]>
Commit | Line | Data |
---|---|---|
c12172d2 AS |
1 | history graph API |
2 | ================= | |
3 | ||
4 | The graph API is used to draw a text-based representation of the commit | |
5 | history. The API generates the graph in a line-by-line fashion. | |
6 | ||
7 | Functions | |
8 | --------- | |
9 | ||
10 | Core functions: | |
11 | ||
12 | * `graph_init()` creates a new `struct git_graph` | |
13 | ||
c12172d2 AS |
14 | * `graph_update()` moves the graph to a new commit. |
15 | ||
16 | * `graph_next_line()` outputs the next line of the graph into a strbuf. It | |
17 | does not add a terminating newline. | |
18 | ||
19 | * `graph_padding_line()` outputs a line of vertical padding in the graph. It | |
20 | is similar to `graph_next_line()`, but is guaranteed to never print the line | |
21 | containing the current commit. Where `graph_next_line()` would print the | |
22 | commit line next, `graph_padding_line()` prints a line that simply extends | |
23 | all branch lines downwards one row, leaving their positions unchanged. | |
24 | ||
25 | * `graph_is_commit_finished()` determines if the graph has output all lines | |
26 | necessary for the current commit. If `graph_update()` is called before all | |
27 | lines for the current commit have been printed, the next call to | |
28 | `graph_next_line()` will output an ellipsis, to indicate that a portion of | |
29 | the graph was omitted. | |
30 | ||
31 | The following utility functions are wrappers around `graph_next_line()` and | |
32 | `graph_is_commit_finished()`. They always print the output to stdout. | |
33 | They can all be called with a NULL graph argument, in which case no graph | |
34 | output will be printed. | |
35 | ||
656197ad MK |
36 | * `graph_show_commit()` calls `graph_next_line()` and |
37 | `graph_is_commit_finished()` until one of them return non-zero. This prints | |
38 | all graph lines up to, and including, the line containing this commit. | |
39 | Output is printed to stdout. The last line printed does not contain a | |
40 | terminating newline. | |
c12172d2 AS |
41 | |
42 | * `graph_show_oneline()` calls `graph_next_line()` and prints the result to | |
43 | stdout. The line printed does not contain a terminating newline. | |
44 | ||
45 | * `graph_show_padding()` calls `graph_padding_line()` and prints the result to | |
46 | stdout. The line printed does not contain a terminating newline. | |
47 | ||
48 | * `graph_show_remainder()` calls `graph_next_line()` until | |
49 | `graph_is_commit_finished()` returns non-zero. Output is printed to stdout. | |
50 | The last line printed does not contain a terminating newline. Returns 1 if | |
51 | output was printed, and 0 if no output was necessary. | |
52 | ||
53 | * `graph_show_strbuf()` prints the specified strbuf to stdout, prefixing all | |
54 | lines but the first with a graph line. The caller is responsible for | |
55 | ensuring graph output for the first line has already been printed to stdout. | |
56 | (This can be done with `graph_show_commit()` or `graph_show_oneline()`.) If | |
57 | a NULL graph is supplied, the strbuf is printed as-is. | |
58 | ||
59 | * `graph_show_commit_msg()` is similar to `graph_show_strbuf()`, but it also | |
60 | prints the remainder of the graph, if more lines are needed after the strbuf | |
61 | ends. It is better than directly calling `graph_show_strbuf()` followed by | |
62 | `graph_show_remainder()` since it properly handles buffers that do not end in | |
63 | a terminating newline. The output printed by `graph_show_commit_msg()` will | |
64 | end in a newline if and only if the strbuf ends in a newline. | |
65 | ||
66 | Data structure | |
67 | -------------- | |
68 | `struct git_graph` is an opaque data type used to store the current graph | |
69 | state. | |
70 | ||
71 | Calling sequence | |
72 | ---------------- | |
73 | ||
7fefda5c AS |
74 | * Create a `struct git_graph` by calling `graph_init()`. When using the |
75 | revision walking API, this is done automatically by `setup_revisions()` if | |
76 | the '--graph' option is supplied. | |
c12172d2 AS |
77 | |
78 | * Use the revision walking API to walk through a group of contiguous commits. | |
7fefda5c AS |
79 | The `get_revision()` function automatically calls `graph_update()` each time |
80 | it is invoked. | |
c12172d2 | 81 | |
7fefda5c | 82 | * For each commit, call `graph_next_line()` repeatedly, until |
42ce44e0 | 83 | `graph_is_commit_finished()` returns non-zero. Each call to |
7fefda5c | 84 | `graph_next_line()` will output a single line of the graph. The resulting |
c12172d2 AS |
85 | lines will not contain any newlines. `graph_next_line()` returns 1 if the |
86 | resulting line contains the current commit, or 0 if this is merely a line | |
87 | needed to adjust the graph before or after the current commit. This return | |
88 | value can be used to determine where to print the commit summary information | |
89 | alongside the graph output. | |
90 | ||
91 | Limitations | |
92 | ----------- | |
93 | ||
94 | * `graph_update()` must be called with commits in topological order. It should | |
95 | not be called on a commit if it has already been invoked with an ancestor of | |
96 | that commit, or the graph output will be incorrect. | |
97 | ||
98 | * `graph_update()` must be called on a contiguous group of commits. If | |
99 | `graph_update()` is called on a particular commit, it should later be called | |
100 | on all parents of that commit. Parents must not be skipped, or the graph | |
101 | output will appear incorrect. | |
102 | + | |
103 | `graph_update()` may be used on a pruned set of commits only if the parent list | |
104 | has been rewritten so as to include only ancestors from the pruned set. | |
105 | ||
106 | * The graph API does not currently support reverse commit ordering. In | |
107 | order to implement reverse ordering, the graphing API needs an | |
108 | (efficient) mechanism to find the children of a commit. | |
109 | ||
110 | Sample usage | |
111 | ------------ | |
112 | ||
113 | ------------ | |
114 | struct commit *commit; | |
7528f27d | 115 | struct git_graph *graph = graph_init(opts); |
c12172d2 AS |
116 | |
117 | while ((commit = get_revision(opts)) != NULL) { | |
c12172d2 AS |
118 | while (!graph_is_commit_finished(graph)) |
119 | { | |
120 | struct strbuf sb; | |
121 | int is_commit_line; | |
122 | ||
123 | strbuf_init(&sb, 0); | |
124 | is_commit_line = graph_next_line(graph, &sb); | |
125 | fputs(sb.buf, stdout); | |
126 | ||
127 | if (is_commit_line) | |
128 | log_tree_commit(opts, commit); | |
129 | else | |
130 | putchar(opts->diffopt.line_termination); | |
131 | } | |
132 | } | |
c12172d2 AS |
133 | ------------ |
134 | ||
135 | Sample output | |
136 | ------------- | |
137 | ||
138 | The following is an example of the output from the graph API. This output does | |
139 | not include any commit summary information--callers are responsible for | |
140 | outputting that information, if desired. | |
141 | ||
142 | ------------ | |
143 | * | |
144 | * | |
7b60d0d3 | 145 | * |
c12172d2 AS |
146 | |\ |
147 | * | | |
148 | | | * | |
149 | | \ \ | |
150 | | \ \ | |
7b60d0d3 | 151 | *-. \ \ |
c12172d2 AS |
152 | |\ \ \ \ |
153 | | | * | | | |
154 | | | | | | * | |
155 | | | | | | * | |
7b60d0d3 | 156 | | | | | | * |
c12172d2 AS |
157 | | | | | | |\ |
158 | | | | | | | * | |
159 | | * | | | | | | |
7b60d0d3 | 160 | | | | | | * \ |
c12172d2 AS |
161 | | | | | | |\ | |
162 | | | | | * | | | | |
163 | | | | | * | | | | |
164 | * | | | | | | | | |
165 | | |/ / / / / / | |
166 | |/| / / / / / | |
167 | * | | | | | | | |
168 | |/ / / / / / | |
169 | * | | | | | | |
170 | | | | | | * | |
171 | | | | | |/ | |
172 | | | | | * | |
173 | ------------ |