gitcs

!gitcs

Installation

Ensure that you have Go installed on your machine before installing this tool. Execute the following command:

go install github.com/hrtsegv/gitcs@latest

Alternatively, if you don't have Go installed, download the latest release from this repository.

Usage

Run gitcs to scan the current directory and its subdirectories. By default, the graph starts 182 days before today. To scan another directory, use -path.

gitcs
gitcs -path "/home/user/dev"

The author email defaults to the Git configuration for the scan directory, including repository-local settings and global settings. Use -email to choose an author, or repeat it to combine your personal and work identities.

gitcs -email "[email protected]" -path "/home/user/dev"
gitcs -email "[email protected]" -email "[email protected]" -path "/home/user/dev"

If you want to include commits from all authors (regardless of email), pass a wildcard:

gitcs -email "*" -path "/home/user/dev"

Choose an inclusive date range with -since and -until. Both flags use YYYY-MM-DD; either can be supplied independently. The end date includes the whole day. Dates use your local timezone unless you choose -timezone.

gitcs -since "2026-01-01" -until "2026-01-31" -timezone "Asia/Beirut" -path "/home/user/dev"

• If Git has no configured email, supply -email or use -email "*".
• Reversed ranges are rejected. Future end dates are capped at today with a warning;

• The calendar fits your terminal width and splits long ranges into blocks. Use

• Run gitcs -help for all options. NO_COLOR=1 disables colored output.

Interactive explorer

Open a contribution calendar, commit list, and full commit details in your terminal:

gitcs explore -path ~/dev
gitcs explore -path ~/dev -email '*' -since 2026-01-01

The explorer accepts the same author, date, timezone, branch, and width flags as the report. It starts on the latest date with matching commits. Repositories load in the background; progress and warnings stay visible while you browse.

| Key | Action | | --- | --- | | Arrows or h/j/k/l | Move through the calendar; left/right move a week, up/down a day | | Home / End | First / last date, or first / last commit in the list | | PgUp / PgDown | Move four weeks, or page through a list or details | | Enter / Esc | Open commits, then details / go back | | Tab / Shift+Tab | Switch panes | | d | Toggle the selected day / all dates | | / | Search loaded commit messages and hashes across all dates | | r | Filter by repository | | w | Inspect warnings and skipped repositories | | R | Refresh the scan | | ? | Show help | | q / Ctrl+C | Quit / cancel and quit |

Search updates the calendar and list together. Enter accepts a search; Esc restores the previous search. On the calendar, Esc clears an accepted search. Repository filtering still counts a shared commit once, and details show every repository containing that commit.

Wide terminals show the list and details side by side. Smaller terminals show the active pane; resizing preserves your selection. The minimum size is 32 columns by 20 rows. Selection markers and intensity symbols also work with NO_COLOR=1. Quitting restores the terminal and cancels background work.

The explorer requires an interactive input and output terminal. Use gitcs [flags] for printable or piped output. Filters apply to the history loaded by the command-line options; change those options to include other authors or dates. Details include the full message, hash, author, timestamps, and repository paths.

How commits are counted

• Both filtering and daily totals use the author date, converted to the

• By default, history includes all local branches plus HEAD, including a

• A commit hash is counted once across branches, clones, and linked worktrees.

• Normal repositories, linked worktrees, and initialized submodules are discovered

• Unreadable repositories and subdirectories produce warnings. Valid repositories

Earlier versions counted only HEAD history and counted repeated clones separately, so totals may change with these corrected counting rules.

Contributions

Contributions are welcome! If you would like to contribute to this project, please follow these steps:

1- Fork the repository.

2- Create a new branch for your feature or bug fix.

3- Make the necessary changes and commit them.

4- Push your changes to your fork.

5- Submit a pull request describing your changes.

License

This project is licensed under the MIT License. See the LICENSE file for details.