New ASCII Art

Junio,

I see my name over on the TODO list:

    31 Documentation
    32 -------------
    33
    34 * Help Jon Loeliger to find place in the documentation to place
    35 his drawing.

So, I have updated drawings for consideration. See if you buy these. And if so, let's ponder where they might go. Then I'll patch 'em in...

I now have four ASCII Art drawings:

    - Fundamental git operations
    - Git merge operations
    - Git diff types
    - Commit DAG Revision Naming

jdl

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

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

Git Merge Operations ====================

                    +-----------+
                    | Object DB |
                    |  Backing  |
                    |   Store   | -------+
                    +-----------+        |
                                         |
                           read-tree -m  |
  +-----+                  tree obj      |
  |patch|                                |
  +-----+           +-----------+        |
     |              |   Index   | <- - - +
     +------------->|  "cache"  | - - - >+
 git-apply --index  +-----------+        |
                                         |
                                         |
                         read-tree -m -u |
 +-----+                        tree obj |
 |patch|                                 |
 +-----+            +-----------+        |
    |               |  Working  |<-------+
    +-------------->| Directory |
  git-apply         +-----------+

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 commit node A. Parent commits are ordered left-to-right.

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

    A =      = A^0
    B = A^   = A^1     = A~1
    C = A^2  = A^2
    D = A^^  = A^1^1   = A~2
    E = B^2  = A^^2
    F = B^3  = A^^3
    G = A^^^ = A^1^1^1 = 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

Fixed-point operations:

    A^0 = A^{commit}
    A^{tree}
   

jdl@freescale.com writes:

Thanks for doing this.  You have a sale.

README (which is included as git(7) Discussion section) might be a good document to decorate with this. Probably after "The Workflow; 5) Tying it all together".

Note that apply --index updates both index and working tree. Note that read-tree -m -u takes information from both odb and index, and updates both index and working tree.

Logically this belongs to "Merging two branches" in the Tutorial document. The Tutorial introduction claims the document intends to show how the core level operates to implement higher level scripts, but currently we lack the lower-level details in the text that would go well together with this illustration. Please remind me that I should write something up at the very end of that section soonish ;-).

Maybe as a side note to "Inspecing Changes" section in the Tutorial.

As an illustration to "SPECIFYING REVISIONS" section of git-rev-parse(1).