summaryrefslogtreecommitdiff
path: root/Documentation/gitk.txt
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/gitk.txt')
-rw-r--r--Documentation/gitk.txt139
1 files changed, 110 insertions, 29 deletions
diff --git a/Documentation/gitk.txt b/Documentation/gitk.txt
index a17a354936..6ade002176 100644
--- a/Documentation/gitk.txt
+++ b/Documentation/gitk.txt
@@ -3,12 +3,12 @@ gitk(1)
NAME
----
-gitk - The git repository browser
+gitk - The Git repository browser
SYNOPSIS
--------
[verse]
-'gitk' [<option>...] [<revs>] [--] [<path>...]
+'gitk' [<options>] [<revision range>] [\--] [<path>...]
DESCRIPTION
-----------
@@ -16,21 +16,38 @@ 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.
-Historically, gitk was the first repository browser. It's written in tcl/tk
-and started off in a separate repository but was later merged into the main
-git repository.
-
OPTIONS
-------
-To control which revisions to show, the command takes options applicable to
-the 'git rev-list' command (see linkgit:git-rev-list[1]).
-This manual page describes only the most
-frequently used options.
--n <number>::
---max-count=<number>::
+To control which revisions to show, gitk supports most options
+applicable to the 'git rev-list' command. It also supports a few
+options applicable to the 'git diff-*' commands to control how the
+changes each commit introduces are shown. Finally, it supports some
+gitk-specific options.
+
+gitk generally only understands options with arguments in the
+'sticked' form (see linkgit:gitcli[7]) due to limitations in the
+command-line parser.
+
+rev-list options and arguments
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This manual page describes only the most frequently used options. See
+linkgit:git-rev-list[1] for a complete list.
+
+--all::
+
+ Show all refs (branches, tags, etc.).
+
+--branches[=<pattern>]::
+--tags[=<pattern>]::
+--remotes[=<pattern>]::
- Limits the number of commits to show.
+ Pretend as if all the branches (tags, remote branches, resp.)
+ are listed on the command line as '<commit>'. If '<pattern>'
+ is given, limit refs to ones matching given shell glob. If
+ pattern lacks '?', '{asterisk}', or '[', '/{asterisk}' at the
+ end is implied.
--since=<date>::
@@ -40,9 +57,9 @@ frequently used options.
Show commits older than a specific date.
---all::
+--date-order::
- Show all branches.
+ Sort commits by date when possible.
--merge::
@@ -51,19 +68,53 @@ frequently used options.
that modify the conflicted files and do not exist on all the heads
being merged.
---argscmd=<command>::
- Command to be run each time gitk has to determine the list of
- <revs> to show. The command is expected to print on its standard
- output a list of additional revs to be shown, one per line.
- Use this instead of explicitly specifying <revs> if the set of
- commits to show may vary between refreshes.
+--left-right::
---select-commit=<ref>::
+ Mark which side of a symmetric diff a commit is reachable
+ from. Commits from the left side are prefixed with a `<`
+ symbol and those from the right with a `>` symbol.
- Automatically select the specified commit after loading the graph.
- Default behavior is equivalent to specifying '--select-commit=HEAD'.
+--full-history::
+
+ When filtering history with '<path>...', does not prune some
+ history. (See "History simplification" in linkgit:git-log[1]
+ for a more detailed explanation.)
+
+--simplify-merges::
+
+ Additional option to '--full-history' to remove some needless
+ merges from the resulting history, as there are no selected
+ commits contributing to this merge. (See "History
+ simplification" in linkgit:git-log[1] for a more detailed
+ explanation.)
+
+--ancestry-path::
-<revs>::
+ When given a range of commits to display
+ (e.g. 'commit1..commit2' or 'commit2 {caret}commit1'), only
+ display commits that exist directly on the ancestry chain
+ between the 'commit1' and 'commit2', i.e. commits that are
+ both descendants of 'commit1', and ancestors of 'commit2'.
+ (See "History simplification" in linkgit:git-log[1] for a more
+ detailed explanation.)
+
+-L<start>,<end>:<file>::
+-L:<funcname>:<file>::
+
+ Trace the evolution of the line range given by "<start>,<end>"
+ (or the function name regex <funcname>) within the <file>. 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.
+ You can specify this option more than once.
++
+*Note:* gitk (unlike linkgit:git-log[1]) currently only understands
+this option if you specify it "glued together" with its argument. Do
+*not* put a space after `-L`.
++
+include::line-range-format.txt[]
+
+<revision range>::
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
@@ -78,6 +129,23 @@ frequently used options.
avoid ambiguity with respect to revision names use "--" to separate the paths
from any preceding options.
+gitk-specific options
+~~~~~~~~~~~~~~~~~~~~~
+
+--argscmd=<command>::
+
+ 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
+ '<revision range>' if the set of commits to show may vary
+ between refreshes.
+
+--select-commit=<ref>::
+
+ Select the specified commit after loading the graph.
+ Default behavior is equivalent to specifying '--select-commit=HEAD'.
+
Examples
--------
gitk v2.6.12.. include/scsi drivers/scsi::
@@ -98,8 +166,21 @@ gitk --max-count=100 --all \-- Makefile::
Files
-----
-Gitk creates the .gitk file in your $HOME directory to store preferences
-such as display options, font, and colors.
+User configuration and preferences are stored at:
+
+* '$XDG_CONFIG_HOME/git/gitk' if it exists, otherwise
+* '$HOME/.gitk' if it exists
+
+If neither of the above exist then '$XDG_CONFIG_HOME/git/gitk' is created and
+used by default. If '$XDG_CONFIG_HOME' is not set it defaults to
+'$HOME/.config' in all cases.
+
+History
+-------
+Gitk was the first graphical repository browser. It's written in
+tcl/tk and started off in a separate repository but was later merged
+into the main Git repository.
+
SEE ALSO
--------
@@ -108,10 +189,10 @@ SEE ALSO
'gitview(1)'::
A repository browser written in Python using Gtk. It's based on
- 'bzrk(1)' and distributed in the contrib area of the git repository.
+ 'bzrk(1)' and distributed in the contrib area of the Git repository.
'tig(1)'::
- A minimal repository browser and git tool output highlighter written
+ A minimal repository browser and Git tool output highlighter written
in C using Ncurses.
GIT