Guide to understanding gitk?

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" ?

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)

Here is an introduction to the visualization of branch history in gitk with screenshots.

http://lostechies.com/joshuaflanagan/2010/09/03/use-gitk-to-understand-git/

> 1. The upper left pane shows the series of commits to this repository, with the most recent on top. > 2. There have been three commits, all by Tony Stark. > 3. The commit message for the most recent commit was “third commit” > 4. There is a single local branch, named “master’”, it points to the most recent commit > 5. There is a single remote reference branch: the “master” branch from the remote repository named “origin”, it also points to the most > recent commit > 6. The yellow dot next to the top commit indicates that is the snapshot currently in my working folder (referred to as HEAD) > 7. I’ve highlighted the second commit, so that I can see its details in the lower pane > 8. The commit SHA (unique identifier, similar to subversion revision number) of the second commit is
> 3d024dd9e4a83d8c6a9a143a68b75d4b872115a6 > 9. The lower right shows the list of files impacted by the second commit > 10. The lower left shows the commit details, including the full diff > 11. Clicking a file in the lower right pane scrolls the diff in the lower left pane to the corresponding section 12.

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.

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.