master TOC | chapter TOC | license
gitk is a very powerful GUI tool. It's one of those rare beasts where the
pretty stuff is not just a crutch for the command-line-ignorant -- it actually
does really useful things that just cannot be done in a CLI.
Sadly, it is woefully undocumented. Scratch that, it's almost completely undocumented.
This is my attempt to do something about that. Strictly speaking, you can explore the UI and find all these features yourself, and indeed, if you find any that are not listed here, please email me.
All these are from the commit list (the top pane):
right clicking on a commit message
right clicking on a branch name
reload: if you're doing stuff on the command line in another screen, and
want those changes reflected in gitk, hit F5.
F5 updates the refs and shows you their new values while still showing
you the old ones. It is most useful after operations like rebase,
because you can compare the previous branch head with the new one.
(Ctrl-F5, on the other hand, is a total refresh, throwing away
everything that was previously shown.)
list/choose references: to quickly go to a particular reference, hit F2.
If there are too many, you can specify a glob pattern in the box at the
bottom to subset the list. Clicking on a reference takes the main window
to that reference. The list window will stay open so you can click on
other refs.
Many of these functions also have character key bindings. For example "n"
acts the same as a "down arrow". I'm not listing those; if you need them,
look in the source code for a series of bindkey statements and match them up
with the others. It's not hard, and you don't need to know Tcl. (I don't).
At any time, the bottom left pane shows a "diff", usually of the current commit shown in the top pane. The bottom right pane (by default) shows a list of files in this "diff".
Now you can browse that diff using the keyboard or mouse. Note that any movement that selects a different commit (like pressing an arrow key) will change the view to show that commit, so while examining this "diff", stick to these keys.
Here're some ways to search for commits. The commits that result will become highlighted in bold, so you can see them in the context of their surrounding changes. You can navigate between matches using the shift-up/down-arrow keys.
There is a widget to the left of the search box that controls what type of search you do. By default it is set to "containing:", which searches the commit message.
searching on commit message: just hit "/" and type in any text. This
will match all commits where the commit message contained the text you
typed.
searching by filename: navigate to some commit that affected the file. Right click the filename in the bottom right pane and choose "Highlight this only". If you want to add more files to the search in an "OR" type match, right click some other file (doesn't have to be the same commit), and choose "Highlight this too".
Notice that when you do this, the search type widget changes from "containing:" to "touching paths:".
searching by changed text: set the search type widget to "adding/removing string:", then type in a search text.
Now that you've understood that widget, take a look at the others on the right also; they're fairly self-explanatory. Note that the last widget (All fields, Headlines, Comments, Author, Committer) is only valid when the type of search widget shows "containing:".
There are several ways to navigate the tree quickly.
the diff pane always shows all the parents and children of the current commit. Click on any of the hashes to go there. Some of the text from the commit message of those hashes is also shown, to give you an idea of what that is.
the diff pane also shows all the branches to which this commit belongs. Click any of them to go to the head of that branch.
when the commit graph gets really complex, the line connecting two commits is broken. Click on any line segment (not on a dot or a dangling arrowhead) and the diff pane changes to show details for that line segment -- all parents and children are shown.
as above, but if you click on the arrowhead, you will be taken to the portion of the tree where the other end of the arrowhead would go to. Your "current" commit is still the same; this is just a way of "connecting" two pieces of the graph that are otherwise too far away.
"Follows:" and "Precedes:" show the nearest tag before and after the commit for each branch that the commit is a part of. For example, if you find the commit for a bugfix or a feature you want, this will tell you the minimum version you should upgrade to.
expand the diff view by using the spin control that says "Lines of context"; the default value is 3.
find the "origin" of any line visible in the "diff" pane by right clicking and choosing "Show origin of this line". This does not make sense for lines prefixed by a plus sign of course.
go to a specific commit by SHA: click on a commit, hit TAB twice to get the focus onto the SHA1 field, then type in the first few characters of the SHA you want.
If you click in the field with a mouse, it deselects the text within the field, and (for some reason), shift-select is disabled so you have to hold down the delete key to delete the entire field before you start typing in the new hash. Irritating, but it's only the mouse use, not keyboard use, so it's ok, I guess.