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