git-commit-dag/git-commit-dag.1 at main · beldmit/git-commit-dag · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
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
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
.TH GIT\-COMMIT\-DAG 1 "August 2026" "git-commit-dag 0.1.0" "User Commands"
.SH NAME
git\-commit\-dag \- analyze commit range reorderability via patch commutation
.SH SYNOPSIS
.B git commit\-dag
.IR base .. last
.RB [ \-\-svg ]
.RB [ \-\-context
.IR N ]
.RB [ \-\-show\-files ]
.RB [ \-\-whole\-file ]
.br
.B git commit\-dag
.I base last
.RB [ ... ]
.br
.B git commit\-dag
.B \-\-explain
.I commit1 commit2
.RB [ \-\-context
.IR N ]
.RB [ \-\-whole\-file ]
.SH DESCRIPTION
.B git\-commit\-dag
takes a range of commits and builds a dependency DAG showing which
commits must come before which others during an interactive rebase.
Two commits are considered independent (reorderable) if their patches
commute \(em that is, applying them in either order produces the same result.
.PP
The range follows standard git conventions:
.I base
is excluded and
.I last
is included, just like
.BR git\-log (1)
.IR base .. last .
.PP
The dependency analysis is purely textual, based on whether commits touch
overlapping line ranges in the same files. It uses the patch commutation
algorithm from Darcs theory.
.SH OPTIONS
.TP
.I base
The base commit (excluded from the range). Any revision specification
accepted by
.BR git (1)
is valid (SHA, branch name, tag, HEAD~N, etc.).
.TP
.I last
The newest commit in the range (included).
.TP
.B \-\-explain
Instead of building a full DAG, show the specific conflicting hunks
between two commits. Requires exactly two commit arguments.
Intermediate commits between the two are automatically found and
used to adjust line numbers, avoiding false positives from line\-number
drift caused by intervening changes.
.TP
.B \-\-svg
Output the dependency graph as SVG to stdout.
.TP
.BI \-\-context " N"
Expand each hunk by
.I N
lines of context on each side before testing commutation.
The default is 0.
.BR git\-apply (1)
uses 3 lines of context, so
.B \-\-context 3
models what would happen during a real rebase more closely.
.TP
.B \-\-show\-files
After the graph, print which files cause each dependency edge.
When used with
.BR \-\-svg ,
the file names appear as edge labels.
.TP
.B \-\-whole\-file
Treat any two commits that touch the same file as dependent,
regardless of whether their hunks overlap. This is a conservative
mode useful when you want file\-level rather than hunk\-level
dependency tracking.
.SH OUTPUT
.SS Default (ASCII tree)
Commits with no dependencies are shown as roots of the tree. Commits
that depend on earlier ones are shown as children of their dependencies.
Commits that neither depend on nor are depended upon by any other commit
in the range are listed as independent.
.PP
.nf
.RS
abc1234 Fix login validation
+\-\- def5678 Add rate limiting  (depends on abc1234)

aaa1111 Update README  (independent)
.RE
.fi
.SS SVG format
With
.BR \-\-svg ,
the output is an SVG image rendered by Graphviz. Edges point from
dependencies to dependents (top\-to\-bottom layout). Redirect to a file:
.PP
.RS
.nf
git commit\-dag abc1234 def5678 \-\-svg > deps.svg
.fi
.RE
.SH EXAMPLES
Analyze the last 5 commits:
.PP
.RS
.nf
git commit\-dag HEAD~5 HEAD
.fi
.RE
.PP
Generate a visual graph of a feature branch:
.PP
.RS
.nf
git commit\-dag main..feature\-branch \-\-svg > graph.svg
.fi
.RE
Explain why two commits depend on each other:
.PP
.RS
.nf
git commit\-dag \-\-explain abc1234 def5678
.fi
.RE
.SH LIMITATIONS
.IP \(bu 3
The analysis is purely textual. Commits that touch different lines but
are semantically dependent (e.g., a function signature change and a
caller update) will not be detected as dependent.
.IP \(bu 3
Binary files, renames with content changes, and submodules are not
analyzed.
.IP \(bu 3
Without
.BR \-\-context ,
the commutation test uses zero context lines, which is slightly more
permissive than
.BR git\-apply (1)
(which uses 3 lines of context by default). Use
.B \-\-context 3
to match git's default behaviour.
.IP \(bu 3
Merge commits in the range are not supported.
.SH SEE ALSO
.BR git\-rebase (1),
.BR git\-log (1)
.SH AUTHORS
Dmitry Belyavskiy <beldmit@gmail.com>
.PP
Patch commutation algorithm derived from
.BR git\-absorb (1)
by Stephen Jung (BSD\-3\-Clause).