| history graph API |
| ================= |
| |
| The graph API is used to draw a text-based representation of the commit |
| history. The API generates the graph in a line-by-line fashion. |
| |
| Functions |
| --------- |
| |
| Core functions: |
| |
| * `graph_init()` creates a new `struct git_graph` |
| |
| * `graph_update()` moves the graph to a new commit. |
| |
| * `graph_next_line()` outputs the next line of the graph into a strbuf. It |
| does not add a terminating newline. |
| |
| * `graph_padding_line()` outputs a line of vertical padding in the graph. It |
| is similar to `graph_next_line()`, but is guaranteed to never print the line |
| containing the current commit. Where `graph_next_line()` would print the |
| commit line next, `graph_padding_line()` prints a line that simply extends |
| all branch lines downwards one row, leaving their positions unchanged. |
| |
| * `graph_is_commit_finished()` determines if the graph has output all lines |
| necessary for the current commit. If `graph_update()` is called before all |
| lines for the current commit have been printed, the next call to |
| `graph_next_line()` will output an ellipsis, to indicate that a portion of |
| the graph was omitted. |
| |
| The following utility functions are wrappers around `graph_next_line()` and |
| `graph_is_commit_finished()`. They always print the output to stdout. |
| They can all be called with a NULL graph argument, in which case no graph |
| output will be printed. |
| |
| * `graph_show_commit()` calls `graph_next_line()` and |
| `graph_is_commit_finished()` until one of them return non-zero. This prints |
| all graph lines up to, and including, the line containing this commit. |
| Output is printed to stdout. The last line printed does not contain a |
| terminating newline. |
| |
| * `graph_show_oneline()` calls `graph_next_line()` and prints the result to |
| stdout. The line printed does not contain a terminating newline. |
| |
| * `graph_show_padding()` calls `graph_padding_line()` and prints the result to |
| stdout. The line printed does not contain a terminating newline. |
| |
| * `graph_show_remainder()` calls `graph_next_line()` until |
| `graph_is_commit_finished()` returns non-zero. Output is printed to stdout. |
| The last line printed does not contain a terminating newline. Returns 1 if |
| output was printed, and 0 if no output was necessary. |
| |
| * `graph_show_strbuf()` prints the specified strbuf to stdout, prefixing all |
| lines but the first with a graph line. The caller is responsible for |
| ensuring graph output for the first line has already been printed to stdout. |
| (This can be done with `graph_show_commit()` or `graph_show_oneline()`.) If |
| a NULL graph is supplied, the strbuf is printed as-is. |
| |
| * `graph_show_commit_msg()` is similar to `graph_show_strbuf()`, but it also |
| prints the remainder of the graph, if more lines are needed after the strbuf |
| ends. It is better than directly calling `graph_show_strbuf()` followed by |
| `graph_show_remainder()` since it properly handles buffers that do not end in |
| a terminating newline. The output printed by `graph_show_commit_msg()` will |
| end in a newline if and only if the strbuf ends in a newline. |
| |
| Data structure |
| -------------- |
| `struct git_graph` is an opaque data type used to store the current graph |
| state. |
| |
| Calling sequence |
| ---------------- |
| |
| * Create a `struct git_graph` by calling `graph_init()`. When using the |
| revision walking API, this is done automatically by `setup_revisions()` if |
| the '--graph' option is supplied. |
| |
| * Use the revision walking API to walk through a group of contiguous commits. |
| The `get_revision()` function automatically calls `graph_update()` each time |
| it is invoked. |
| |
| * For each commit, call `graph_next_line()` repeatedly, until |
| `graph_is_commit_finished()` returns non-zero. Each call to |
| `graph_next_line()` will output a single line of the graph. The resulting |
| lines will not contain any newlines. `graph_next_line()` returns 1 if the |
| resulting line contains the current commit, or 0 if this is merely a line |
| needed to adjust the graph before or after the current commit. This return |
| value can be used to determine where to print the commit summary information |
| alongside the graph output. |
| |
| Limitations |
| ----------- |
| |
| * `graph_update()` must be called with commits in topological order. It should |
| not be called on a commit if it has already been invoked with an ancestor of |
| that commit, or the graph output will be incorrect. |
| |
| * `graph_update()` must be called on a contiguous group of commits. If |
| `graph_update()` is called on a particular commit, it should later be called |
| on all parents of that commit. Parents must not be skipped, or the graph |
| output will appear incorrect. |
| + |
| `graph_update()` may be used on a pruned set of commits only if the parent list |
| has been rewritten so as to include only ancestors from the pruned set. |
| |
| * The graph API does not currently support reverse commit ordering. In |
| order to implement reverse ordering, the graphing API needs an |
| (efficient) mechanism to find the children of a commit. |
| |
| Sample usage |
| ------------ |
| |
| ------------ |
| struct commit *commit; |
| struct git_graph *graph = graph_init(opts); |
| |
| while ((commit = get_revision(opts)) != NULL) { |
| while (!graph_is_commit_finished(graph)) |
| { |
| struct strbuf sb; |
| int is_commit_line; |
| |
| strbuf_init(&sb, 0); |
| is_commit_line = graph_next_line(graph, &sb); |
| fputs(sb.buf, stdout); |
| |
| if (is_commit_line) |
| log_tree_commit(opts, commit); |
| else |
| putchar(opts->diffopt.line_termination); |
| } |
| } |
| ------------ |
| |
| Sample output |
| ------------- |
| |
| The following is an example of the output from the graph API. This output does |
| not include any commit summary information--callers are responsible for |
| outputting that information, if desired. |
| |
| ------------ |
| * |
| * |
| * |
| |\ |
| * | |
| | | * |
| | \ \ |
| | \ \ |
| *-. \ \ |
| |\ \ \ \ |
| | | * | | |
| | | | | | * |
| | | | | | * |
| | | | | | * |
| | | | | | |\ |
| | | | | | | * |
| | * | | | | | |
| | | | | | * \ |
| | | | | | |\ | |
| | | | | * | | | |
| | | | | * | | | |
| * | | | | | | | |
| | |/ / / / / / |
| |/| / / / / / |
| * | | | | | | |
| |/ / / / / / |
| * | | | | | |
| | | | | | * |
| | | | | |/ |
| | | | | * |
| ------------ |