Re: A Visual Git Reference

From: Daniel Barkalow <barkalow@iabervon.org>
Date: Feb 8, 2010, 21:57 UTC
Message-ID: <alpine.LNX.2.00.1002081513430.14365@iabervon.org>
In-Reply-To: <ca433831002081134m698f531bwa22f0474db0cdcb@mail.gmail.com>

On Mon, 8 Feb 2010, Mark Lodato wrote:

Show 11 quoted lines

> All,
> 
> I put together a "Visual Git Reference" containing visualizations of
> the most common git commands, for people who prefer to see images over
> text.  It is designed as a reference, not a tutorial, so readers need
> to have some amount of experience before the page will become useful.
> 
> URL: http://marklodato.github.com/visual-git-guide/
> Git repo: http://github.com/marklodato/visual-git-guide/
> 
> If you have any feedback or suggestions, please let me know!

The "3-way merge" node should graphically distinguish the base from the two sides, rather than having all three just go in. The "3-way merge" operation is tricky to understand visually without some sort of "split and rejoin, with specific points" thing.

Also, it would probably be worth showing the use of the index in the process of a 3-way merge: all three versions go into the blue box, and a combination (with conflict markers) goes into the pink box; the user cleans up the pink box, and replaces the 3-part blue box content with the cleaned-up single result content; then the commit gives the diagram you have for "git merge other".

I think you should introduce the detached HEAD situation early; right after "git checkout HEAD~ files", it would be worth showing "git checkout HEAD~". It's pretty common for people in the "technical user" part of the kernel community to use git to browse history and test different commits, and never do a commit at all. This is a pretty common mode across many version control systems (e.g., "cvs checkout -D yesterday"), and nothing unexpected happens if you don't try to commit while doing it. In fact, you could show tracking down a bug introduced between maint and master by checking out c10b9 and then da985.

Then, later, you can bring up the fact that you can actually do commits in that situation, and show how that works. That part is the part that's novel and could potentially lead to people doing work and having it become unreachable. Also, after commiting with a detached HEAD, the normal next step is to create a new branch ("git checkout -b new-topic").

	-Daniel
*This .sig left intentionally blank*