This looks promising as a teaching aide. At my previous company, I transitioned our project from Clearcase to Git to save us licensing and administration fees. Many of the senior developers, who had never used Git, had a hard time understanding it, and I spent many whiteboard sessions explaining by drawing similar graphs. This would give those developers more autonomy, and stop the “let me blow it away and start over”, which would drive me nuts. Devs spent a lot of time and frustration performing that operation.
I believe the core issue is devs like above never take the time to “grok” Git. I believe part of this is due to the lack of a tool like above to teach easily, but also because devs want to ignore the “how” of their tool working to find out the exact commands they need to run in their current situation.
One could argue users should not need to understand how their tool works to use it effectively and this is a leaky abstraction. Others could argue some commands are not intuitive (git reset can do many things, and git rebase swapping ours/theirs comes to mind). I don’t claim Git is perfect, and sometimes I need to Google to learn more than I wanted to, to get out of an obscure scenario (e.g. someone put classified intelligence into a repository we need to transfer to a lower classification network; how do I rewrite the entire history while correcting this error that occurred 487 commits ago?). However, understanding the tree structure of Git, what git rebase does under the covers, what branches and tags are, how remotes work, how merging works, etc. would go a LONG way. The folk I worked with struggled to pick it up.
> I believe the core issue is devs like above never take the time to “grok” Git.
The problem I have with git us that it's just too complicated. When I'm juggling project complexities and design complexities and implementation complexities, I frequently don't want to have to deal with git too.
I understand how to stage and check in and squash, and branch and merge, and how to manage remotes. But last week I still managed to get a new repo into a state where I couldn't push local changes to github without doing a pull first, and I couldn't do a pull without (apparently) first updating the remote. I had a hard deadline and ended up deleting the repo and starting fresh. Nothing much was lost. I never had this trouble with tfs...
Maybe I'm just not clever enough, but I've never come across a dev tool with as much surface complexity as git.
(Not a git hater. Use it every day. Have had a personal github profile for a decade. Etc etc.)
I've resigned myself to accepting git because I have to use it. But JFC, I've hated it from the first time I tried it.
We now have a large selection of tools that allow you to visualize what's going on (I use git-kraken), as well as google for help on doing something that isn't in muscle memory.
But, really, SO MUCH pain and suffering could have been resolved by refactoring the damn commands to something more coherent and consistent. Git people sometimes call this "porcelain"-- which I guess is an apt name because it makes one think of a toilet (but an improvement to a hole in the ground).
I teach git professionally. I have a 3-day 12-hour course I give.
I'm amazed how many people who have used SVN or CVS just assume git works like that but with different commands. And, of course, they get very screwed up. (GitHub contributes to this problem, too, with their own set of commands like "forks" and "pull requests" that aren't really a part of git.)
One you understand the Merkle DAG that's at the heart of git, understanding the rest is simple. Yes the commands are named badly, but get past that and it's a great system.
It is not outside the realm of possibility that Github itself had a problem. I've seen instances where "git fetch" pulls refs but not the objects pointed to by the refs, then it gets cleared up an hour later and my builds suddenly start working again.
It's almost pure happenstance that Linus's idea of Git being distributed lent itself to the Cloud hosting business model. And the hardest thing to teach is the mental mapping of local and remote refs.
So this isn't just Git being too complicated. It's a confluence of several factors that would never have been possible if Git had never happned.
One thing to remember is that a pull is fetch + merge. I always fetch first which doesn't change any local branches. If that doesn't work fix your remotes. You can always recreate your local branches to track remotes, then reset to specific git hashes (if you take note of them or give them temp branch names).
> I believe the core issue is devs like above never take the time to “grok” Git. I believe part of this is due to the lack of a tool like above to teach easily, but also because devs want to ignore the “how” of their tool working to find out the exact commands they need to run in their current situation.
Github is largely to "blame" for this. It mostly only exposes the happy path and using git kind of like any other VCS, but above all it ossifies the idea of git repositories being centralized (both because the canonical repo is always on github.com but also because of the forking/ownership model). A lot of the power (and sharp edges, and messiness) of git are in scenarios where everybody has a local repo and nobody's is really "canonical".
Git is really well-suited to development of the linux kernel. It's not.. amazingly well-suited for the job that 95% of people these days press it into?
I think that the bigger problem is the misuse of Tags as the sole method of marking a commit for release for example.
Tags could be utilised for naming commits which would make it much easier to reason about where in the process of your development you are instead of referencing commits by hash. Hashes are hard to remember after all.
I agree with your position. Our use case at the company I mentioned above was ten developers, all physically co-located, actually all operating on the same 3 or 4 servers. A centralized VCS was a better fit to our development needs. In situations where the problem space is centralized, applying a distributed tool is using the wrong tool for the job.
> I believe the core issue is devs like above never take the time to “grok” Git
I believe the same, and it's not just a problem you see with git, it's all over the place. Some developers seems eager to use something so they just skim the documentation in order to do the least amount of reading and understanding in order to implement something, but often miss some fundamental detail and have to jump back. Or, they fundamentally misunderstand the tool at all, but push forward with their own idea what the tool is, rather than stepping back and start learning again.
You say that like it's bad, but that's just life. We're trying to fit a whole universe into 3 pounds of meat. If we stopped to truly understand anything before taking action, we'd never get anywhere.
That's especially true in technology, where whole armies of people are working to complicate things as fast as possible. For the best of reasons, of course. But when I started out, I could read one short book and have a pretty good understanding of my computer's processor, and from there it wasn't much further to understanding the whole computer. Now I could spend days just understanding, say, processor cache strategies [1]. A field that is super interesting, but if I am to get any of my actual work done, I can't afford to dig into that and the many, many other similar subtopics. I'm going to get a casual understanding of something, do my best to make something useful, and only dig in further when I'm forced to.
When I do have to dig in, it comes in two cases for me. One is where there is something necessary complexity that I would have to learn about regardless. E.g., if something is too slow, I need to learn about what happens under the hood to do proper performance tuning. Great, fine, I will learn it.
But then there's the other bucket, which includes unnecessary complexity, bad abstractions, poorly considered UX, and the like. For me, git is clearly in that bucket. I intentionally have very simple development flows. Git can do a great deal, 98% of which I not only don't need, I actively don't want. [2] So I'm going do my best to remain ignorant of its inner workings, stick with my small number of commands, and very occasionally refer to "Oh Shit, Git!?!" [3] And I'm perfectly happy with that until it gets replaced with a technology that better matches the domain.
I'm very happy to fundamentally misunderstand GIT's internals because I want to do a finite (and small) set of operations with it, not HOW it operates under the covers.
Conflating the two, like you do, is elitism.
"If you just stopped and read to understand...", a-ha, sure, I'll do that for every one of the no less than 500 tools I've used over the course of my career and will never get anything done on time.
There's no time. We got real work to do and no we can't switch to a company that gives us this time. There's a big world outside the Silicon Valley.
GIT is a huge UX failure and seeing people pretend otherwise makes me question my -- or their -- sanity.
I've seen this phenomenon as well. I've noticed a few factors that I hypothesize contribute to this:
1) Making Computer Science programs in universities overly simple. When I was in college, I tutored students in CS. When I started college, the CS 101 course was taught in Java, and when I finished, it was being taught in Python. There was an immense gap between the understanding of the Python-first vs. Java-first students.
The Java-first students understood fundamental concepts like arrays, passing parameters by reference vs. by value, "OOP" concepts, and other common paradigms in languages. The Python-first students would use "lists" and "dictionaries" for many problems without understanding that those structures impacted the time complexity of their solutions, or that they used memory allocation, reallocation, hashing, etc. Python is great for hacking together a non-fault-tolerant program that does X as quickly as possible, but I saw it damage the way the students thought about computing.
It made the students think it ought to be easy. It made them think that they should be able to write, in nearly plain English, what they wanted the computer to do, and that it ought to do it. It made them think they should be able to intuitively be able to code without spending any amount of time learning the craft, and that they could do anything an advanced programmer could do by typing a few lines of simple code. They were less willing to accept that sometimes problems are hard, sometimes they would have to think, and sometimes they would have to write more than a for loop to solve problems. The Java students' problem sets covered implementation of data structures and complex applications, while the Python students struggled to put together even the implementation.
For a humorous and broader explanation of this subject, see James Mickens' excellent article The Night Watch [0]. For example: "That being said, if you find yourself drinking a martini and writing programs in garbage-collected, object-oriented Esperanto, be aware that the only reason that the Esperanto runtime works is because there are systems people who have exchanged any hope of losing their virginity for the exciting opportunity to think about hex numbers and their relationships with the operating system, the hardware, and ancient blood rituals that Bjarne Stroustrup performed at Stonehenge."
2) Bad documentation, and bad users of documentation. I dislike documentation that neglects how the tool works and instead creates a cookbook that its users can copy verbatim. It has similar effects to what I described above. Developers that use this type of documentation find themselves helpless when they encounter a problem they've not memorized the solution to. I think it also creates a learned helplessness wherein users cannot question the model the tool uses or think outside that model to solve complex problems. I prefer documentation that teaches the ethos of the subject in question so that I can understand better and imagine new solutions.
I've also heard the complaint that Git's documentation is awful; some say that it is only useful if you know already know where what you are looking for is, and useless if not. In other words, it lacks an "apropos" (aka "man -k") equivalent. This is my gripe with "wiki" style documentation. It is scattered and unsearchable and has no cohesion. We as developers need to do a better job creating documentation that is searchable, coherent, and useful to new and experienced users alike. Various sections of documentation should have ample cross-references to help users understand the connection between parts of the system to help them form a mental model of how tooling works.
Git is an amazing tool with terrible UX. It's very difficult to know what the right thing to do is and the mental model is a bit weird. For example, undoing an operation is another, new commit.
That is the option of last resort, when you have already pushed _and_ you cannot mess with the history anymore.
The other one being reseting your local branch to a previous commit and force pushing if needed.
I learned git at 45yo after many years using ClearCase (even licensed as CC admin) and .. I really liked learning git, I do admit that it took me two full days of self study to start groking git but I wouldn't call it 'struggling'.
Obviously it depends a lot of your background.. git is the 5th version controls I've used , while it is far from being perfect (submodules.. :-( ), it's my favourite.
Were you trying to teach them with the CLI though? That's a terrible approach. The CLI is awful and Git is a visual thing.
It's like teaching someone to drive a car using LOGO.
The way to teach Git is:
1. Explain the mental model (correctly). Basically a commit is a snapshot with deduplication to avoid huge file sizes.
2. Show them how to use a good Git GUI. There are a lot of bad ones. I would recommend Git Extensions (terrible name but it's actually quite good). Or maybe GitX on Mac.
3. Let them learn the CLI slowly in their own time.
I never found a GUI that was more intuitive than the CLI, personally. I am a bad person to consult for this, since I live in vim and tmux (my coworkers hid my mouse for April Fool’s Day and I went the day without it to make a point) while others blaze ahead in VS Code and know the bare minimum command line to get their job done.
I’ll take a look at Git Extensions, thanks for the recommendation! Some of our devs took to using the integration with VS Code, which I didn’t like because I didn’t understand how its terminology (e.g. “sync” mapped to underlying Git operations). Others tried the Git GUI which I found very confusing.
I focused on the graphical operations and then tried to show them what commands they could run to execute those operations. Next time I’m in the situation, maybe I’ll adopt a GUI-first approach.
The problem is that every git UI I've tried of the past ~10 years abstracts core concepts in order to (try to) simplify things, then people make a mess and don't have the slightest clue why or how to fix it.
The git CLI for the vast majority of things isn't difficult once you have a basic understanding of DVCS. 95% of the time fetch, pull, push, checkout and commit are all you need.
I admit that Hg had a far nicer an more consistent CLI, and it was my preference back in the day. But it lost for a few reasons - one of which was that it made the 90% easier, but the 10% far harder.
Terrible advice, you should absolutely start with the official UI, which is the CLI. Avoiding it because "it's hard" will just complicate everything down the line.
A big reason I wanted to pursue this idea is exactly what you mentioned - a lack of ability to easily create presentation-quality Git structures that can apply specifically to the situation a user is in, NOW.
A super annoying thing about troubleshooting Git issues is when you find a similar solution online but it's done in someone's random repo which could be very different that yours. Your whiteboard sessions are another good example down this line of thought.
More like a backed-up abstraction, simpler on the inside.
Though that's only true of the core, with tags being additional decorations and renames inferred. The simple core delegates complexity.
I think designing a nicer git UX is not easy. Even if we oversimplify commit to cp your working directory together with a path to the previous commit (to form a tree of "branches"), then the abstraction for operations like rebase to manipulate that tree is not quite intrinsically simple.
BTW Tools can be used without proper understanding, like arithmetic without commuting, associating or distributing. While a workable pidgin aids adoption, it's fair to argue for the power of understanding, especially of something clean and coherent and whole. Git's core is like that; the add-ons (like tags) aren't; and the UX seems arbitrary and accreted.
My company is currently transitioning from a 20+ year old Perforce depot to a git workflow. We're certainly having issues like you describe, where people don't know (and don't care to learn) the mechanics of git. And I agree, git is the kind of tool where once you understand the primitives, you can quickly start making lateral leaps to solve problems.
But I do think that there's room for a better mechanism for orchestrating "macros" or building other workflows on top of git. I know a lot of developers who'd love the ability to pretend they're using p4.
My company wanted to "script away" all the "pain" of using Git to make it equivalent to Clearcase. I think it's a smell. If you want to use Clearcase, use Clearcase. etc.
This is why I'm in love with Mercurial. It has a very simple mental model which is not far from Git, but Mercurial's commands and presentation are so much more comprehensible.
Every time I see a thread like this I echo the same sentiments. It’s not hard to grok how hg works, git adds more mental cycles which just take away from solving the actual problem at hand
I want to pile on here; I switched to Mercurial for some projects and didn't think much of it (had to look up equivalents of some git commands here and there). However, after 2 years of that, coming back to git made me feel like a total newbie. I recently got myself into a detached HEAD state and felt like I was groping in the dark with "git reset". I never had this issue with mercurial, even with weird botched evolve/content-divergent states.
> Heptapod is a community driven effort to bring Mercurial SCM support to GitLab™, started by Octobus, a company providing professional services around Mercurial.
I really like git. I like teaching it to my fellow developers, I frequenty use git cherry-pick, git rebase, multiple remotes, submodules, ontop of the usual "common" git stuff.
I found GitExtensions (windows) which I used at my last job to be VERY useful, as it is git, properly, the way it was designed, but in GUI format. It taught me a lot about how to actually use git.
Now I dont use the GUI, its too slow to click around when I know the command.
I dont get the git hate. Then again, I also dont get the "C++ is too complex/complicated" debate, either, so maybe I just have a higher tolerance for terrible design.
Or maybe git just is a very powerful tool and takes more than half a year of half-assed use to learn.
Teaching some basic things like rebase vs. merge, how to git bisect, how to pull with rebase, update a branch with rebase before merging it, stashing changes, etc. got me and the team I lead at $CURRENT_WORKPLACE very, very far.
I can recommend to stop complaining about git, find someone who knows how to use it, and just ask until you get it. Its worth it
> Or maybe git just is a very powerful tool and takes more than half a year of half-assed use to learn.
And also distributed version control is complicated. Git isn't as intuitive on the happy paths as perhaps it could have been and shows its slightly rushed initial development, but no tool that allows such flexibility can ever be truly simple. And in its defense, it wasn't originally designed to be a super-simple glossy tool. The technical advantages of it simply outweighed the slightly clunky interface, and that interface has improved since then.
I do recommend to use the "git lola" alias to give an easy gestalt of the repo state if you're ever unsure what's going on.
It doesn't matter how much I look at them, and I get the reasoning, but the right->left flow orientation of VCS diagrams will always be disorienting for me.
1. In the static output, put a dashed, or shadowed marker corresponding "frame 0" of the animation, e.g. in the git reset example, show where "HEAD" was before (perhaps even add an arrow)
2. Make it possible to 'remember' a set progress, of git commands - and replay them. (I.e. simulation looks ok, now apply them on real git)
3. Make it possible to visualize actual git log in the same style as simulation.
I generally have a good mental model of my repo and I try to KISS as much as possible, but I can see the value of this in a teaching scenario, for example (as well as on extremely complex git situations).
Check out the quickstart page as well, seems to have more content[1].
Haha wow you posted this before I could! I created Git-Sim and hope that folks can get some use and value out of it. Happy to answer any questions anyone might have, and especially looking for feedback so that I can improve the tool. Also if anyone is interested in contributing let me know and also check out the project Github page:
Alternative would be: clone the repo, do your changes, run gitk to be sure.
Which has advantage that result looks exactly the same as it will in production (no new diagram type b/c only using git and gitk), with zero risk that sim differs from reality.
Hehe jk you make a fair point, and in fact I do have a bunch of work left to do to make sure my simulations do match up with Git's behavior as closely as possible.
One big benefit I was going for with Git-Sim though is to interrupt the developer workflow as little as possible.
Changing directories, running a new clone (which could take a mildly annoying amount of time), and running gitk is a pretty big context-switch.
I'm really missing support for remotes. There are lots of tools for local-only development (like https://gitexercises.fracz.com/), but very few allow to demonstrate stuff like "Syncing a GitHub fork with the original repository" which involves two remotes and three copies of the same branch at the very least.
This is a great point. I thought about how I could simulate commands like "git pull" and "git push", but like you said that would require communicating with the remote to determine ... stuff ... like what objects need to be synched, and potentially even doing some of the actual data transfer before an accurate simulation would be possible.
My initial goals for this tool are to purely simulate actions on Git repos without actually modifying them, but I might be flexible on that going forward, as I mention in the article with the --execute flag.
> simulate actions on Git repos without actually modifying them
One way around this could be to create a new temporary directory in /tmp, copy .git over there and symlink the rest, then run whatever operation in the newly copied workspace and compare it with the original.
Then you can mutate things however you want and the original stays the same.
Readit News
I believe the core issue is devs like above never take the time to “grok” Git. I believe part of this is due to the lack of a tool like above to teach easily, but also because devs want to ignore the “how” of their tool working to find out the exact commands they need to run in their current situation.
One could argue users should not need to understand how their tool works to use it effectively and this is a leaky abstraction. Others could argue some commands are not intuitive (git reset can do many things, and git rebase swapping ours/theirs comes to mind). I don’t claim Git is perfect, and sometimes I need to Google to learn more than I wanted to, to get out of an obscure scenario (e.g. someone put classified intelligence into a repository we need to transfer to a lower classification network; how do I rewrite the entire history while correcting this error that occurred 487 commits ago?). However, understanding the tree structure of Git, what git rebase does under the covers, what branches and tags are, how remotes work, how merging works, etc. would go a LONG way. The folk I worked with struggled to pick it up.
The problem I have with git us that it's just too complicated. When I'm juggling project complexities and design complexities and implementation complexities, I frequently don't want to have to deal with git too.
I understand how to stage and check in and squash, and branch and merge, and how to manage remotes. But last week I still managed to get a new repo into a state where I couldn't push local changes to github without doing a pull first, and I couldn't do a pull without (apparently) first updating the remote. I had a hard deadline and ended up deleting the repo and starting fresh. Nothing much was lost. I never had this trouble with tfs...
Maybe I'm just not clever enough, but I've never come across a dev tool with as much surface complexity as git.
(Not a git hater. Use it every day. Have had a personal github profile for a decade. Etc etc.)
We now have a large selection of tools that allow you to visualize what's going on (I use git-kraken), as well as google for help on doing something that isn't in muscle memory.
But, really, SO MUCH pain and suffering could have been resolved by refactoring the damn commands to something more coherent and consistent. Git people sometimes call this "porcelain"-- which I guess is an apt name because it makes one think of a toilet (but an improvement to a hole in the ground).
I'm amazed how many people who have used SVN or CVS just assume git works like that but with different commands. And, of course, they get very screwed up. (GitHub contributes to this problem, too, with their own set of commands like "forks" and "pull requests" that aren't really a part of git.)
One you understand the Merkle DAG that's at the heart of git, understanding the rest is simple. Yes the commands are named badly, but get past that and it's a great system.
It's almost pure happenstance that Linus's idea of Git being distributed lent itself to the Cloud hosting business model. And the hardest thing to teach is the mental mapping of local and remote refs.
So this isn't just Git being too complicated. It's a confluence of several factors that would never have been possible if Git had never happned.
Github is largely to "blame" for this. It mostly only exposes the happy path and using git kind of like any other VCS, but above all it ossifies the idea of git repositories being centralized (both because the canonical repo is always on github.com but also because of the forking/ownership model). A lot of the power (and sharp edges, and messiness) of git are in scenarios where everybody has a local repo and nobody's is really "canonical".
Git is really well-suited to development of the linux kernel. It's not.. amazingly well-suited for the job that 95% of people these days press it into?
Tags could be utilised for naming commits which would make it much easier to reason about where in the process of your development you are instead of referencing commits by hash. Hashes are hard to remember after all.
I believe the same, and it's not just a problem you see with git, it's all over the place. Some developers seems eager to use something so they just skim the documentation in order to do the least amount of reading and understanding in order to implement something, but often miss some fundamental detail and have to jump back. Or, they fundamentally misunderstand the tool at all, but push forward with their own idea what the tool is, rather than stepping back and start learning again.
That's especially true in technology, where whole armies of people are working to complicate things as fast as possible. For the best of reasons, of course. But when I started out, I could read one short book and have a pretty good understanding of my computer's processor, and from there it wasn't much further to understanding the whole computer. Now I could spend days just understanding, say, processor cache strategies [1]. A field that is super interesting, but if I am to get any of my actual work done, I can't afford to dig into that and the many, many other similar subtopics. I'm going to get a casual understanding of something, do my best to make something useful, and only dig in further when I'm forced to.
When I do have to dig in, it comes in two cases for me. One is where there is something necessary complexity that I would have to learn about regardless. E.g., if something is too slow, I need to learn about what happens under the hood to do proper performance tuning. Great, fine, I will learn it.
But then there's the other bucket, which includes unnecessary complexity, bad abstractions, poorly considered UX, and the like. For me, git is clearly in that bucket. I intentionally have very simple development flows. Git can do a great deal, 98% of which I not only don't need, I actively don't want. [2] So I'm going do my best to remain ignorant of its inner workings, stick with my small number of commands, and very occasionally refer to "Oh Shit, Git!?!" [3] And I'm perfectly happy with that until it gets replaced with a technology that better matches the domain.
[1] e.g.: https://chipsandcheese.com/2022/05/21/igpu-cache-setups-comp...
[2] An example of what I don't want: https://www.tiktok.com/t/ZTRpPPuKf/
[3] https://ohshitgit.com/
Conflating the two, like you do, is elitism.
"If you just stopped and read to understand...", a-ha, sure, I'll do that for every one of the no less than 500 tools I've used over the course of my career and will never get anything done on time.
There's no time. We got real work to do and no we can't switch to a company that gives us this time. There's a big world outside the Silicon Valley.
GIT is a huge UX failure and seeing people pretend otherwise makes me question my -- or their -- sanity.
1) Making Computer Science programs in universities overly simple. When I was in college, I tutored students in CS. When I started college, the CS 101 course was taught in Java, and when I finished, it was being taught in Python. There was an immense gap between the understanding of the Python-first vs. Java-first students.
The Java-first students understood fundamental concepts like arrays, passing parameters by reference vs. by value, "OOP" concepts, and other common paradigms in languages. The Python-first students would use "lists" and "dictionaries" for many problems without understanding that those structures impacted the time complexity of their solutions, or that they used memory allocation, reallocation, hashing, etc. Python is great for hacking together a non-fault-tolerant program that does X as quickly as possible, but I saw it damage the way the students thought about computing.
It made the students think it ought to be easy. It made them think that they should be able to write, in nearly plain English, what they wanted the computer to do, and that it ought to do it. It made them think they should be able to intuitively be able to code without spending any amount of time learning the craft, and that they could do anything an advanced programmer could do by typing a few lines of simple code. They were less willing to accept that sometimes problems are hard, sometimes they would have to think, and sometimes they would have to write more than a for loop to solve problems. The Java students' problem sets covered implementation of data structures and complex applications, while the Python students struggled to put together even the implementation.
For a humorous and broader explanation of this subject, see James Mickens' excellent article The Night Watch [0]. For example: "That being said, if you find yourself drinking a martini and writing programs in garbage-collected, object-oriented Esperanto, be aware that the only reason that the Esperanto runtime works is because there are systems people who have exchanged any hope of losing their virginity for the exciting opportunity to think about hex numbers and their relationships with the operating system, the hardware, and ancient blood rituals that Bjarne Stroustrup performed at Stonehenge."
2) Bad documentation, and bad users of documentation. I dislike documentation that neglects how the tool works and instead creates a cookbook that its users can copy verbatim. It has similar effects to what I described above. Developers that use this type of documentation find themselves helpless when they encounter a problem they've not memorized the solution to. I think it also creates a learned helplessness wherein users cannot question the model the tool uses or think outside that model to solve complex problems. I prefer documentation that teaches the ethos of the subject in question so that I can understand better and imagine new solutions.
I've also heard the complaint that Git's documentation is awful; some say that it is only useful if you know already know where what you are looking for is, and useless if not. In other words, it lacks an "apropos" (aka "man -k") equivalent. This is my gripe with "wiki" style documentation. It is scattered and unsearchable and has no cohesion. We as developers need to do a better job creating documentation that is searchable, coherent, and useful to new and experienced users alike. Various sections of documentation should have ample cross-references to help users understand the connection between parts of the system to help them form a mental model of how tooling works.
[0]: https://www.usenix.org/system/files/1311_05-08_mickens.pdf
Edit: wording
I learned git at 45yo after many years using ClearCase (even licensed as CC admin) and .. I really liked learning git, I do admit that it took me two full days of self study to start groking git but I wouldn't call it 'struggling'.
Obviously it depends a lot of your background.. git is the 5th version controls I've used , while it is far from being perfect (submodules.. :-( ), it's my favourite.
It's like teaching someone to drive a car using LOGO.
The way to teach Git is:
1. Explain the mental model (correctly). Basically a commit is a snapshot with deduplication to avoid huge file sizes.
2. Show them how to use a good Git GUI. There are a lot of bad ones. I would recommend Git Extensions (terrible name but it's actually quite good). Or maybe GitX on Mac.
3. Let them learn the CLI slowly in their own time.
I’ll take a look at Git Extensions, thanks for the recommendation! Some of our devs took to using the integration with VS Code, which I didn’t like because I didn’t understand how its terminology (e.g. “sync” mapped to underlying Git operations). Others tried the Git GUI which I found very confusing.
I focused on the graphical operations and then tried to show them what commands they could run to execute those operations. Next time I’m in the situation, maybe I’ll adopt a GUI-first approach.
The git CLI for the vast majority of things isn't difficult once you have a basic understanding of DVCS. 95% of the time fetch, pull, push, checkout and commit are all you need.
I admit that Hg had a far nicer an more consistent CLI, and it was my preference back in the day. But it lost for a few reasons - one of which was that it made the 90% easier, but the 10% far harder.
A big reason I wanted to pursue this idea is exactly what you mentioned - a lack of ability to easily create presentation-quality Git structures that can apply specifically to the situation a user is in, NOW.
A super annoying thing about troubleshooting Git issues is when you find a similar solution online but it's done in someone's random repo which could be very different that yours. Your whiteboard sessions are another good example down this line of thought.
Though that's only true of the core, with tags being additional decorations and renames inferred. The simple core delegates complexity.
I think designing a nicer git UX is not easy. Even if we oversimplify commit to cp your working directory together with a path to the previous commit (to form a tree of "branches"), then the abstraction for operations like rebase to manipulate that tree is not quite intrinsically simple.
BTW Tools can be used without proper understanding, like arithmetic without commuting, associating or distributing. While a workable pidgin aids adoption, it's fair to argue for the power of understanding, especially of something clean and coherent and whole. Git's core is like that; the add-ons (like tags) aren't; and the UX seems arbitrary and accreted.
But I do think that there's room for a better mechanism for orchestrating "macros" or building other workflows on top of git. I know a lot of developers who'd love the ability to pretend they're using p4.
Deleted Comment
> Heptapod is a community driven effort to bring Mercurial SCM support to GitLab™, started by Octobus, a company providing professional services around Mercurial.
I found GitExtensions (windows) which I used at my last job to be VERY useful, as it is git, properly, the way it was designed, but in GUI format. It taught me a lot about how to actually use git.
Now I dont use the GUI, its too slow to click around when I know the command.
I dont get the git hate. Then again, I also dont get the "C++ is too complex/complicated" debate, either, so maybe I just have a higher tolerance for terrible design.
Or maybe git just is a very powerful tool and takes more than half a year of half-assed use to learn.
Teaching some basic things like rebase vs. merge, how to git bisect, how to pull with rebase, update a branch with rebase before merging it, stashing changes, etc. got me and the team I lead at $CURRENT_WORKPLACE very, very far.
I can recommend to stop complaining about git, find someone who knows how to use it, and just ask until you get it. Its worth it
And also distributed version control is complicated. Git isn't as intuitive on the happy paths as perhaps it could have been and shows its slightly rushed initial development, but no tool that allows such flexibility can ever be truly simple. And in its defense, it wasn't originally designed to be a super-simple glossy tool. The technical advantages of it simply outweighed the slightly clunky interface, and that interface has improved since then.
I do recommend to use the "git lola" alias to give an easy gestalt of the repo state if you're ever unsure what's going on.
However the fact that time flows in the opposite direction of the parent/child relationships, is inevitable based on Git's design.
They make it look like it flows right to left even though time (or at least sequence) flows left to right.
I generally have a good mental model of my repo and I try to KISS as much as possible, but I can see the value of this in a teaching scenario, for example (as well as on extremely complex git situations).
Check out the quickstart page as well, seems to have more content[1].
[1] https://initialcommit.com/tools/git-sim
https://github.com/initialcommit-com/git-sim
Alternative would be: clone the repo, do your changes, run gitk to be sure.
Which has advantage that result looks exactly the same as it will in production (no new diagram type b/c only using git and gitk), with zero risk that sim differs from reality.
Hehe jk you make a fair point, and in fact I do have a bunch of work left to do to make sure my simulations do match up with Git's behavior as closely as possible.
One big benefit I was going for with Git-Sim though is to interrupt the developer workflow as little as possible.
Changing directories, running a new clone (which could take a mildly annoying amount of time), and running gitk is a pretty big context-switch.
I'm really missing support for remotes. There are lots of tools for local-only development (like https://gitexercises.fracz.com/), but very few allow to demonstrate stuff like "Syncing a GitHub fork with the original repository" which involves two remotes and three copies of the same branch at the very least.
My initial goals for this tool are to purely simulate actions on Git repos without actually modifying them, but I might be flexible on that going forward, as I mention in the article with the --execute flag.
One way around this could be to create a new temporary directory in /tmp, copy .git over there and symlink the rest, then run whatever operation in the newly copied workspace and compare it with the original.
Then you can mutate things however you want and the original stays the same.