Add history graph API
This new API allows the commit history to be displayed as a text-based graphical representation. Signed-off-by: Adam Simpkins <adam@adamsimpkins.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
This commit is contained in:

committed by
Junio C Hamano

parent
885cf80899
commit
c12172d2ea
176
Documentation/technical/api-history-graph.txt
Normal file
176
Documentation/technical/api-history-graph.txt
Normal file
@ -0,0 +1,176 @@
|
||||
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_release()` destroys a `struct git_graph`, and frees the memory
|
||||
associated with it.
|
||||
|
||||
* `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()` until it returns 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. This should not be called if the commit line has
|
||||
already been printed, or it will loop forever.
|
||||
|
||||
* `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()`.
|
||||
|
||||
* Use the revision walking API to walk through a group of contiguous commits.
|
||||
|
||||
* For each commit traversed, call `graph_update()` to move the graph to the
|
||||
next commit. Once `graph_update()` has been called, 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();
|
||||
|
||||
while ((commit = get_revision(opts)) != NULL) {
|
||||
graph_update(graph, commit);
|
||||
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);
|
||||
}
|
||||
}
|
||||
|
||||
graph_release(graph);
|
||||
------------
|
||||
|
||||
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.
|
||||
|
||||
------------
|
||||
*
|
||||
*
|
||||
M
|
||||
|\
|
||||
* |
|
||||
| | *
|
||||
| \ \
|
||||
| \ \
|
||||
M-. \ \
|
||||
|\ \ \ \
|
||||
| | * | |
|
||||
| | | | | *
|
||||
| | | | | *
|
||||
| | | | | M
|
||||
| | | | | |\
|
||||
| | | | | | *
|
||||
| * | | | | |
|
||||
| | | | | M \
|
||||
| | | | | |\ |
|
||||
| | | | * | | |
|
||||
| | | | * | | |
|
||||
* | | | | | | |
|
||||
| |/ / / / / /
|
||||
|/| / / / / /
|
||||
* | | | | | |
|
||||
|/ / / / / /
|
||||
* | | | | |
|
||||
| | | | | *
|
||||
| | | | |/
|
||||
| | | | *
|
||||
------------
|
Reference in New Issue
Block a user