git notes main page | gitolite main page | license
IMPORTANT NOTE:
although this page has a "gitolite.com" URL, this is not about gitolite.
That's just an artifact of "sitaramc.github.com" being translated to
"gitolite.com" and so ALL my git related stuff gets carried over.
Gitolite documentation has another /gitolite in the URL, so
you can tell. My apologies for this confusion.
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.
[Update 2020-06-28: I just found Exploring gitk, which is pretty neat too. A lot of things in gitk are better explained in video than text so be sure to check that out also.]
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):
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.
(Shift-F5, on the other hand, is a total refresh, throwing away everything that was previously shown.)
list 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 jumps to that reference.
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.
Searching for commits is done by typing something in the search box just below the SHA ID. (The “Search” box on the next line is to search for text within a commit diff; that’s not the one we want, despite its name!)
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.
On Linux, you can grab the current SHA into a terminal command line by using the middle-click.
Just above the diff view are some additional widgets. One of them is a drop-down called Line diff. Be sure to try the Color words diff, especially when long lines have had just one or two changes.
Similarly, the “Ignore space change” checkbox is useful when blocks have indentation changes that cause the normal diff to look a lot noisier than it should be.
Finally, for a great birds-eye view of all the refs in a repo (but not the commits between them), try gitk --all --simplify-by-decoration.