For example, if I explain Git to someone as: “Git is a version control system that lets developers track their code changes and collaborate with others.” I get a bored and glazed look every time.
…Okay? Sometimes, learning is boring. Some new things are slog. Cybersecurity training at work sucks but we all do it and we mostly learn from it. Using metaphors about M$ Word and placing blocks in Minecraft won’t ever substitute for using Git.
Sure, sometimes it is. Cybersecurity training is a great example man I hate that stuff and click through as fast as possible without absorbing much. Maybe you enjoy that more than I do.
As for Git specifically, I never said anything about Git itself being boring - my point was more about the terminology that we use to communicate (esp technical terms that seem comfortable to us) and how it translates into the audience’s ability to digest that info.
I don’t think it’s too controversial to say however that Git learning is typically confusing for most new users (not necessarily boring) - there are just a lot of abstract concepts. I think this is also supported by the many experienced devs in this parallel thread on hackernews who have used the same 3 commands for 10 years, although I’m sure they would argue that they just never wanted to learn more than the bare minimum they needed for their workflows, which to me is a little sad.
Anyway, each person is free to use or not use whatever tools/methods they choose, so my goal was just to offer a gamified alternative for whoever finds value in it.
This is interesting, though I find it hard to imagine in action. Is this meant as a general tutorial or visualization of any git repo in a Minecraft-y world, or is it also tracking the state and changes to such a world? It seems like the former, though the latter might be cool to see, and closer to the “track changes” kind of connection with players. I worry it’ll be something like the Library in the game Hack ‘n’ Slash, which contains the game’s own source code, a neat idea but awkward in execution. (Or the branching, time-travelling save state system, similarly.)
Self-indulgent aside, it reminded me of my favorite bit to quote from Johan Georg Raeder’s 1984 thesis Programming in Pictures (pp79-80):
What real-world metaphors can fit programming? To get a feeling for how immense our initial search space is, let us amuse ourselves with a few possibilities. Is a program like a road with intersections and forks where we have to make decisions depending on our current errand, and with roadside inns where we can spend computation time or, if we are careless, completely overflow our stack? Or shall we abolish the ‘meta-view’ and, instead of seeing the program from the sky, put the programmer inside the program by presenting a view of a tunnel he/she can drive through? At each intersection one might have to throw dice or make guesses to introduce some of the challenge, fantasy and curiosity found in computer games. Perhaps we should rather present programs as physical, three-dimensional objects that we can turn around and view from different angles and in different light so as to reveal the various facets of their structure.
A Git tutorial mode where an in-game character walks the player through about 15 levels, and each level focuses on one or more Git concepts/commands. It basically starts from scratch in an empty repo and builds up the respective concepts as you initialize the repo, create files, stage and commit them. Then you build on that to eventually create multiple branches, perform merges, rebases, resets, reverts, and all the common Git operations. The game responds in real time to operations that change the content in the Git repo, but it’s in a linear, happy-path in this mode since it’s meant to be done in a specific way according to the tutorial.
The second mode is more freeform and more likely suited for folks who already have some level of Git experience. It renders your current repo in the game world, so folks who somewhat know what they are doing can get a much more concrete idea of how Git works. You can do a whole bunch of things from within the game world, like write/edit code, simulate and run any Git command, explain difficult code with AI, and as mentioned before all operations are immediately reflected in the world.
I feel that one of the best concepts that Devlands communicates is how branches (and all refs) are just pointers to commits. I find that people really struggle to get that, since conceptually a branch is so clearly evocative of a series of commits, not just a pointer to the first one.
Gorgeous, gorgeous, gorgeous. Imagine all the people (and I’ve been one and tutored a bunch) who would fearfully wonder “what happens when I do this?”, and can now happily wonder “what happens when I do this?”! Just thinking about them is making me happy, I’m sitting here with a literal grin that’s dimpling my cheeks :D
Echoing: The client sends l and then immediately receives an l sent back. I guess the idea here is that the client is really dumb – it doesn’t know that when I type an l, I want an l to be echoed back to the screen. It has to be told explicitly by the server process to display it.
Not just that it’s dumb, but also that it’s on a pretty low-latency link :-). The article doesn’t discuss this topic but it’s actually a pretty interesting historical artefact.
You can have serial terminals echo things locally, too. You press l and the local terminal immediately writes an l, without waiting for the other end to tell it “now show an l”. If you’re on a high-latency link this is pretty useful, because sometimes it can take a long time for all this to go back and forth. It’s even more useful if you’re on a slow link with variable latency.
But it also complicates a bunch of things. E.g. what if you’re on a link that’s not only slow but also a lossy – if you locally echo :wq! at vi‘s prompt, but the w didn’t make it, what do you do about it? It’s also pretty important to be able to switch it on and off on demand for some things, like typing passwords.
if you locally echo :wq! at vi‘s prompt, but the w didn’t make it, what do you do about it?
Did these dumb terminals have a mechanism that performs these types of comparisons to ensure data integrity? I.e. that the user input matches what the server received?
Any chance this could just output the final graph as an SVG. Could be really cool to take an entire repo and just have a zoom-able final output image with literally every commit in a giant web.
I mentioned something very similar in one of my responses above:
Maybe some sort of scrollable, zoomable image output option would be cool for large repos…
I will try to add a feature / command-line option for something very similar to this. For now, the best option is just to run the video of the desired portion of your commit history and take a static screenshot of the desired frame.
This presentation might work for a handful of commits but how does it fare on say the linux kernel or the nixpkgs repo? Is it able to extract some understanding from that torrent of information?
So for now the tool is really designed for a reasonable number of commits on a few branches (this is mentioned in my article and the docs). There are 2 limiting factors for animations at this point:
Manim is generating video, so each element (commit circle, arrow, etc) adds time to generate the output. I’m sure I could optimize it a lot better than I am now, but large commit sequences would take a long time to generate video for. One option for that is to add a feature to export one image of the final result instead of animating, but even so there is only so much you can squeeze in 1 static image. Maybe some sort of scrollable, zoomable image output option would be cool for large repos…
Repos with large and complex branching structures can have many crissy-crossy relationships between commits, so some TLC would need to go into making that look decent. The current logic I’m using wouldn’t scale well to massive and complex repos.
Oh that’s the default animation when creating shapes in Manim and I thought it was pretty sleek, but pretty subjective so I can understand it might annoy some folks.
You could always take a screenshot of the video’s final state which is a zoomed-to-fit frame of the pictured commit sequence.
I’m curious where you’d want to use this project ? With gource I’d say you can have a fun time visualizing what got edited the most (I did actually use that in a presentation once). Like an “interactive flame graph” ? But where do you intend to use this for, when do you want to show specific commits animated like this ? I’m not against “for fun”, it just appears you (and the people upvoting) have a specific use case for this, which I can’t see.
Haha no worries, but if you mentioned it there’s a good possibility other folks out there might feel the same… So whether or not you use it you may get a “–proctrap” command-line option ;)
Yeah, partly it’s for fun after I found out about Manim and thought it would be a fun way to try it out. But I also thought it’s surprising there isn’t a presentation-caliber way to easily generate commit history. “git log –graph” is fine for devs in action but falls pretty short of being good-looking.
One use case would be a team keeping a series of animations that represent their workflow, so that new folks on the team (esp those that might be new to Git) can quickly get up to speed.
Another would be folks who often write Git or other programming tutorials (my website being one example) but are not artistically inclined at all. I cringe at the thought of opening image editing software, which often prevents me from adding visual aids to my stuff. So the ability to generate one-off animations that I can either use as video (or take a screenshot of the final frame for a static version) is very convenient.
Thanks, I can feel the need to create something better than image editing software for visualizing git workflows. Could be interesting for teaching students. Git is still something they only get to know at the last moment, and then it’s everything and the kitchen sink (gitlab, merge requests, approval, CI, CD, rebase-only, milestones..)
you may get a “–proctrap command-line option
I’d be honored, and it would keep the git CLI tradition of using very obscure flags and names ;) (Though then you’d probably have to make the flag change animations to be even slower.)
Looks super cool! I think it complements gource very well. Git-story focuses on commit history, and gource visualizes the file tree structure and contributors. Thanks for sharing!
I love gource. That was the first tool (and most memorable) I’ve used for visualizing data in Git repos. I’m surprised there aren’t more by now for various aspects of the data that Git stores.
I like to visualize my commit history. So I’d use it as prettier alternative to git log. I might also try to use the generated video clip in my programming videos to give a high level overview of my progress.
Working on a Python package called Git Story for Git users to create mp4 video animations of their commit history using a single terminal command within their Git repo.
On the topic of #5 (running commands w/o exiting vim), this is certainly a way to do it, but in my experience, it’s a lot easier to Ctrl+Z and background the vim job and do my stuff there. That said, this command is super useful when combined with :r, :r!ls will run ls, and then paste the contents into your file. It’s a nice way of pulling data into somewhere where you can screw around with it, a little bit quicker than dropping to the CL and dumping the content into a file where you can edit it.
Thank you and good points! When I first started using the command line I remember learnings about backgrounding tasks but for whatever reason, it didn’t become a long term habit for me. I can’t really explain why though. Nice point about adding the command ouput into the file to play around with!
Another place where the use of imperative mood makes sense is in option descriptions that you get in --help output for commands. It’s often the shortest form, not only in English but also many other languages. And other forms can be clumsier with regard to whether the command, the option or the human is doing the action. It allows you to leave out the subject of the sentence but still have a valid sentence.
Yes. And this reminds me of a comment from Reddit:
“You wouldn’t name a function madeWidget or addedBarToFoo. You’d say make or add. Because you’re not describing what you did. You’re describing what the thing you made does. A commit is a thing you made. Every time someone applies it, it’s going to do something”
I’m reminded of once reading about a team that set up their computers to take a webcam snapshot of the developer’s expression (face) when a git conflict occurred.
…Okay? Sometimes, learning is boring. Some new things are slog. Cybersecurity training at work sucks but we all do it and we mostly learn from it. Using metaphors about M$ Word and placing blocks in Minecraft won’t ever substitute for using Git.
why can’t learning be fun?
Sure, sometimes it is. Cybersecurity training is a great example man I hate that stuff and click through as fast as possible without absorbing much. Maybe you enjoy that more than I do.
As for Git specifically, I never said anything about Git itself being boring - my point was more about the terminology that we use to communicate (esp technical terms that seem comfortable to us) and how it translates into the audience’s ability to digest that info.
I don’t think it’s too controversial to say however that Git learning is typically confusing for most new users (not necessarily boring) - there are just a lot of abstract concepts. I think this is also supported by the many experienced devs in this parallel thread on hackernews who have used the same 3 commands for 10 years, although I’m sure they would argue that they just never wanted to learn more than the bare minimum they needed for their workflows, which to me is a little sad.
Anyway, each person is free to use or not use whatever tools/methods they choose, so my goal was just to offer a gamified alternative for whoever finds value in it.
This is interesting, though I find it hard to imagine in action. Is this meant as a general tutorial or visualization of any git repo in a Minecraft-y world, or is it also tracking the state and changes to such a world? It seems like the former, though the latter might be cool to see, and closer to the “track changes” kind of connection with players. I worry it’ll be something like the Library in the game Hack ‘n’ Slash, which contains the game’s own source code, a neat idea but awkward in execution. (Or the branching, time-travelling save state system, similarly.)
Self-indulgent aside, it reminded me of my favorite bit to quote from Johan Georg Raeder’s 1984 thesis Programming in Pictures (pp79-80):
Thanks for the thoughtful comment!
So it currently runs in 2 modes:
A Git tutorial mode where an in-game character walks the player through about 15 levels, and each level focuses on one or more Git concepts/commands. It basically starts from scratch in an empty repo and builds up the respective concepts as you initialize the repo, create files, stage and commit them. Then you build on that to eventually create multiple branches, perform merges, rebases, resets, reverts, and all the common Git operations. The game responds in real time to operations that change the content in the Git repo, but it’s in a linear, happy-path in this mode since it’s meant to be done in a specific way according to the tutorial.
The second mode is more freeform and more likely suited for folks who already have some level of Git experience. It renders your current repo in the game world, so folks who somewhat know what they are doing can get a much more concrete idea of how Git works. You can do a whole bunch of things from within the game world, like write/edit code, simulate and run any Git command, explain difficult code with AI, and as mentioned before all operations are immediately reflected in the world.
I feel that one of the best concepts that Devlands communicates is how branches (and all refs) are just pointers to commits. I find that people really struggle to get that, since conceptually a branch is so clearly evocative of a series of commits, not just a pointer to the first one.
Very sad to hear this. I love Vim. A great tool for curious people who love learning seemingly endless new things. Thank you for everything Bram.
He could save others from exiting, but not himself. Ironic.
Rest in peace Bram.
ZZAt one point or another we will all :wq
Sadly for some people it looks more like :q!
Gorgeous, gorgeous, gorgeous. Imagine all the people (and I’ve been one and tutored a bunch) who would fearfully wonder “what happens when I do this?”, and can now happily wonder “what happens when I do this?”! Just thinking about them is making me happy, I’m sitting here with a literal grin that’s dimpling my cheeks :D
Thank you! Yes, I feel the same way, learning/using GIt should be a playfully curious endeavor, not a fearful one!
That sounds amazing and I need to test it immediately
Please do. Let me know any issues/thoughts/suggestions you might have :D
Not just that it’s dumb, but also that it’s on a pretty low-latency link :-). The article doesn’t discuss this topic but it’s actually a pretty interesting historical artefact.
You can have serial terminals echo things locally, too. You press
land the local terminal immediately writes anl, without waiting for the other end to tell it “now show anl”. If you’re on a high-latency link this is pretty useful, because sometimes it can take a long time for all this to go back and forth. It’s even more useful if you’re on a slow link with variable latency.But it also complicates a bunch of things. E.g. what if you’re on a link that’s not only slow but also a lossy – if you locally echo
:wq!atvi‘s prompt, but thewdidn’t make it, what do you do about it? It’s also pretty important to be able to switch it on and off on demand for some things, like typing passwords.Did these dumb terminals have a mechanism that performs these types of comparisons to ensure data integrity? I.e. that the user input matches what the server received?
No, that’s the point: they only echoed what the server sent back, and the server echoes back every input too
Any chance this could just output the final graph as an SVG. Could be really cool to take an entire repo and just have a zoom-able final output image with literally every commit in a giant web.
I mentioned something very similar in one of my responses above:
I will try to add a feature / command-line option for something very similar to this. For now, the best option is just to run the video of the desired portion of your commit history and take a static screenshot of the desired frame.
For sure. Mostly is useful from a time perspective. No need to render a ton of video just to get the last frame.
Also, the second gain of that if it can be SVG, it won’t be pixelated.
Yeah definitely agree. That’s just the “workaround” for now haha. Thanks for the suggestion :)
This presentation might work for a handful of commits but how does it fare on say the linux kernel or the nixpkgs repo? Is it able to extract some understanding from that torrent of information?
So for now the tool is really designed for a reasonable number of commits on a few branches (this is mentioned in my article and the docs). There are 2 limiting factors for animations at this point:
Manim is generating video, so each element (commit circle, arrow, etc) adds time to generate the output. I’m sure I could optimize it a lot better than I am now, but large commit sequences would take a long time to generate video for. One option for that is to add a feature to export one image of the final result instead of animating, but even so there is only so much you can squeeze in 1 static image. Maybe some sort of scrollable, zoomable image output option would be cool for large repos…
Repos with large and complex branching structures can have many crissy-crossy relationships between commits, so some TLC would need to go into making that look decent. The current logic I’m using wouldn’t scale well to massive and complex repos.
If you want to try an unreasonable number of commits on a very reasonable number of branches, check out void-packages
Haha thanks for that I’ll take a peek O.o
The slow circle animation would annoy me very fast if this is used for a presentation
Oh that’s the default animation when creating shapes in Manim and I thought it was pretty sleek, but pretty subjective so I can understand it might annoy some folks.
You could always take a screenshot of the video’s final state which is a zoomed-to-fit frame of the pictured commit sequence.
Or I could add a new feature to adjust tweak that… if only I had the details in a GitHub issue… https://github.com/initialcommit-com/git-story
Wait, stop. I’m the passerby that won’t use it ;)
I’m curious where you’d want to use this project ? With gource I’d say you can have a fun time visualizing what got edited the most (I did actually use that in a presentation once). Like an “interactive flame graph” ? But where do you intend to use this for, when do you want to show specific commits animated like this ? I’m not against “for fun”, it just appears you (and the people upvoting) have a specific use case for this, which I can’t see.
Haha no worries, but if you mentioned it there’s a good possibility other folks out there might feel the same… So whether or not you use it you may get a “–proctrap” command-line option ;)
Yeah, partly it’s for fun after I found out about Manim and thought it would be a fun way to try it out. But I also thought it’s surprising there isn’t a presentation-caliber way to easily generate commit history. “git log –graph” is fine for devs in action but falls pretty short of being good-looking.
One use case would be a team keeping a series of animations that represent their workflow, so that new folks on the team (esp those that might be new to Git) can quickly get up to speed.
Another would be folks who often write Git or other programming tutorials (my website being one example) but are not artistically inclined at all. I cringe at the thought of opening image editing software, which often prevents me from adding visual aids to my stuff. So the ability to generate one-off animations that I can either use as video (or take a screenshot of the final frame for a static version) is very convenient.
Thanks, I can feel the need to create something better than image editing software for visualizing git workflows. Could be interesting for teaching students. Git is still something they only get to know at the last moment, and then it’s everything and the kitchen sink (gitlab, merge requests, approval, CI, CD, rebase-only, milestones..)
I’d be honored, and it would keep the git CLI tradition of using very obscure flags and names ;) (Though then you’d probably have to make the flag change animations to be even slower.)
Looks super cool! I think it complements gource very well. Git-story focuses on commit history, and gource visualizes the file tree structure and contributors. Thanks for sharing!
I love gource. That was the first tool (and most memorable) I’ve used for visualizing data in Git repos. I’m surprised there aren’t more by now for various aspects of the data that Git stores.
This is amazing! I’ve always been on the lookout for a similar tool and I’m glad I found it today. Thanks for you work!
Woohoo! :D
Out of curiosity what do you plan to use it for?
I like to visualize my commit history. So I’d use it as prettier alternative to
git log. I might also try to use the generated video clip in my programming videos to give a high level overview of my progress.Sweet! Would love to get your feedback after you test it out, and am happy to help if you run into any issues.
Working on a Python package called Git Story for Git users to create mp4 video animations of their commit history using a single terminal command within their Git repo.
Anyone wanna help me test it?
I just wanted to say that this article was well-written. I had been meaning to learn about Pijul and this was a good starting point.
Pedantic: I think there is a small typo where there should be a line-break before the
pijul recordcommand to separate it frompijul ls.Thx very much! It was very fun to learn about Pijul and work on the article, so glad it was useful. The typo should be fixed as well ;)
On the topic of #5 (running commands w/o exiting vim), this is certainly a way to do it, but in my experience, it’s a lot easier to
Ctrl+Zand background the vim job and do my stuff there. That said, this command is super useful when combined with:r,:r!lswill runls, and then paste the contents into your file. It’s a nice way of pulling data into somewhere where you can screw around with it, a little bit quicker than dropping to the CL and dumping the content into a file where you can edit it.Otherwise great tips!
Thank you and good points! When I first started using the command line I remember learnings about backgrounding tasks but for whatever reason, it didn’t become a long term habit for me. I can’t really explain why though. Nice point about adding the command ouput into the file to play around with!
Some of these I didn’t know, so it got my upvote.
Glad to hear it :D
Surprised they didn’t include bat, one of my favourite “modern” tools.
I just installed this after some recommendations in the Reddit comments and so far it seems really cool!!
If you like it, check out other tools by the author - fd, hyperfine, hexyl, etc
https://github.com/sharkdp?tab=repositories
Another place where the use of imperative mood makes sense is in option descriptions that you get in
--helpoutput for commands. It’s often the shortest form, not only in English but also many other languages. And other forms can be clumsier with regard to whether the command, the option or the human is doing the action. It allows you to leave out the subject of the sentence but still have a valid sentence.Yes. And this reminds me of a comment from Reddit:
“You wouldn’t name a function madeWidget or addedBarToFoo. You’d say make or add. Because you’re not describing what you did. You’re describing what the thing you made does. A commit is a thing you made. Every time someone applies it, it’s going to do something”
My top requirement for a commit message is that I be able to understand it a month from now.
Hehe yes that is certainly an important requirement!
What about performing sentiment analysis on all those commit logs?
Haha I’d think most commit messages would be a little too dry/robotic to get a good sentiment reading on? What do you think?
I’m reminded of once reading about a team that set up their computers to take a webcam snapshot of the developer’s expression (face) when a git conflict occurred.
Well… I was bored the other day which led me to just posting this… https://lobste.rs/s/0zxoap/suggested_improvements_for_tool