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.

the missing gitk documentation

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.

1 colors and bold

2 repository operations

All these are from the commit list (the top pane):

3 the main menu

4 browsing the commit list (top pane)

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).

5 browsing the diff

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”.

5.1 running a diff between two arbitrary commits

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.

6 searching for commits

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.

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:”.

7 navigating the commit tree

There are several ways to navigate the tree quickly.

8 some other tricks