path: root/man1/gitk.1

'\" t
.\"     Title: gitk
.\"    Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 2024-04-24
.\"    Manual: Git Manual
.\"    Source: Git 2.45.0.rc1.1.g9f32d8da7a
.\"  Language: English
.\"
.TH "GITK" "1" "2024\-04\-24" "Git 2\&.45\&.0\&.rc1\&.1\&.g9f" "Git Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
gitk \- The Git repository browser
.SH "SYNOPSIS"
.sp
.nf
\fIgitk\fR [<options>] [<revision\-range>] [\-\-] [<path>\&...]
.fi
.sp
.SH "DESCRIPTION"
.sp
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\&.
.SH "OPTIONS"
.sp
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\&.
.sp
gitk generally only understands options with arguments in the \fIstuck\fR form (see \fBgitcli\fR(7)) due to limitations in the command\-line parser\&.
.SS "rev\-list options and arguments"
.sp
This manual page describes only the most frequently used options\&. See \fBgit-rev-list\fR(1) for a complete list\&.
.PP
\-\-all
.RS 4
Show all refs (branches, tags, etc\&.)\&.
.RE
.PP
\-\-branches[=<pattern>], \-\-tags[=<pattern>], \-\-remotes[=<pattern>]
.RS 4
Pretend as if all the branches (tags, remote branches, resp\&.) are listed on the command line as
\fI<commit>\fR\&. If
\fI<pattern>\fR
is given, limit refs to ones matching given shell glob\&. If pattern lacks
\fI?\fR,
\fI*\fR, or
\fI[\fR,
\fI/*\fR
at the end is implied\&.
.RE
.PP
\-\-since=<date>
.RS 4
Show commits more recent than a specific date\&.
.RE
.PP
\-\-until=<date>
.RS 4
Show commits older than a specific date\&.
.RE
.PP
\-\-date\-order
.RS 4
Sort commits by date when possible\&.
.RE
.PP
\-\-merge
.RS 4
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\&.
.RE
.PP
\-\-left\-right
.RS 4
Mark which side of a symmetric difference a commit is reachable from\&. Commits from the left side are prefixed with a
\fB<\fR
symbol and those from the right with a
\fB>\fR
symbol\&.
.RE
.PP
\-\-full\-history
.RS 4
When filtering history with
\fI<path>\&...\fR, does not prune some history\&. (See "History simplification" in
\fBgit-log\fR(1)
for a more detailed explanation\&.)
.RE
.PP
\-\-simplify\-merges
.RS 4
Additional option to
\fB\-\-full\-history\fR
to remove some needless merges from the resulting history, as there are no selected commits contributing to this merge\&. (See "History simplification" in
\fBgit-log\fR(1)
for a more detailed explanation\&.)
.RE
.PP
\-\-ancestry\-path
.RS 4
When given a range of commits to display (e\&.g\&.
\fIcommit1\&.\&.commit2\fR
or
\fIcommit2 ^commit1\fR), only display commits that exist directly on the ancestry chain between the
\fIcommit1\fR
and
\fIcommit2\fR, i\&.e\&. commits that are both descendants of
\fIcommit1\fR, and ancestors of
\fIcommit2\fR\&. (See "History simplification" in
\fBgit-log\fR(1)
for a more detailed explanation\&.)
.RE
.PP
\-L<start>,<end>:<file>, \-L:<funcname>:<file>
.RS 4
Trace the evolution of the line range given by
\fI<start>,<end>\fR, or by the function name regex
\fI<funcname>\fR, within the
\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
\fI<start>\fR
and
\fI<end>\fR
(or
\fI<funcname>\fR) must exist in the starting revision\&. You can specify this option more than once\&. Implies
\fB\-\-patch\fR\&. Patch output can be suppressed using
\fB\-\-no\-patch\fR, but other diff formats (namely
\fB\-\-raw\fR,
\fB\-\-numstat\fR,
\fB\-\-shortstat\fR,
\fB\-\-dirstat\fR,
\fB\-\-summary\fR,
\fB\-\-name\-only\fR,
\fB\-\-name\-status\fR,
\fB\-\-check\fR) are not currently implemented\&.
.sp
\fI<start>\fR
and
\fI<end>\fR
can take one of these forms:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
number
.sp
If
\fI<start>\fR
or
\fI<end>\fR
is a number, it specifies an absolute line number (lines count from 1)\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fB/regex/\fR
.sp
This form will use the first line matching the given POSIX regex\&. If
\fI<start>\fR
is a regex, it will search from the end of the previous
\fB\-L\fR
range, if any, otherwise from the start of file\&. If
\fI<start>\fR
is
\fB^/regex/\fR, it will search from the start of file\&. If
\fI<end>\fR
is a regex, it will search starting at the line given by
\fI<start>\fR\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
+offset or \-offset
.sp
This is only valid for
\fI<end>\fR
and will specify a number of lines before or after the line given by
\fI<start>\fR\&.
.RE
.sp
If
\fB:<funcname>\fR
is given in place of
\fI<start>\fR
and
\fI<end>\fR, it is a regular expression that denotes the range from the first funcname line that matches
\fI<funcname>\fR, up to the next funcname line\&.
\fB:<funcname>\fR
searches from the end of the previous
\fB\-L\fR
range, if any, otherwise from the start of file\&.
\fB^:<funcname>\fR
searches from the start of file\&. The function names are determined in the same way as
\fBgit diff\fR
works out patch hunk headers (see
\fIDefining a custom hunk\-header\fR
in
\fBgitattributes\fR(5))\&.
.RE
.PP
<revision range>
.RS 4
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
\fI<from>\fR
and back to
\fI<to>\fR\&. Note, more advanced revision selection can be applied\&. For a more complete list of ways to spell object names, see
\fBgitrevisions\fR(7)\&.
.RE
.PP
<path>\&...
.RS 4
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\&.
.RE
.SS "gitk\-specific options"
.PP
\-\-argscmd=<command>
.RS 4
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
\fI<revision\-range>\fR
if the set of commits to show may vary between refreshes\&.
.RE
.PP
\-\-select\-commit=<ref>
.RS 4
Select the specified commit after loading the graph\&. Default behavior is equivalent to specifying
\fI\-\-select\-commit=HEAD\fR\&.
.RE
.SH "EXAMPLES"
.PP
gitk v2\&.6\&.12\&.\&. include/scsi drivers/scsi
.RS 4
Show the changes since version
\fIv2\&.6\&.12\fR
that changed any file in the include/scsi or drivers/scsi subdirectories
.RE
.PP
gitk \-\-since="2 weeks ago" \-\- gitk
.RS 4
Show the changes during the last two weeks to the file
\fIgitk\fR\&. The "\-\-" is necessary to avoid confusion with the
\fBbranch\fR
named
\fIgitk\fR
.RE
.PP
gitk \-\-max\-count=100 \-\-all \-\- Makefile
.RS 4
Show at most 100 changes made to the file
\fIMakefile\fR\&. Instead of only looking for changes in the current branch look in all branches\&.
.RE
.SH "FILES"
.sp
User configuration and preferences are stored at:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fB$XDG_CONFIG_HOME/git/gitk\fR
if it exists, otherwise
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fB$HOME/\&.gitk\fR
if it exists
.RE
.sp
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\&.
.SH "HISTORY"
.sp
Gitk was the first graphical repository browser\&. It\(cqs written in tcl/tk\&.
.sp
\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\&.
.sp
gitk\-git/ comes from Paul Mackerras\(cqs gitk project:
.sp
.if n \{\
.RS 4
.\}
.nf
git://ozlabs\&.org/~paulus/gitk
.fi
.if n \{\
.RE
.\}
.SH "SEE ALSO"
.PP
\fIqgit(1)\fR
.RS 4
A repository browser written in C++ using Qt\&.
.RE
.PP
\fItig(1)\fR
.RS 4
A minimal repository browser and Git tool output highlighter written in C using Ncurses\&.
.RE
.SH "GIT"
.sp
Part of the \fBgit\fR(1) suite