| blob | 8c3afda235a841f94af73831ee46be0ff26819cf |
1 '\" t
2 .\" Title: gitk
3 .\" Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
4 .\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
5 .\" Date: 2024-06-10
6 .\" Manual: Git Manual
7 .\" Source: Git 2.45.2.457.g8d94cfb545
8 .\" Language: English
9 .\"
10 .TH "GITK" "1" "2024\-06\-10" "Git 2\&.45\&.2\&.457\&.g8d94cf" "Git Manual"
11 .\" -----------------------------------------------------------------
12 .\" * Define some portability stuff
13 .\" -----------------------------------------------------------------
14 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
15 .\" http://bugs.debian.org/507673
16 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
17 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
18 .ie \n(.g .ds Aq \(aq
19 .el .ds Aq '
20 .\" -----------------------------------------------------------------
21 .\" * set default formatting
22 .\" -----------------------------------------------------------------
23 .\" disable hyphenation
24 .nh
25 .\" disable justification (adjust text to left margin only)
26 .ad l
27 .\" -----------------------------------------------------------------
28 .\" * MAIN CONTENT STARTS HERE *
29 .\" -----------------------------------------------------------------
30 .SH "NAME"
31 gitk \- The Git repository browser
32 .SH "SYNOPSIS"
33 .sp
34 .nf
35 \fIgitk\fR [<options>] [<revision\-range>] [\-\-] [<path>\&...]
36 .fi
37 .sp
38 .SH "DESCRIPTION"
39 .sp
40 Displays changes in a repository or a selected set of commits\&. This includes visualizing the commit graph, showing information related to each commit, and the files in the trees of each revision\&.
41 .SH "OPTIONS"
42 .sp
43 To control which revisions to show, gitk supports most options applicable to the \fIgit rev\-list\fR command\&. It also supports a few options applicable to the \fIgit diff\-*\fR commands to control how the changes each commit introduces are shown\&. Finally, it supports some gitk\-specific options\&.
44 .sp
45 gitk generally only understands options with arguments in the \fIstuck\fR form (see \fBgitcli\fR(7)) due to limitations in the command\-line parser\&.
46 .SS "rev\-list options and arguments"
47 .sp
48 This manual page describes only the most frequently used options\&. See \fBgit-rev-list\fR(1) for a complete list\&.
49 .PP
50 \-\-all
51 .RS 4
52 Show all refs (branches, tags, etc\&.)\&.
53 .RE
54 .PP
55 \-\-branches[=<pattern>], \-\-tags[=<pattern>], \-\-remotes[=<pattern>]
56 .RS 4
57 Pretend as if all the branches (tags, remote branches, resp\&.) are listed on the command line as
58 \fI<commit>\fR\&. If
59 \fI<pattern>\fR
60 is given, limit refs to ones matching given shell glob\&. If pattern lacks
61 \fI?\fR,
62 \fI*\fR, or
63 \fI[\fR,
64 \fI/*\fR
65 at the end is implied\&.
66 .RE
67 .PP
68 \-\-since=<date>
69 .RS 4
70 Show commits more recent than a specific date\&.
71 .RE
72 .PP
73 \-\-until=<date>
74 .RS 4
75 Show commits older than a specific date\&.
76 .RE
77 .PP
78 \-\-date\-order
79 .RS 4
80 Sort commits by date when possible\&.
81 .RE
82 .PP
83 \-\-merge
84 .RS 4
85 After an attempt to merge stops with conflicts, show the commits on the history between two branches (i\&.e\&. the HEAD and the MERGE_HEAD) that modify the conflicted files and do not exist on all the heads being merged\&.
86 .RE
87 .PP
88 \-\-left\-right
89 .RS 4
90 Mark which side of a symmetric difference a commit is reachable from\&. Commits from the left side are prefixed with a
91 \fB<\fR
92 symbol and those from the right with a
93 \fB>\fR
94 symbol\&.
95 .RE
96 .PP
97 \-\-full\-history
98 .RS 4
99 When filtering history with
100 \fI<path>\&...\fR, does not prune some history\&. (See "History simplification" in
101 \fBgit-log\fR(1)
102 for a more detailed explanation\&.)
103 .RE
104 .PP
105 \-\-simplify\-merges
106 .RS 4
107 Additional option to
108 \fB\-\-full\-history\fR
109 to remove some needless merges from the resulting history, as there are no selected commits contributing to this merge\&. (See "History simplification" in
110 \fBgit-log\fR(1)
111 for a more detailed explanation\&.)
112 .RE
113 .PP
114 \-\-ancestry\-path
115 .RS 4
116 When given a range of commits to display (e\&.g\&.
117 \fIcommit1\&.\&.commit2\fR
118 or
119 \fIcommit2 ^commit1\fR), only display commits that exist directly on the ancestry chain between the
120 \fIcommit1\fR
121 and
122 \fIcommit2\fR, i\&.e\&. commits that are both descendants of
123 \fIcommit1\fR, and ancestors of
124 \fIcommit2\fR\&. (See "History simplification" in
125 \fBgit-log\fR(1)
126 for a more detailed explanation\&.)
127 .RE
128 .PP
129 \-L<start>,<end>:<file>, \-L:<funcname>:<file>
130 .RS 4
131 Trace the evolution of the line range given by
132 \fI<start>,<end>\fR, or by the function name regex
133 \fI<funcname>\fR, within the
134 \fI<file>\fR\&. You may not give any pathspec limiters\&. This is currently limited to a walk starting from a single revision, i\&.e\&., you may only give zero or one positive revision arguments, and
135 \fI<start>\fR
136 and
137 \fI<end>\fR
138 (or
139 \fI<funcname>\fR) must exist in the starting revision\&. You can specify this option more than once\&. Implies
140 \fB\-\-patch\fR\&. Patch output can be suppressed using
141 \fB\-\-no\-patch\fR, but other diff formats (namely
142 \fB\-\-raw\fR,
143 \fB\-\-numstat\fR,
144 \fB\-\-shortstat\fR,
145 \fB\-\-dirstat\fR,
146 \fB\-\-summary\fR,
147 \fB\-\-name\-only\fR,
148 \fB\-\-name\-status\fR,
149 \fB\-\-check\fR) are not currently implemented\&.
150 .sp
151 \fI<start>\fR
152 and
153 \fI<end>\fR
154 can take one of these forms:
155 .sp
156 .RS 4
157 .ie n \{\
158 \h'-04'\(bu\h'+03'\c
159 .\}
160 .el \{\
161 .sp -1
162 .IP \(bu 2.3
163 .\}
164 number
165 .sp
166 If
167 \fI<start>\fR
168 or
169 \fI<end>\fR
170 is a number, it specifies an absolute line number (lines count from 1)\&.
171 .RE
172 .sp
173 .RS 4
174 .ie n \{\
175 \h'-04'\(bu\h'+03'\c
176 .\}
177 .el \{\
178 .sp -1
179 .IP \(bu 2.3
180 .\}
181 \fB/regex/\fR
182 .sp
183 This form will use the first line matching the given POSIX regex\&. If
184 \fI<start>\fR
185 is a regex, it will search from the end of the previous
186 \fB\-L\fR
187 range, if any, otherwise from the start of file\&. If
188 \fI<start>\fR
189 is
190 \fB^/regex/\fR, it will search from the start of file\&. If
191 \fI<end>\fR
192 is a regex, it will search starting at the line given by
193 \fI<start>\fR\&.
194 .RE
195 .sp
196 .RS 4
197 .ie n \{\
198 \h'-04'\(bu\h'+03'\c
199 .\}
200 .el \{\
201 .sp -1
202 .IP \(bu 2.3
203 .\}
204 +offset or \-offset
205 .sp
206 This is only valid for
207 \fI<end>\fR
208 and will specify a number of lines before or after the line given by
209 \fI<start>\fR\&.
210 .RE
211 .sp
212 If
213 \fB:<funcname>\fR
214 is given in place of
215 \fI<start>\fR
216 and
217 \fI<end>\fR, it is a regular expression that denotes the range from the first funcname line that matches
218 \fI<funcname>\fR, up to the next funcname line\&.
219 \fB:<funcname>\fR
220 searches from the end of the previous
221 \fB\-L\fR
222 range, if any, otherwise from the start of file\&.
223 \fB^:<funcname>\fR
224 searches from the start of file\&. The function names are determined in the same way as
225 \fBgit diff\fR
226 works out patch hunk headers (see
227 \fIDefining a custom hunk\-header\fR
228 in
229 \fBgitattributes\fR(5))\&.
230 .RE
231 .PP
232 <revision range>
233 .RS 4
234 Limit the revisions to show\&. This can be either a single revision meaning show from the given revision and back, or it can be a range in the form "\fI<from>\fR\&.\&.\fI<to>\fR" to show all revisions between
235 \fI<from>\fR
236 and back to
237 \fI<to>\fR\&. Note, more advanced revision selection can be applied\&. For a more complete list of ways to spell object names, see
238 \fBgitrevisions\fR(7)\&.
239 .RE
240 .PP
241 <path>\&...
242 .RS 4
243 Limit commits to the ones touching files in the given paths\&. Note, to avoid ambiguity with respect to revision names use "\-\-" to separate the paths from any preceding options\&.
244 .RE
245 .SS "gitk\-specific options"
246 .PP
247 \-\-argscmd=<command>
248 .RS 4
249 Command to be run each time gitk has to determine the revision range to show\&. The command is expected to print on its standard output a list of additional revisions to be shown, one per line\&. Use this instead of explicitly specifying a
250 \fI<revision\-range>\fR
251 if the set of commits to show may vary between refreshes\&.
252 .RE
253 .PP
254 \-\-select\-commit=<ref>
255 .RS 4
256 Select the specified commit after loading the graph\&. Default behavior is equivalent to specifying
257 \fI\-\-select\-commit=HEAD\fR\&.
258 .RE
259 .SH "EXAMPLES"
260 .PP
261 gitk v2\&.6\&.12\&.\&. include/scsi drivers/scsi
262 .RS 4
263 Show the changes since version
264 \fIv2\&.6\&.12\fR
265 that changed any file in the include/scsi or drivers/scsi subdirectories
266 .RE
267 .PP
268 gitk \-\-since="2 weeks ago" \-\- gitk
269 .RS 4
270 Show the changes during the last two weeks to the file
271 \fIgitk\fR\&. The "\-\-" is necessary to avoid confusion with the
272 \fBbranch\fR
273 named
274 \fIgitk\fR
275 .RE
276 .PP
277 gitk \-\-max\-count=100 \-\-all \-\- Makefile
278 .RS 4
279 Show at most 100 changes made to the file
280 \fIMakefile\fR\&. Instead of only looking for changes in the current branch look in all branches\&.
281 .RE
282 .SH "FILES"
283 .sp
284 User configuration and preferences are stored at:
285 .sp
286 .RS 4
287 .ie n \{\
288 \h'-04'\(bu\h'+03'\c
289 .\}
290 .el \{\
291 .sp -1
292 .IP \(bu 2.3
293 .\}
294 \fB$XDG_CONFIG_HOME/git/gitk\fR
295 if it exists, otherwise
296 .RE
297 .sp
298 .RS 4
299 .ie n \{\
300 \h'-04'\(bu\h'+03'\c
301 .\}
302 .el \{\
303 .sp -1
304 .IP \(bu 2.3
305 .\}
306 \fB$HOME/\&.gitk\fR
307 if it exists
308 .RE
309 .sp
310 If neither of the above exist then \fB$XDG_CONFIG_HOME/git/gitk\fR is created and used by default\&. If \fI$XDG_CONFIG_HOME\fR is not set it defaults to \fB$HOME/\&.config\fR in all cases\&.
311 .SH "HISTORY"
312 .sp
313 Gitk was the first graphical repository browser\&. It\(cqs written in tcl/tk\&.
314 .sp
315 \fIgitk\fR is actually maintained as an independent project, but stable versions are distributed as part of the Git suite for the convenience of end users\&.
316 .sp
317 gitk\-git/ comes from Paul Mackerras\(cqs gitk project:
318 .sp
319 .if n \{\
320 .RS 4
321 .\}
322 .nf
323 git://ozlabs\&.org/~paulus/gitk
324 .fi
325 .if n \{\
326 .RE
327 .\}
328 .SH "SEE ALSO"
329 .PP
330 \fIqgit(1)\fR
331 .RS 4
332 A repository browser written in C++ using Qt\&.
333 .RE
334 .PP
335 \fItig(1)\fR
336 .RS 4
337 A minimal repository browser and Git tool output highlighter written in C using Ncurses\&.
338 .RE
339 .SH "GIT"
340 .sp
341 Part of the \fBgit\fR(1) suite