Re: A Visual Git Reference

[Mark Lodato <lodatom@gmail.com>]

On Mon, Feb 8, 2010 at 4:57 PM, Daniel Barkalow <barkalow@iabervon.org> 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.

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...

> 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".

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.

> 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.

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.

> In fact, you
> could show tracking down a bug introduced between maint and master by
> checking out c10b9 and then da985.

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

> 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").

Done.  Good idea.

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