Use Cases

Four ways people use GitPulse, each ready to copy. All of them start from the same config — create it once with gitpulse init ~/code.

1. The morning check

You open the terminal and want to know what you left open yesterday.

gitpulse --compact

Only repositories with uncommitted changes, unpushed or unpulled commits, or stashes are listed. An empty list means you can start fresh.

Add -v to see every branch with its sync state and age — handy before a cleanup:

gitpulse --compact -v

2. A daily status mail

Let cron send you the overview every working day at 8:00. --compact --html writes one self-contained page with only the repositories that need attention — inline styles, so it looks right in Outlook and Gmail too.

# crontab -e
0 8 * * 1-5  /usr/local/bin/gitpulse --compact --html | mail -a "Content-Type: text/html" -s "Repo status" you@example.com

Use --config /path/to/repos.ini if cron runs as a different user.

3. Several servers over SSH

remote_gitpulse copies the right gitpulse binary and a config to a Linux or macOS server, runs the scan there and removes everything afterwards. Nothing stays installed on the server.

# server-repos.ini lists the paths as they are on the server
remote_gitpulse -host deploy@web01 -config server-repos.ini -arch linux-amd64
remote_gitpulse -host deploy@pi    -config pi-repos.ini     -arch linux-arm64

Typical finding: someone edited a config on the server directly and never committed it.

4. Scripts, dashboards and CI

--json returns the full state — every repository, every local branch, ahead/behind counts, stashes, last commit and last fetch.

# names of all repositories with uncommitted changes
gitpulse --json | jq -r '.results[] | select(.is_clean == false) | .name'

# fail a CI job if anything is unpushed
gitpulse --json | jq -e '.summary.ahead == 0'

The field reference is in the JSON schema. Go developers can use the scanner directly as a library — see the library guide.