Documentation

Commands

gitpulse [flags]                 show the status of all configured repositories
gitpulse init [flags] [DIR ...]  find repositories below DIR and add them to the config

`gitpulse` flags

Flag	Effect
`--compact`	only repositories that need action
`-v`, `--all`	details for every local branch (sync state, age) and stashes
`--jobs N`	repositories scanned in parallel (default: one per CPU; lower it on slow disks)
`--progress`	show scanning progress (terminal output only)
`--json`	structured output for scripts
`--html`	self-contained, high-contrast HTML report
`--no-color`	plain text
`--config PATH`	use this config file
`--version`	print the version

`gitpulse init` flags

Flag	Effect
`--depth N`	how many directory levels to search (default 4)
`--dry-run`	only list what would be added
`--config PATH`	config file to create or extend

init skips hidden folders, node_modules and vendor, and does not look inside a repository it has found. Projects already in the config — enabled or disabled — are never added twice, so you can run it once per folder.

Status column

Status	Meaning
`DIRTY (2.go, 1.css)`	uncommitted changes (modified, new or deleted files), grouped by file type
`↑N`	N local commits not pushed, summed over all local branches
`↓N`	N commits on the remote tracking branch not pulled yet
`N stash`	entries in `git stash list`
`N stale`	local branches without a commit for 30+ days (information only)
`(No Remote)`	the repository has no remote configured
`ERROR`	path missing, not readable or not a Git repository
`CLEAN`	nothing to do

↓N is based on the last git fetch — GitPulse itself never contacts the remote. Run git fetch (or a scheduled git fetch --all) to keep it current.

Configuration file

GitPulse looks for its config in this order:

--config PATH
the GITPULSE_CONFIG environment variable
config/repos.ini in the current directory
~/.gitpulsemlc/repos.ini — this is where gitpulse init writes by default

[projects]
# name = absolute path
webshop    = /home/me/code/webshop
api-server = /home/me/code/api-server

[general]
# show /home/me as ~ in the output
replace_path_prefix = /home/me
replace_with        = ~

[settings]
column_name_width = 25     # minimum width of the NAME column
show_summary      = true   # summary block at the end
compact_mode      = false  # same as always passing --compact

[disabled_projects]
# not scanned, but remembered
old-tool = /home/me/code/old-tool

A path ending in /.git is accepted and corrected automatically.

FAQ

Does GitPulse change anything in my repositories? No. It only reads. It never commits, fetches, pulls, pushes or rewrites files.

Why does a repository show ↓0 although the remote has new commits? GitPulse compares with what your last git fetch brought in. Fetch first, or schedule it.

Windows blocks the binary. Defender sometimes flags unsigned tools that read many files quickly. Add an exclusion for gitpulse.exe.

Does macOS warn about the binary? No. The macOS downloads on this page are signed with a Developer ID and notarized by Apple. install.sh fetches the same signed binaries.

How do I stop watching a repository without deleting the line? Move it from [projects] to [disabled_projects].

More: JSON schema · Go library · Changelog