Adam Simpkins | c12172d | 2008-05-04 03:36:53 -0700 | [diff] [blame] | 1 | #ifndef GRAPH_H |
| 2 | #define GRAPH_H |
Jacob Keller | 660e113 | 2016-08-31 16:27:20 -0700 | [diff] [blame] | 3 | #include "diff.h" |
Adam Simpkins | c12172d | 2008-05-04 03:36:53 -0700 | [diff] [blame] | 4 | |
Heba Waly | 3f1480b | 2019-11-17 21:04:42 +0000 | [diff] [blame] | 5 | /** |
| 6 | * The graph API is used to draw a text-based representation of the commit |
| 7 | * history. The API generates the graph in a line-by-line fashion. |
| 8 | * |
| 9 | * Calling sequence |
| 10 | * ---------------- |
| 11 | * |
| 12 | * - Create a `struct git_graph` by calling `graph_init()`. When using the |
| 13 | * revision walking API, this is done automatically by `setup_revisions()` if |
| 14 | * the '--graph' option is supplied. |
| 15 | * |
| 16 | * - Use the revision walking API to walk through a group of contiguous commits. |
| 17 | * The `get_revision()` function automatically calls `graph_update()` each time |
| 18 | * it is invoked. |
| 19 | * |
| 20 | * - For each commit, call `graph_next_line()` repeatedly, until |
| 21 | * `graph_is_commit_finished()` returns non-zero. Each call to |
| 22 | * `graph_next_line()` will output a single line of the graph. The resulting |
| 23 | * lines will not contain any newlines. `graph_next_line()` returns 1 if the |
| 24 | * resulting line contains the current commit, or 0 if this is merely a line |
| 25 | * needed to adjust the graph before or after the current commit. This return |
| 26 | * value can be used to determine where to print the commit summary information |
| 27 | * alongside the graph output. |
| 28 | * |
| 29 | * Limitations |
| 30 | * ----------- |
| 31 | * - Check the graph_update() function for its limitations. |
| 32 | * |
| 33 | * - The graph API does not currently support reverse commit ordering. In |
| 34 | * order to implement reverse ordering, the graphing API needs an |
| 35 | * (efficient) mechanism to find the children of a commit. |
| 36 | * |
| 37 | * Sample usage |
| 38 | * ------------ |
| 39 | * |
| 40 | * ------------ |
| 41 | * struct commit *commit; |
| 42 | * struct git_graph *graph = graph_init(opts); |
| 43 | * |
| 44 | * while ((commit = get_revision(opts)) != NULL) { |
| 45 | * while (!graph_is_commit_finished(graph)) |
| 46 | * { |
| 47 | * struct strbuf sb; |
| 48 | * int is_commit_line; |
| 49 | * |
| 50 | * strbuf_init(&sb, 0); |
| 51 | * is_commit_line = graph_next_line(graph, &sb); |
| 52 | * fputs(sb.buf, stdout); |
| 53 | * |
| 54 | * if (is_commit_line) |
| 55 | * log_tree_commit(opts, commit); |
| 56 | * else |
| 57 | * putchar(opts->diffopt.line_termination); |
| 58 | * } |
| 59 | * } |
| 60 | * ------------ |
| 61 | * Sample output |
| 62 | * ------------- |
| 63 | * |
| 64 | * The following is an example of the output from the graph API. This output does |
| 65 | * not include any commit summary information--callers are responsible for |
| 66 | * outputting that information, if desired. |
| 67 | * ------------ |
| 68 | * * |
| 69 | * * |
| 70 | * * |
| 71 | * |\ |
| 72 | * * | |
| 73 | * | | * |
| 74 | * | \ \ |
| 75 | * | \ \ |
| 76 | * *-. \ \ |
| 77 | * |\ \ \ \ |
| 78 | * | | * | | |
| 79 | * | | | | | * |
| 80 | * | | | | | * |
| 81 | * | | | | | * |
| 82 | * | | | | | |\ |
| 83 | * | | | | | | * |
| 84 | * | * | | | | | |
| 85 | * | | | | | * \ |
| 86 | * | | | | | |\ | |
| 87 | * | | | | * | | | |
| 88 | * | | | | * | | | |
| 89 | * * | | | | | | | |
| 90 | * | |/ / / / / / |
| 91 | * |/| / / / / / |
| 92 | * * | | | | | | |
| 93 | * |/ / / / / / |
| 94 | * * | | | | | |
| 95 | * | | | | | * |
| 96 | * | | | | |/ |
| 97 | * | | | | * |
| 98 | * ------------ |
| 99 | * |
| 100 | */ |
| 101 | |
Adam Simpkins | c12172d | 2008-05-04 03:36:53 -0700 | [diff] [blame] | 102 | /* A graph is a pointer to this opaque structure */ |
| 103 | struct git_graph; |
| 104 | |
John Keeping | ac751a0 | 2013-03-04 00:03:37 +0000 | [diff] [blame] | 105 | /* |
Jacob Keller | 660e113 | 2016-08-31 16:27:20 -0700 | [diff] [blame] | 106 | * Called to setup global display of line_prefix diff option. |
| 107 | * |
| 108 | * Passed a diff_options structure which indicates the line_prefix and the |
| 109 | * file to output the prefix to. This is sort of a hack used so that the |
| 110 | * line_prefix will be honored by all flows which also honor "--graph" |
| 111 | * regardless of whether a graph has actually been setup. The normal graph |
| 112 | * flow will honor the exact diff_options passed, but a NULL graph will cause |
| 113 | * display of a line_prefix to stdout. |
| 114 | */ |
| 115 | void graph_setup_line_prefix(struct diff_options *diffopt); |
| 116 | |
| 117 | /* |
John Keeping | ac751a0 | 2013-03-04 00:03:37 +0000 | [diff] [blame] | 118 | * Set up a custom scheme for column colors. |
| 119 | * |
| 120 | * The default column color scheme inserts ANSI color escapes to colorize |
| 121 | * the graph. The various color escapes are stored in an array of strings |
| 122 | * where each entry corresponds to a color, except for the last entry, |
| 123 | * which denotes the escape for resetting the color back to the default. |
| 124 | * When generating the graph, strings from this array are inserted before |
| 125 | * and after the various column characters. |
| 126 | * |
| 127 | * This function allows you to enable a custom array of color escapes. |
| 128 | * The 'colors_max' argument is the index of the last "reset" entry. |
| 129 | * |
| 130 | * This functions must be called BEFORE graph_init() is called. |
| 131 | * |
| 132 | * NOTE: This function isn't used in Git outside graph.c but it is used |
Josh Soref | d05b08c | 2023-11-24 03:35:13 +0000 | [diff] [blame] | 133 | * by CGit (https://git.zx2c4.com/cgit/) to use HTML for colors. |
John Keeping | ac751a0 | 2013-03-04 00:03:37 +0000 | [diff] [blame] | 134 | */ |
| 135 | void graph_set_column_colors(const char **colors, unsigned short colors_max); |
Johan Herland | 1e3d411 | 2010-07-13 23:23:39 +0200 | [diff] [blame] | 136 | |
| 137 | /* |
Adam Simpkins | c12172d | 2008-05-04 03:36:53 -0700 | [diff] [blame] | 138 | * Create a new struct git_graph. |
Adam Simpkins | c12172d | 2008-05-04 03:36:53 -0700 | [diff] [blame] | 139 | */ |
Adam Simpkins | 7528f27 | 2008-05-25 00:07:21 -0700 | [diff] [blame] | 140 | struct git_graph *graph_init(struct rev_info *opt); |
Adam Simpkins | c12172d | 2008-05-04 03:36:53 -0700 | [diff] [blame] | 141 | |
| 142 | /* |
Alex Henrie | dccf6c1 | 2022-02-11 09:36:24 -0700 | [diff] [blame] | 143 | * Free a struct git_graph. |
| 144 | */ |
| 145 | void graph_clear(struct git_graph *graph); |
| 146 | |
| 147 | /* |
Adam Simpkins | c12172d | 2008-05-04 03:36:53 -0700 | [diff] [blame] | 148 | * Update a git_graph with a new commit. |
| 149 | * This will cause the graph to begin outputting lines for the new commit |
| 150 | * the next time graph_next_line() is called. |
| 151 | * |
| 152 | * If graph_update() is called before graph_is_commit_finished() returns 1, |
| 153 | * the next call to graph_next_line() will output an ellipsis ("...") |
| 154 | * to indicate that a portion of the graph is missing. |
Heba Waly | 3f1480b | 2019-11-17 21:04:42 +0000 | [diff] [blame] | 155 | * |
| 156 | * Limitations: |
| 157 | * ----------- |
| 158 | * |
| 159 | * - `graph_update()` must be called with commits in topological order. It should |
| 160 | * not be called on a commit if it has already been invoked with an ancestor of |
| 161 | * that commit, or the graph output will be incorrect. |
| 162 | * |
| 163 | * - `graph_update()` must be called on a contiguous group of commits. If |
| 164 | * `graph_update()` is called on a particular commit, it should later be called |
| 165 | * on all parents of that commit. Parents must not be skipped, or the graph |
| 166 | * output will appear incorrect. |
| 167 | * |
| 168 | * - `graph_update()` may be used on a pruned set of commits only if the parent list |
| 169 | * has been rewritten so as to include only ancestors from the pruned set. |
Adam Simpkins | c12172d | 2008-05-04 03:36:53 -0700 | [diff] [blame] | 170 | */ |
| 171 | void graph_update(struct git_graph *graph, struct commit *commit); |
| 172 | |
| 173 | /* |
Adam Simpkins | c12172d | 2008-05-04 03:36:53 -0700 | [diff] [blame] | 174 | * Determine if a graph has finished outputting lines for the current |
| 175 | * commit. |
| 176 | * |
| 177 | * Returns 1 if graph_next_line() needs to be called again before |
| 178 | * graph_update() should be called. Returns 0 if no more lines are needed |
| 179 | * for this commit. If 0 is returned, graph_next_line() may still be |
| 180 | * called without calling graph_update(), and it will merely output |
| 181 | * appropriate "vertical padding" in the graph. |
Heba Waly | 3f1480b | 2019-11-17 21:04:42 +0000 | [diff] [blame] | 182 | * |
| 183 | * If `graph_update()` is called before all lines for the current commit have |
| 184 | * been printed, the next call to `graph_next_line()` will output an ellipsis, |
| 185 | * to indicate that a portion of the graph was omitted. |
Adam Simpkins | c12172d | 2008-05-04 03:36:53 -0700 | [diff] [blame] | 186 | */ |
| 187 | int graph_is_commit_finished(struct git_graph const *graph); |
| 188 | |
John Keeping | ac751a0 | 2013-03-04 00:03:37 +0000 | [diff] [blame] | 189 | /* |
| 190 | * Output the next line for a graph. |
| 191 | * This formats the next graph line into the specified strbuf. It is not |
| 192 | * terminated with a newline. |
| 193 | * |
| 194 | * Returns 1 if the line includes the current commit, and 0 otherwise. |
| 195 | * graph_next_line() will return 1 exactly once for each time |
| 196 | * graph_update() is called. |
| 197 | * |
| 198 | * NOTE: This function isn't used in Git outside graph.c but it is used |
Josh Soref | d05b08c | 2023-11-24 03:35:13 +0000 | [diff] [blame] | 199 | * by CGit (https://git.zx2c4.com/cgit/) to wrap HTML around graph lines. |
John Keeping | ac751a0 | 2013-03-04 00:03:37 +0000 | [diff] [blame] | 200 | */ |
| 201 | int graph_next_line(struct git_graph *graph, struct strbuf *sb); |
| 202 | |
Adam Simpkins | c12172d | 2008-05-04 03:36:53 -0700 | [diff] [blame] | 203 | |
| 204 | /* |
Josef Kufner | 3ad87c8 | 2016-06-16 20:18:37 +0700 | [diff] [blame] | 205 | * Return current width of the graph in on-screen characters. |
| 206 | */ |
| 207 | int graph_width(struct git_graph *graph); |
| 208 | |
| 209 | /* |
Adam Simpkins | c12172d | 2008-05-04 03:36:53 -0700 | [diff] [blame] | 210 | * graph_show_*: helper functions for printing to stdout |
| 211 | */ |
| 212 | |
| 213 | |
| 214 | /* |
| 215 | * If the graph is non-NULL, print the history graph to stdout, |
| 216 | * up to and including the line containing this commit. |
| 217 | * Does not print a terminating newline on the last line. |
| 218 | */ |
| 219 | void graph_show_commit(struct git_graph *graph); |
| 220 | |
| 221 | /* |
| 222 | * If the graph is non-NULL, print one line of the history graph to stdout. |
| 223 | * Does not print a terminating newline on the last line. |
| 224 | */ |
| 225 | void graph_show_oneline(struct git_graph *graph); |
| 226 | |
| 227 | /* |
| 228 | * If the graph is non-NULL, print one line of vertical graph padding to |
| 229 | * stdout. Does not print a terminating newline on the last line. |
| 230 | */ |
| 231 | void graph_show_padding(struct git_graph *graph); |
| 232 | |
| 233 | /* |
| 234 | * If the graph is non-NULL, print the rest of the history graph for this |
| 235 | * commit to stdout. Does not print a terminating newline on the last line. |
Heba Waly | 3f1480b | 2019-11-17 21:04:42 +0000 | [diff] [blame] | 236 | * Returns 1 if output was printed, and 0 if no output was necessary. |
Adam Simpkins | c12172d | 2008-05-04 03:36:53 -0700 | [diff] [blame] | 237 | */ |
| 238 | int graph_show_remainder(struct git_graph *graph); |
| 239 | |
| 240 | /* |
Adam Simpkins | c12172d | 2008-05-04 03:36:53 -0700 | [diff] [blame] | 241 | * Print a commit message strbuf and the remainder of the graph to stdout. |
| 242 | * |
| 243 | * This is similar to graph_show_strbuf(), but it always prints the |
| 244 | * remainder of the graph. |
| 245 | * |
Heba Waly | 3f1480b | 2019-11-17 21:04:42 +0000 | [diff] [blame] | 246 | * It is better than directly calling `graph_show_strbuf()` followed by |
| 247 | * `graph_show_remainder()` since it properly handles buffers that do not end in |
| 248 | * a terminating newline. |
| 249 | * |
Adam Simpkins | c12172d | 2008-05-04 03:36:53 -0700 | [diff] [blame] | 250 | * If the strbuf ends with a newline, the output printed by |
| 251 | * graph_show_commit_msg() will end with a newline. If the strbuf is |
| 252 | * missing a terminating newline (including if it is empty), the output |
| 253 | * printed by graph_show_commit_msg() will also be missing a terminating |
| 254 | * newline. |
Jacob Keller | 660e113 | 2016-08-31 16:27:20 -0700 | [diff] [blame] | 255 | * |
| 256 | * Note that unlike some other graph display functions, you must pass the file |
| 257 | * handle directly. It is assumed that this is the same file handle as the |
| 258 | * file specified by the graph diff options. This is necessary so that |
| 259 | * graph_show_commit_msg can be called even with a NULL graph. |
Adam Simpkins | c12172d | 2008-05-04 03:36:53 -0700 | [diff] [blame] | 260 | */ |
Jacob Keller | 660e113 | 2016-08-31 16:27:20 -0700 | [diff] [blame] | 261 | void graph_show_commit_msg(struct git_graph *graph, |
| 262 | FILE *file, |
| 263 | struct strbuf const *sb); |
Adam Simpkins | c12172d | 2008-05-04 03:36:53 -0700 | [diff] [blame] | 264 | |
| 265 | #endif /* GRAPH_H */ |