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