Guide to understanding gitk ?

Question

I am introducing git to a team of developers and i find gitk to be an amazing tool. It's also quite hard to understand, since understanding gitk requires an understanding of both git history and the viewer tool itself.

Does anyone have any good references to something like a "beginner's guide to git history with gitk" ?

Answer 1

I've never seen anything specifically for gitk. Here's a stab at it, from a "how does it work" point of view. Knowing the commands that are behind everything (or at least generally equivalent) helps learn to use command-line tools more easily, and also shows you where to look in documentation to understand gitk better!

File menu

This has changed somewhat over the last few major versions - I'm describing the current state.

• update and reload: This is probably the most confusing thing. Reload refreshes everything as if you started the program over with the same configuration. This means if a branch has been removed/rebased, if some commits are now dangling, you don't see them anymore. Update, on the other hand, refreshes all the information, but still shows all commits that were previously shown. This is an excellent thing to use if you're rebasing and want to make sure you didn't mess up - you can see both the original and rebased versions.

• references: pretty obvious. References include tags and branches (which may be remote). You can reread them, and list to click a particular one to show it in the history.

Views

As the man page says, gitk takes git-rev-list options to help specify what history should be shown. These can also be set interactively in the "view" menu. The man page is an excellent place to find more information about the ways you can control views (it's mostly in the commit limiting section). If you've looked at git-log before, you'll have seen a lot of this.

Help

There's a list of keybindings here! Sweet.

Context menu

This presents several common git porcelain commands, generally in a common/default mode of operation. Listing them will at least help you find the right documentation to understand what they do, if you don't already!

• git-diff (Diff this <-> selected
• git-format-patch (make patch)
• git-tag (create tag)
• git-diff-tree (write commit to file, rarely used)
• git-branch
• git-cherry-pick
• git-reset (reset branch to here) This prompts you for soft, mixed, or hard, with a brief reminder of what each does. Longer description on the man page, but of course you have to understand the concept of the index to really get it.

The "mark a commit" and related commands should be self-explanatory at this point.

In the context menu for a branch, we have git-checkout and the -d (delete) mode of git-branch.

Middle section

• SHA1 ID: the hash of the current commit. Very useful for copy/paste into a terminal to perform an action on a given commit you used gitk to find. You can also paste hashes into here.

• Forward/back buttons, row number... obvious!

• Find! The options here are again pretty self-explanatory, but for everyone's education, they're analogous to git-log parameters: "containing" is --grep, "touching paths" is the arguments, and adding/removing string is -S (pickaxe).

Message/diff pane

Here we have the commit message along with git-diff's output - this is something like using git-log -p, with a little extra:

• "Branches" is equivalent to git branch -a --contains=<commit>

• "Precedes"/"Follows" is equivalent to git describe [--contains] <commit> (git-describe)

Answer 2

The only thing I find useful about the gitk interface is the nice (colorful) branches overview..

If you want a gui for git, check TortoiseGit on windows or GitX on Mac or QGit on linux.

Answer 3

---

A merged version will have 2 parents. I'm trying to get the diff of a merged version to its parents by gitk. However, gitk only shows empty diffs. You can not set to diff to either of the parents.

Does gitk have this feature? If not, is there any other GUI tool in Linux?

Answer 4

What novices could really use in terms of "combination of gitk and history" is a specific explanation how to recognize what happened by looking at the gitk tree view.

As far as I got - the right way to look at the tree is (of course): 1. each node is a commit 2. ultimate parent is at the bottom 3. direct child to a commit is the one that happened first in the same branch (no matter who did it) 4. the node with 2 or more children indicates ... ? 5. merge commit node has 2 parents. 6. rebase is recognized ... ?

Screenshots would be appreciated as well.

The tree is actually representing the current state of the repository. What would be great is if we would be able to tell what happened by looking at the tree view.

Thanks

v.