Some ASCII Art

Some ASCII Art

[Jon Loeliger]

Guys,

I tend to be a visual learner.  So I made up some ASCII
art and annotated it with some Git operations and stuff.

First, I'd love to have any feedback on these drawings,
especially if it actually misrepresents things.  If there
are obvious additions to these, that'd be nice to know too.

Second, if you think they are generally useful, please
feel free to add them to whatever documentation seems
appropriate.  (If you want a patch to a certain file
and a Sign-Off, let me know!)

Thanks,
jdl


Fundamental Git Index Operations
================================

                    +-----------+
                    | Object DB |
                    |  Backing  |
                    |   Store   |
                    +-----------+
                       ^
           write-tree  |     |
             tree obj  |     |
                       |     |  read-tree
                       |     |  tree obj
                             V
                    +-----------+
                    |   Index   |
                    |  "cache"  |
                    +-----------+
                       ^
         update-index  |     |
             blob obj  |     |
                       |     |  checkout-index
                       |     |  blob obj
                             V
                    +-----------+
                    |  Working  |
                    | Directory |
                    +-----------+


Git Index Operations
====================


                    +-----------+
                    | Object DB |
                    |  Backing  |
                    |   Store   | -----------+
                    +-----------+            |
                       ^                     |
          commit-tree  |     |               |
           commit obj  |     | read-tree -m  |
                       |     | tree obj      |
                       |     |               |
                             V               |
                    +-----------+            |
                    |   Index   | <- - - - - +
                    |  "cache"  | - - - - - >+
                    +-----------+            |
                       ^                     |
                       |                     |
         update-index  |     read-tree -m -u |
             blob obj  |            tree obj |
                       |                     |
                                             |
                    +-----------+            |
                    |  Working  |<-----------+
                    | Directory |
                    +-----------+



Git Diff Types
==============


                      diff-tree

                       +----+
                       |    |
                       |    |
                       V    V
                    +-----------+
                    | Object DB |
                    |  Backing  |
                    |   Store   |
                    +-----------+
                      ^    ^
                      |    |
                      |    |  diff-index --cached
                      |    |
          diff-index  |    V
                      |  +-----------+
                      |  |   Index   |
                      |  |  "cache"  |
                      |  +-----------+
                      |    ^
                      |    |
                      |    |  diff-files
                      |    |
                      V    V
                    +-----------+
                    |  Working  |
                    | Directory |
                    +-----------+


Commit DAG Revision Naming
==========================

Both node B and C are a commit parents of node A.

    G   H   I   J
     \ /     \ /
      D   E   F
       \  |  /
        \ | /
         \|/
          B     C
           \   /
            \ /
             A


    A = rev    = rev^0
    B = rev^   = rev^1     = rev~1
    D = rev^^  = rev^1^1   = rev~2
    G = rev^^^ = rev^1^1^1 = rev~3

Is there a way to name node C, E, F, H, I or J?
Is A also called rev~0?

Re: Some ASCII Art

[Junio C Hamano]

Jon Loeliger <jdl@freescale.com> writes:

> Fundamental Git Index Operations
> Git Index Operations

These two look almost the same.

I find the label "commit-tree" on index -> odb in the second
picture a bit misleading.  "commit-tree" takes a tree and zero
or more commit objects to create a new commit object, so it
works solely inside odb.

It is good that you mention that "read-tree -u" form updates
working tree in the second picture.  In the same spirit, you
might also want to mention that "checkout-index -u" updates the
index (i.e. matches the stat information) in the same picture.

Diff drawing looks good.  If you are aiming for completeness,
diff-stages is lacking -- it compares between stages in the
index file.  But diff-stages is really a specialized operation
whose usefulness is still unproven, so not drawing it for the
sake of simplicity is also OK.

> Commit DAG Revision Naming
> ==========================
>
> Both node B and C are a commit parents of node A.

I assume that parents are left to right in this picture, that
is, B's first parent is D, second E, and third F.

>
>     G   H   I   J
>      \ /     \ /
>       D   E   F
>        \  |  /
>         \ | /
>          \|/
>           B     C
>            \   /
>             \ /
>              A
>
>
>     A = rev    = rev^0
>     B = rev^   = rev^1     = rev~1
>     D = rev^^  = rev^1^1   = rev~2
>     G = rev^^^ = rev^1^1^1 = rev~3

> Is there a way to name node C, E, F, H, I or J?

