summaryrefslogtreecommitdiff
path: root/Documentation/technical/api-history-graph.txt
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/technical/api-history-graph.txt')
-rw-r--r--Documentation/technical/api-history-graph.txt174
1 files changed, 174 insertions, 0 deletions
diff --git a/Documentation/technical/api-history-graph.txt b/Documentation/technical/api-history-graph.txt
new file mode 100644
index 0000000000..d6fc90ac7e
--- /dev/null
+++ b/Documentation/technical/api-history-graph.txt
@@ -0,0 +1,174 @@
+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.
+
+------------
+*
+*
+*
+|\
+* |
+| | *
+| \ \
+| \ \
+*-. \ \
+|\ \ \ \
+| | * | |
+| | | | | *
+| | | | | *
+| | | | | *
+| | | | | |\
+| | | | | | *
+| * | | | | |
+| | | | | * \
+| | | | | |\ |
+| | | | * | | |
+| | | | * | | |
+* | | | | | | |
+| |/ / / / / /
+|/| / / / / /
+* | | | | | |
+|/ / / / / /
+* | | | | |
+| | | | | *
+| | | | |/
+| | | | *
+------------