A Visual Git Reference

A Visual Git Reference

[Mark Lodato]

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

Re: A Visual Git Reference

[Peter Baumann]

On Mon, Feb 08, 2010 at 02:34:21PM -0500, Mark Lodato wrote:
> 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!

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.

Re: A Visual Git Reference

[Mark Lodato]

On Mon, Feb 8, 2010 at 2:51 PM, Peter Baumann <waste.manager@gmx.de> 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.

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

Thanks,
Mark

Re: A Visual Git Reference

[Jon Seymour]

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 2:51 PM, Peter Baumann <waste.manager@gmx.de> 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.
>
> Good call.  I don't know why I did that.  I just pushed a new version
> that goes left-to-right.
>
> Thanks,
> Mark
> --
> To unsubscribe from this list: send the line "unsubscribe git" in
> the body of a message to majordomo@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html
>

Re: A Visual Git Reference

[Mark Lodato]

On Mon, Feb 8, 2010 at 3:34 PM, Jon Seymour <jon.seymour@gmail.com> wrote:
> Nice diagrams. You might want to change the arrows on the diffs to be
> consistently in direction of the forward diff.

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

Re: A Visual Git Reference

[Johannes Schindelin]

Hi,

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

Ciao,
Dscho

Re: A Visual Git Reference

[Daniel Barkalow]

On Mon, 8 Feb 2010, Mark Lodato wrote:

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

Re: A Visual Git Reference

[Mark Lodato]

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

Re: A Visual Git Reference

[John J. Franey]

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

> On Mon, 8 Feb 2010, Mark Lodato wrote:
> 
>> 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 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

Re: A Visual Git Reference

[Jeff King]

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

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

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

Re: A Visual Git Reference

[Scott R. Godin]

On 02/10/2010 12:20 AM, Jeff King wrote:
> On Mon, Feb 08, 2010 at 02:34:21PM -0500, Mark Lodato wrote:
>
>> 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!
>
> 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. ;) ).

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

-- 
(please respond to the list as opposed to my email box directly,
unless you are supplying private information you don't want public
on the list)

Re: A Visual Git Reference

[Dilip M]

Hello Mark,


On Tue, Feb 9, 2010 at 1:04 AM, Mark Lodato <lodatom@gmail.com> wrote:
> 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!

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


-- 
Dilip

Everyone is gifted - but some people never open their package!

Re: A Visual Git Reference

[Michael Witten]

On Mon, Feb 8, 2010 at 1:34 PM, Mark Lodato <lodatom@gmail.com> wrote:
> 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 would be great if you could output either larger images or
something that is resolution-independent like SVG.

Re: A Visual Git Reference

[Jeff King]

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

> On Mon, Feb 8, 2010 at 1:34 PM, Mark Lodato <lodatom@gmail.com> wrote:
> > 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 would be great if you could output either larger images or
> something that is resolution-independent like SVG.

Try

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

-Peff

Re: A Visual Git Reference

[Mark Lodato]

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 Mon, Feb 8, 2010 at 1:34 PM, Mark Lodato <lodatom@gmail.com> wrote:
>> 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 would be great if you could output either larger images or
> something that is resolution-independent like SVG.
>

Re: A Visual Git Reference

[Michael Witten]

On Wed, Feb 17, 2010 at 7:39 PM, Jeff King <peff@peff.net> wrote:
> Try
>
>  http://marklodato.github.com/visual-git-guide/index-svg.html

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

Oh... :-D

Re: A Visual Git Reference

[Tor Arvid Lund]

On Thu, Feb 18, 2010 at 2:39 AM, Mark Lodato <lodatom@gmail.com> wrote:
> 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.

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.

Re: A Visual Git Reference

[Tay Ray Chuan]

Hi,

On Thu, Feb 18, 2010 at 9:39 AM, Mark Lodato <lodatom@gmail.com> wrote:
> 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.

Chrome 4 gives some parsing errors for the SVG files.

  Error: Problem parsing d=""

For example, line 5 of conventions.svg.

-- 
Cheers,
Ray Chuan