C = A^2
E = B^2 = A^^2
F = B^3 = A^^3
H = D^2 = B^^2 = A^^^2 = A~2^2
I = F^ = B^3^ = A^^3^
J = F^2 = B^3^2 = A^^3^2

They look like line noise ;-)

> Is A also called rev~0?

If you are talking about only commit objects, then REV^0 is
always the same as REV.  You could write REV^0^0^0^0 if you
want but that is rather pointless ;-).

Re: Some ASCII Art

[Jon Loeliger]

On Thu, 2005-10-06 at 15:38, Junio C Hamano wrote:
> Jon Loeliger <jdl@freescale.com> writes:
> 
> > Fundamental Git Index Operations
> > Git Index Operations
> 
> These two look almost the same.

Yeah, the first one was intended to capture the
operations discussed the first four points of the
"The Workflow" section of the main Git doc page.

The second is "more of same", but the one picture with
every ASCII arc on it was getting confusing and crowded.

> I find the label "commit-tree" on index -> odb in the second
> picture a bit misleading.  "commit-tree" takes a tree and zero
> or more commit objects to create a new commit object, so it
> works solely inside odb.

Ah!  Of course.  Thanks!

> It is good that you mention that "read-tree -u" form updates
> working tree in the second picture.

Discovering how this related was a key insight for me. :-)

>   In the same spirit, you
> might also want to mention that "checkout-index -u" updates the
> index (i.e. matches the stat information) in the same picture.

Ooh.  Yes!  Good idea.


> > Commit DAG Revision Naming
> > ==========================
> >
> > Both node B and C are a commit parents of node A.
> 
> I assume that parents are left to right in this picture, that
> is, B's first parent is D, second E, and third F.

Yeah, I even meant to add that sentence before
sending the mail. 

> > Is there a way to name node C, E, F, H, I or J?
> 
> C = A^2
> E = B^2 = A^^2
> F = B^3 = A^^3
> H = D^2 = B^^2 = A^^^2 = A~2^2
> I = F^ = B^3^ = A^^3^
> J = F^2 = B^3^2 = A^^3^2

Ah!

> They look like line noise ;-)

Indeed. :-)

Would it be a useful option to git-show-branch
that would state the commit SHA1s as well?

    % git show-branch --show-revs

    * [master] Merge paul's branch
     ! [origin] Fix drm 'debug' sysfs permissions
      ! [paul] powerpc: Fix idle.c compile warning
    ---
    +   [06a41091c93e529e6cef68ba60deeb1b9ceabc7f] Merge paul's branch
    + + [05f62a5c049845eab8dfb3aeda55c18a2d4396e3] powerpc: Fix idle.c compile warning
    + + [c16ff7e44883afc05cbf6fde0e6913bb10c66885] powerpc: Define a _sdata symbol
    + + [8dad3f9257414f151cd821bfe01f54d7f52d2507] powerpc: Merge traps.c a bit more
    + + [b3491269f5604e4265ee2f27b47a76ce1e3678b6] powerpc: Use the merged of_device.c with ARCH=powerpc


Thanks for your feedback!

jdl

Re: Some ASCII Art

[Junio C Hamano]

Jon Loeliger <jdl@freescale.com> writes:

> Would it be a useful option to git-show-branch
> that would state the commit SHA1s as well?
>
>     % git show-branch --show-revs
>
>     * [master] Merge paul's branch
>      ! [origin] Fix drm 'debug' sysfs permissions
>       ! [paul] powerpc: Fix idle.c compile warning
>     ---
>     +   [06a41091c93e529e6cef68ba60deeb1b9ceabc7f] Merge paul's branch
>     + + [05f62a5c049845eab8dfb3aeda55c18a2d4396e3] powerpc: Fix idle.c compile warning
>     + + [c16ff7e44883afc05cbf6fde0e6913bb10c66885] powerpc: Define a _sdata symbol
>     + + [8dad3f9257414f151cd821bfe01f54d7f52d2507] powerpc: Merge traps.c a bit more
>     + + [b3491269f5604e4265ee2f27b47a76ce1e3678b6] powerpc: Use the merged of_device.c with ARCH=powerpc

In practice, probably 30 or so bits prefix would identify an
object uniquely within a repository, so one possibility is to
use the first 7 or so letters from 40-byte SHA1, after making
sure 7 is enough for that particular prefix -- otherwise use
more for that particular object.

The current "relative to the head" notation is descriptive and
easier to see when you do not have too many branches and complex
merge structure but one major drawback is that it is not stable;
you add a commit then what was used to be master~5 now suddenly
become master~6.