Re: A Visual Git Reference

From: Mark Lodato <lodatom@gmail.com>
Date: Feb 9, 2010, 00:18 UTC
Message-ID: <ca433831002081618s1e3193c3ge7b637ede540533a@mail.gmail.com>
In-Reply-To: <alpine.LNX.2.00.1002081513430.14365@iabervon.org>

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

Show 6 quoted lines

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

Show 7 quoted lines

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

Show 5 quoted lines

> 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