Some ASCII Art

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?

Jon Loeliger <jdl@freescale.com> writes:

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.

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

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 ;-)

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

On Thu, 2005-10-06 at 15:38, Junio C Hamano wrote:

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.

Ah!  Of course.  Thanks!

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

Ooh.  Yes!  Good idea.

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

Ah!

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

Jon Loeliger <jdl@freescale.com> writes:

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.