Understanding the gitk Command

gitk is a graphical history viewer for Git repositories. It provides a visual representation of the commit history, making it easier to understand the changes made over time.

Table of Contents

1. Synopsis
2. Description
3. Basic Usage
4. Common gitk Options and Examples
5. Rev-List Options
6. Gitk-Specific Options
7. Advanced Usage Examples
8. Configuration
9. Conclusion

Synopsis

gitk [<options>] [<revision-range>] [--] [<path>…​]

Description

Displays changes in a repository or a selected set of commits. This includes visualizing the commit graph, showing information related to each commit, and the files in the trees of each revision.

Basic Usage

To start gitk, navigate to your Git repository in the terminal and run:

code2care@mac % gitk

This command opens the gitk interface, displaying the commit history in a graphical format.

Common gitk Options and Examples

gitk --all

gitk --since="1 week ago"

gitk --until="yesterday"

gitk --max-count=10

gitk --branches="feature*"

gitk --author="John Doe"

gitk --grep="bug fix"

gitk main..feature

gitk src/main.cpp

Rev-List Options

gitk supports most options applicable to the git rev-list command. Some key options include:

• --date-order

  : Sort commits by date when possible.

• --merge

  : Show the commits on the history between two branches that modify the conflicted files.

• --left-right

  : Mark which side of a symmetric difference a commit is reachable from.

• --full-history

  : When filtering history with <path>, does not prune some history.

• --simplify-merges

  : Remove some needless merges from the resulting history.

• --ancestry-path

  : Only display commits that exist directly on the ancestry chain between two commits.

Gitk-Specific Options

• --argscmd=<command>

  : Command to be run each time gitk has to determine the revision range to show.

• --select-commit=<ref>

  : Select the specified commit after loading the graph.

Advanced Usage Examples

1. View commits from the last month, excluding merges:

   code2care@mac % gitk --since="1 month ago" --no-merges

2. Show commits touching a specific file in a date range:

   code2care@mac % gitk --since="2023-01-01" --until="2023-06-30" path/to/file.txt

3. Display commits from all branches containing a specific keyword:

   code2care@mac % gitk --all --grep="refactor"

4. View commits by a specific author on a particular branch:

   code2care@mac % gitk --author="Jane Smith" feature-branch

5. Show the last 20 commits affecting a specific directory:

   code2care@mac % gitk -n 20 -- src/

6. Show changes since version v2.6.12 in specific directories:

   code2care@mac % gitk v2.6.12.. include/scsi drivers/scsi

7. Show changes during the last two weeks to a specific file:

   code2care@mac % gitk --since="2 weeks ago" -- gitk

8. Show at most 100 changes made to a file in all branches:

   code2care@mac % gitk --max-count=100 --all -- Makefile

Configuration

User configuration and preferences are stored at:

• $XDG_CONFIG_HOME/git/gitk

  if it exists, otherwise

• $HOME/.gitk

  if it exists

If neither of the above exist, then

$XDG_CONFIG_HOME/git/gitk

$XDG_CONFIG_HOME

$HOME/.config

Conclusion

gitk is a powerful tool for visualizing your Git repository's history. By combining various options and arguments, you can create highly specific views of your project's commit history, making it easier to track changes, debug issues, and understand the evolution of your codebase.