capillary

Capillary.rb

Capillary parses the output of Git log and produces a beautiful graphical representation of your repository's history - similar to gitk and git log --graph, except beautiful.

Capillary consists of two parts:

• capillary.rb: which parses the output from Git log data and generates a JSON representation of it, usable from:
• capillary.js: the javascript library doing the presentation

The emitted JSON

Capillary.rb emits a JSON array consisting of JSON objects in the following form (starting with seqId=0):

[[{
        "refs": {
            "remotes": {
                "origin": { "production" }
            },
            "heads": ["production", "master"],
            "tags": ["v2.0.0"]
        },
        "seqId": 0,
        "committedAt": "Fri Jul 15 07:23:44 +0200 2011",
        "parentIds": ["8f38426b1641a20511f6eeb6878f2e1e00712df2", "ce7de03fc2cb6114d2f859fefc996e7fffa2d7f6"],
        "id": "a490db7b450e6c58bb69ac64dfe725b188bfe5b3",
        "committerEmail": "[e-mail]",
        "message": "Merge branch 'master' into production"
    }, {
        "refs": { "heads": [], "tags": [], "remotes": {} },
        "seqId": 1,
        "committedAt": "Thu Jun 16 10:20:03 +0200 2011",
        "parentIds": ["0443fcdf66df410993441b617d14dab121245ff7"],
        "id": "909d42da14d186e4580995f24b56aa4223f7965f",
        "committerEmail": "[e-mail]",
        "message":"Don't allow destructive actions via GET etc"
    }]]

• seqId: The relative sequence id of the commit. This is used to order commits, and seqId == 0 is given to the newest commit, because Capillary looks at the commit graph top-down (newest-oldest).
• committedAt: The commit date.
• committerEmail: The committer email.
• id: The commit sha
• parentIds: The commit sha of all parent commits of this commit
• message: The commit message
• refs: Relevant names of heads, tags, remotes and others that concern the commit in question

Note that the JSON emitted is a nested array - an array of "paths", where each path is an array of commits.

What is a path? If you look at a log graph from the "top" (newest commit), each merge point is considered the start of a new path through the graph. The commit where the branch was originally created marks the end of the path.

Consider the following graph (the numbers to the left indicate each commit's assigned seqId):

0 0 |
1 0 | | | 2 | 0 | | 3 | 0 | |
4 | 0 | | | | 5 | 0 | | | | 6 | | 0 | |/ 7 | 0 |/ 8 0 |

Capillary parses this log into three paths:

Path #1: [{ seqId: 0 }, { seqId: 1 }, { seqId: 8 }] 0 0 | 1 0 | 2 | | 3 | | 4 | | 5 | | 6 | | 7 | | 8 0 |

Path #2: [{ seqId: 0 }, { seqId: 2 }, { seqId: 3 }, { seqId: 4 }, { seqId: 5 }, { seqId: 7 }, { seqId: 8 }] 0 0
1 | | 2 0 | 3 0 | 4 0 | 5 0 | 6 | | 7 0 / 8 0 |

Path #3: [{ seqId: 3 }, { seqId: 6 }, { seqId: 7 }] 3 0
4 | | 5 | | 6 0 / 7 0

This output can be further processed by capillary.js.

Input to capillary.rb

Capillary parses output from Git log, in the format as specified in test/fixtures/single_commit.txt. This output was generated from Git using the following command:

git log --pretty=format:"%H§%P§%ad§%ae§%d§%s§" --decorate=full

This will produce a graph where commits are strictly ordered by date. To get a graph similar to that produced by git log --graph, you add - surprise - the --graph option:

git log --pretty=format:"%H§%P§%ad§%ae§%d§%s§" --decorate=full --graph

Both of these will produce a graph that includes all ancestors to the current HEAD. If you want everything - including branches not merged to the current branch, use --all:

git log --pretty=format:"%H§%P§%ad§%ae§%d§%s§" --decorate=full --graph --all

The name

Look it up: http://www.google.com/search?aq=f&ie=UTF-8&q=capillary