7 ms·

Git Magic

238 points by polm23 9y ago

polm23 9y ago
A lot of git tutorials go into detail about how the data model works as part of or even before explaining basic usage. This guide is different in that it explains how to use git in the simplest possible way - conceptually just as a system to make save points - and then covers the data model later after it's shown the merits of the system. If you need to explain git to someone who has the option of not using it or isn't sold on the whole idea in the first place, this is the absolute best place to start.
- hyperpallium 9y ago
  They're not being rigorous; it's just simpler to explain in terms of the data model. The data model is very simple and clean (and most of git's benefits flow directly from the model). The UI is awful... confusing and inconsistent. The engineering is brilliant: informative error messages and hints; fast; great features (e.g. a better diff, with --color-words; logical argument parsing). The only significant things missing are deliberate design choices inherent in the data model. e.g.: not storing renames explicitly (which BitKeeper did), so you can't easily search for changes in a file that was renamed/moved. It could be simulated with out-of-band info (like tags), but isn't.
severine 9y ago
Wow, there are full translations into Simplified/Traditional Chinese, French, German, Italian, Korean, Polish, Brazilian Portuguese, Russian, Ukrainian and Vietnamese. Truly a great resource, thanks!
mrestko 9y ago
Would be nice if you didn't have to scroll back to the top of the page to go to the next section. Otherwise seems like a good resource.
msravi 9y ago
This seems to try to get the reader familiar with commands in a verbose sort of way, but IMHO, that's not exactly the best way. See for example the section on branches - it tells you to run certain commands (checkout -b) without telling you what's happening in the background. So while you kind-of get a feel for the command in the context it's being explained, you wouldn't know how to apply it to your context, unless your workflow and context is the same. On the other hand, if you look at how branching is dealt with in the "official" book (https://git-scm.com/book/en/v2/Git-Branching-Branches-in-a-Nutshell https://git-scm.com/book/en/v2/Git-Branching-Branches-in-a-N...), it tells you very clearly what each command is doing in the background so you know exactly what's happening. Once you understand that, you know git.
- IndrekR 9y ago
  > it tells you to run certain commands (checkout -b) without telling you what's happening in the background I guess this is why it is called A Usage-First Guide to Git. You can always dig deeper, but in most cases people just starting out with git want to get things done without their heads exploding first.
  - barrkel 9y ago
    Understanding git's data model is the correct route to avoid head explosion, because it's both simple and every other feature fits in within the mental model. Git is by far the simplest SCC system I've used because it is so easy to understand the data model. It lets me intuit the existence of commands because I know the kind of data model manipulation I want to apply and all I need to do is find the right incantation.
    - wastedhours 9y ago
      There's no "correct" route. The logical way into tackling a subject to you might be different to someone else. The "see it in action and delve into more details later" approach might not be the way you see the best practitioners developing their skillset, and starting at the theoretical basics and building from there might be the more academically rigorous approach, but it can be effective approach to directing learning. If I was learning Java, I'd want to get cracking on developing a "Hello World" application before trying to understand the JVM.
hnrodey 9y ago
Shameless plug, I'm the author of Git Evangelism. This is the guide I built to onboard my coworkers during our transition to Git. This guide is updated regularly and differentiates itself by putting the reader in a position to succeed during their first attempt at Git by providing sane defaults (which Git does remarkably poorly) like setting Sublime Text as the text editor (instead of Vim) and configuring Beyond Compare as the diff tool and mergetool. GE gives a brief introduction to the commands to move you towards being productive early-on and orders the commands that the user is likely to encounter the need. https://github.com/ryanrodemoyer/git-evangelism https://github.com/ryanrodemoyer/git-evangelism I like Vim, but it's incredibly intimidating and frustrating that you get presented with Vim if all you want to do is experiment with merging. I'm going to stop myself here. I could go on a long rant about the awful system defaults. I have a series of screencasts planned, some recorded, that follow through Git Evangelism so that you, the reader, can use Git confidently and successfully while avoiding the bizarre error states that plague new and seasoned users alike. In addition, I have created a non-traditional in-person workshop event that helps new users build up their understanding of the Git data model and we go in detail on how that differs from a centralized source control system (ie. TFS VC). Git Evangelism is in some ways heavily influenced by the thinking forced by centralized version control systems. At my current job, we are moving away from Team Foundation Server Version Control (TFSVC/TFVC) and to Git hosted by TFS. There is much in that document that is specifically geared towards Windows/TFS background although I have planned to make non-Windows specific updates (personally, I'm a Mac user). The problem with most getting started guides for Git, is that they continue to put the reader in a position to fail rather than a position to succeed. Git has all kind of "gotchas" that guides skip over. A typical guide leads you through staging and committing and reverting but rarely does the guide explain the nuances such as difference between "git add ." and "git commit -a" or the value in using a tool like GitLab (besides that it's hipsterish) or what is a hard reset (hint, there's multiple meanings so it depends how it is used).
- recursive 9y ago
  Oh wow, I didn't realize you could change git's diff thing. I've never been able to figure out what it was doing, so I always just used a separate gui for diffs.
pdonis 9y ago
A priceless quote: "[U]sing systems that scale poorly for tiny projects is like using Roman numerals for calculations involving small numbers."
- thetruthseeker1 9y ago
  I really liked the analogies the author used to demistify git usecases. I also agree that it probably doesn’t make sense to use other version control systems if cost and learning (which can also be modeled as cost for the company) are not factors. For eg, if there is some quick project you need to do, and people in your team have been using say CVS, and there is not much wiggle room in the deadline, getting your team to use Git may not be the most smartest choice - I think that is what most people mean there when they talk about ‘tiny’ projects. I will say that even if you are not truly starting from scratch, migrating to git has advantages more often, but I am wary of trivialising the people who think there is a cost associated to ( move to )a distributed system like git.
newscracker 9y ago
Looks like the website is not updated with builds from the GitHub repo. The single page HTML and the PDF file on the website are both dated August 2007. The printed book on Amazon is from 2010. Anyone wanting the latest should get this from GitHub and build it. [1] If you're not familiar with technology and someone pointed you to this to learn Git (like in the case of publishing), this step in itself could be a barrier. [1]: https://github.com/blynn/gitmagic https://github.com/blynn/gitmagic
dangirsh 9y ago
I can't help but mention Magit [1] here. It's so pleasant compared to the CLI, I've actually found myself Emacs + Magit on machines just to avoid running a few git CLI commands. [1]: https://magit.vc/ https://magit.vc/
- ams6110 9y ago
  Magit is the only thing that makes git usable to me.
dudeget 9y ago
somewhere else on HN this was posted recently: https://learngitbranching.js.org/ https://learngitbranching.js.org/ I've known git for years but anything more than push, pull, clone, merge, commit, and add I didn't really touch. This webapp definitely helped expand my git knowledge
fwgwgwgch 9y ago
Sidenote: Convert simplified Chinese to traditional Chinese : `cconv -f UTF8-CN -t UTF8-TW` Does this work? If so, how? My understanding is that there are certain simplified characters that map from multiple traditional characters.
TRS80MIII 9y ago
I'm not so sure "usage first" is the way to go. You really must understand how the git content-oriented filesystem works, what a commit is, and how it works internally to avoid becoming very confused. Ive seen people who came from other systems (cvs, rcs, subversion) who thought they were just "checking in and out" files and got themselves into all sorts of trouble.
milkmiruku 9y ago
something gets marked as a dupe, but no op link?

238 points by polm23 9y ago

A lot of git tutorials go into detail about how the data model works as part of or even before explaining basic usage. This guide is different in that it explains how to use git in the simplest possible way - conceptually just as a system to make save points - and then covers the data model later after it's shown the merits of the system. If you need to explain git to someone who has the option of not using it or isn't sold on the whole idea in the first place, this is the absolute best place to start.

hyperpallium 9y ago
They're not being rigorous; it's just simpler to explain in terms of the data model. The data model is very simple and clean (and most of git's benefits flow directly from the model). The UI is awful... confusing and inconsistent. The engineering is brilliant: informative error messages and hints; fast; great features (e.g. a better diff, with --color-words; logical argument parsing). The only significant things missing are deliberate design choices inherent in the data model. e.g.: not storing renames explicitly (which BitKeeper did), so you can't easily search for changes in a file that was renamed/moved. It could be simulated with out-of-band info (like tags), but isn't.

severine 9y ago

Wow, there are full translations into Simplified/Traditional Chinese, French, German, Italian, Korean, Polish, Brazilian Portuguese, Russian, Ukrainian and Vietnamese. Truly a great resource, thanks!

mrestko 9y ago

Would be nice if you didn't have to scroll back to the top of the page to go to the next section. Otherwise seems like a good resource.

msravi 9y ago

This seems to try to get the reader familiar with commands in a verbose sort of way, but IMHO, that's not exactly the best way. See for example the section on branches - it tells you to run certain commands (checkout -b) without telling you what's happening in the background. So while you kind-of get a feel for the command in the context it's being explained, you wouldn't know how to apply it to your context, unless your workflow and context is the same. On the other hand, if you look at how branching is dealt with in the "official" book (https://git-scm.com/book/en/v2/Git-Branching-Branches-in-a-Nutshell https://git-scm.com/book/en/v2/Git-Branching-Branches-in-a-N...), it tells you very clearly what each command is doing in the background so you know exactly what's happening. Once you understand that, you know git.

IndrekR 9y ago
> it tells you to run certain commands (checkout -b) without telling you what's happening in the background I guess this is why it is called A Usage-First Guide to Git. You can always dig deeper, but in most cases people just starting out with git want to get things done without their heads exploding first.
- barrkel 9y ago
  Understanding git's data model is the correct route to avoid head explosion, because it's both simple and every other feature fits in within the mental model. Git is by far the simplest SCC system I've used because it is so easy to understand the data model. It lets me intuit the existence of commands because I know the kind of data model manipulation I want to apply and all I need to do is find the right incantation.
  - wastedhours 9y ago
    There's no "correct" route. The logical way into tackling a subject to you might be different to someone else. The "see it in action and delve into more details later" approach might not be the way you see the best practitioners developing their skillset, and starting at the theoretical basics and building from there might be the more academically rigorous approach, but it can be effective approach to directing learning. If I was learning Java, I'd want to get cracking on developing a "Hello World" application before trying to understand the JVM.

hnrodey 9y ago

Shameless plug, I'm the author of Git Evangelism. This is the guide I built to onboard my coworkers during our transition to Git. This guide is updated regularly and differentiates itself by putting the reader in a position to succeed during their first attempt at Git by providing sane defaults (which Git does remarkably poorly) like setting Sublime Text as the text editor (instead of Vim) and configuring Beyond Compare as the diff tool and mergetool. GE gives a brief introduction to the commands to move you towards being productive early-on and orders the commands that the user is likely to encounter the need. https://github.com/ryanrodemoyer/git-evangelism https://github.com/ryanrodemoyer/git-evangelism I like Vim, but it's incredibly intimidating and frustrating that you get presented with Vim if all you want to do is experiment with merging. I'm going to stop myself here. I could go on a long rant about the awful system defaults. I have a series of screencasts planned, some recorded, that follow through Git Evangelism so that you, the reader, can use Git confidently and successfully while avoiding the bizarre error states that plague new and seasoned users alike. In addition, I have created a non-traditional in-person workshop event that helps new users build up their understanding of the Git data model and we go in detail on how that differs from a centralized source control system (ie. TFS VC). Git Evangelism is in some ways heavily influenced by the thinking forced by centralized version control systems. At my current job, we are moving away from Team Foundation Server Version Control (TFSVC/TFVC) and to Git hosted by TFS. There is much in that document that is specifically geared towards Windows/TFS background although I have planned to make non-Windows specific updates (personally, I'm a Mac user). The problem with most getting started guides for Git, is that they continue to put the reader in a position to fail rather than a position to succeed. Git has all kind of "gotchas" that guides skip over. A typical guide leads you through staging and committing and reverting but rarely does the guide explain the nuances such as difference between "git add ." and "git commit -a" or the value in using a tool like GitLab (besides that it's hipsterish) or what is a hard reset (hint, there's multiple meanings so it depends how it is used).

recursive 9y ago
Oh wow, I didn't realize you could change git's diff thing. I've never been able to figure out what it was doing, so I always just used a separate gui for diffs.

pdonis 9y ago

A priceless quote: "[U]sing systems that scale poorly for tiny projects is like using Roman numerals for calculations involving small numbers."

thetruthseeker1 9y ago
I really liked the analogies the author used to demistify git usecases. I also agree that it probably doesn’t make sense to use other version control systems if cost and learning (which can also be modeled as cost for the company) are not factors. For eg, if there is some quick project you need to do, and people in your team have been using say CVS, and there is not much wiggle room in the deadline, getting your team to use Git may not be the most smartest choice - I think that is what most people mean there when they talk about ‘tiny’ projects. I will say that even if you are not truly starting from scratch, migrating to git has advantages more often, but I am wary of trivialising the people who think there is a cost associated to ( move to )a distributed system like git.

newscracker 9y ago

Looks like the website is not updated with builds from the GitHub repo. The single page HTML and the PDF file on the website are both dated August 2007. The printed book on Amazon is from 2010. Anyone wanting the latest should get this from GitHub and build it. [1] If you're not familiar with technology and someone pointed you to this to learn Git (like in the case of publishing), this step in itself could be a barrier. [1]: https://github.com/blynn/gitmagic https://github.com/blynn/gitmagic

dangirsh 9y ago

I can't help but mention Magit [1] here. It's so pleasant compared to the CLI, I've actually found myself Emacs + Magit on machines just to avoid running a few git CLI commands. [1]: https://magit.vc/ https://magit.vc/

ams6110 9y ago
Magit is the only thing that makes git usable to me.

dudeget 9y ago

somewhere else on HN this was posted recently: https://learngitbranching.js.org/ https://learngitbranching.js.org/ I've known git for years but anything more than push, pull, clone, merge, commit, and add I didn't really touch. This webapp definitely helped expand my git knowledge

fwgwgwgch 9y ago

Sidenote: Convert simplified Chinese to traditional Chinese : `cconv -f UTF8-CN -t UTF8-TW` Does this work? If so, how? My understanding is that there are certain simplified characters that map from multiple traditional characters.

TRS80MIII 9y ago

I'm not so sure "usage first" is the way to go. You really must understand how the git content-oriented filesystem works, what a commit is, and how it works internally to avoid becoming very confused. Ive seen people who came from other systems (cvs, rcs, subversion) who thought they were just "checking in and out" files and got themselves into all sorts of trouble.

milkmiruku 9y ago

something gets marked as a dupe, but no op link?