A Visual Git Reference

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!

Cheers, Mark

On Mon, Feb 08, 2010 at 02:34:21PM -0500, Mark Lodato wrote:

I have only glanced over the page, but it seems you have made the time flow from right to left. Is this intentional? I find it not very intuitive.

On Mon, Feb 8, 2010 at 2:51 PM, Peter Baumann <waste.manager@gmx.de> wrote:

Good call. I don't know why I did that. I just pushed a new version that goes left-to-right.

Thanks, Mark

G'day Mark,

Nice diagrams. You might want to change the arrows on the diffs to be consistently in direction of the forward diff.

jon.

On Tue, Feb 9, 2010 at 7:21 AM, Mark Lodato <lodatom@gmail.com> wrote:

On Mon, Feb 8, 2010 at 3:34 PM, Jon Seymour <jon.seymour@gmail.com> wrote:

Thanks. You're right, the da985->b325c was the only one that made sense - the rest were reversed. Is this what you meant? I just pushed this change, so it should be fixed.

Mark

Hi,

to save you time: I added a link to the Git Wiki.

Ciao, Dscho

On Mon, 8 Feb 2010, Mark Lodato wrote:

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*

On Mon, Feb 8, 2010 at 4:57 PM, Daniel Barkalow <barkalow@iabervon.org> wrote:

Yes, I'm not happy with the merge picture at all. As you said, it's difficult to draw a nice picture for it that doesn't become too complex. I'll have to think of a better way...

My fear is making the graphic too complicated. That said, it may be worth making separate graphics: a simple no-conflict case, and a more complicated conflict case.

Good point. At your suggestion, I moved up the detached HEAD section and integrated part of it into the checkout section. You're right, this does come up a lot, so I should cover it.

I may add a section on git bisect in the future.

Done.  Good idea.

Thanks for the feedback. If you have any other thoughts, I'd be glad to hear them! Mark

On Mon, 08 Feb 2010 16:57:12 -0500, Daniel Barkalow wrote:

I often have difficulty trying to internally visualize a mapping from the commits of a merge to the panes of a kdiff3 session. I have special difficulty keeping straight which commit is the LOCAL and which is the REMOTE. Looking at your visual guide, I can almost see a kdiff session in this section on three way merge where each commit sits in one of the panes. b325c in upper left, ed489 in upper middle, and 33104 in upper right, "Working Directory" on the bottom pane. Not sure if that graphic would be useful to anyone else. Thought I'd throw it in for grins.

I learned a few things from your guide. I've been using git for about a year and a half. Thanks.

John

On Mon, Feb 08, 2010 at 02:34:21PM -0500, Mark Lodato wrote:

This looks really awesome, thanks for doing it (though I'll admit I threw up in my mouth a little when I saw you did all of the diagrams as TeX. ;) ).

One of the projects I have wanted to do but never found time for is a "Git Picture Glossary". I was intending to start with much simpler concepts, like how the various object types relate, what a ref is, how a symref differs, what a detached HEAD is, etc. And then move on to "here is what happens when you branch", "here is what happens when you merge", etc. Sort of like "Git for Computer Scientists", but organized as a glossary, with each entry starting off with "to understand this, you first need to understand entries X and Y", with links.

And it seems like what you have done is more or less the same thing, except you skipped all of the really basic entries and went straight to the action-oriented ones.

-Peff

On 02/10/2010 12:20 AM, Jeff King wrote:

*chuckle* on the otherhand I was quite intrigued to find out that TeX was used to create all the graphics; especially after seeing all the examples at http://www.texample.net/tikz/examples/all/date/

(BTW great work on the guide, too, even if I am chiming in a bit late to this. still catching up to the news posts I'm behind on. augh.)

Hello Mark,

On Tue, Feb 9, 2010 at 1:04 AM, Mark Lodato <lodatom@gmail.com> wrote:

This is very helpful for git users...:) Thanks...

On Mon, Feb 8, 2010 at 1:34 PM, Mark Lodato <lodatom@gmail.com> wrote:

It would be great if you could output either larger images or something that is resolution-independent like SVG.

On Wed, Feb 17, 2010 at 07:17:20PM -0600, Michael Witten wrote:

Try

  http://marklodato.github.com/visual-git-guide/index-svg.html

-Peff

The first paragraph has a link to an SVG version of the page. It's not the default since SVG support varies greatly between browsers. Still, I'll consider making the images bigger.

Thanks, Mark

On Wed, Feb 17, 2010 at 8:17 PM, Michael Witten <mfwitten@gmail.com> wrote:

On Wed, Feb 17, 2010 at 7:39 PM, Jeff King <peff@peff.net> wrote:

On Wed, Feb 17, 2010 at 7:39 PM, Mark Lodato <lodatom@gmail.com> wrote:

Oh... :-D

On Thu, Feb 18, 2010 at 2:39 AM, Mark Lodato <lodatom@gmail.com> wrote:

Yes, it does :-)

For me (using Chrome 4 on windows), the SVG images are scaled a little too big for the box that they are placed in, so the bottom and right side is cropped.

Hi,

On Thu, Feb 18, 2010 at 9:39 AM, Mark Lodato <lodatom@gmail.com> wrote:

Chrome 4 gives some parsing errors for the SVG files.

  Error: Problem parsing d=""

For example, line 5 of conventions.svg.