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.txt173
1 files changed, 0 insertions, 173 deletions
diff --git a/Documentation/technical/api-history-graph.txt b/Documentation/technical/api-history-graph.txt
deleted file mode 100644
index d0d1707c8c..0000000000
--- a/Documentation/technical/api-history-graph.txt
+++ /dev/null
@@ -1,173 +0,0 @@
-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.
-
-------------
-*
-*
-*
-|\
-* |
-| | *
-| \ \
-| \ \
-*-. \ \
-|\ \ \ \
-| | * | |
-| | | | | *
-| | | | | *
-| | | | | *
-| | | | | |\
-| | | | | | *
-| * | | | | |
-| | | | | * \
-| | | | | |\ |
-| | | | * | | |
-| | | | * | | |
-* | | | | | | |
-| |/ / / / / /
-|/| / / / / /
-* | | | | | |
-|/ / / / / /
-* | | | | |
-| | | | | *
-| | | | |/
-| | | | *
-------------