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