mirror of
https://github.com/git/git
synced 2024-10-31 01:43:41 +00:00
aa8dc9679a
graph_release() was removed in 064bfbd
. Cut it from the API
documentation and a comment.
Signed-off-by: Greg Price <price@ksplice.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
174 lines
6 KiB
Text
174 lines
6 KiB
Text
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()` 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()`. 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 go
|
|
`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) {
|
|
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);
|
|
}
|
|
}
|
|
------------
|
|
|
|
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.
|
|
|
|
------------
|
|
*
|
|
*
|
|
*
|
|
|\
|
|
* |
|
|
| | *
|
|
| \ \
|
|
| \ \
|
|
*-. \ \
|
|
|\ \ \ \
|
|
| | * | |
|
|
| | | | | *
|
|
| | | | | *
|
|
| | | | | *
|
|
| | | | | |\
|
|
| | | | | | *
|
|
| * | | | | |
|
|
| | | | | * \
|
|
| | | | | |\ |
|
|
| | | | * | | |
|
|
| | | | * | | |
|
|
* | | | | | | |
|
|
| |/ / / / / /
|
|
|/| / / / / /
|
|
* | | | | | |
|
|
|/ / / / / /
|
|
* | | | | |
|
|
| | | | | *
|
|
| | | | |/
|
|
| | | | *
|
|
------------
|