Mostly for scripting reasons and alerting reasons, there are multiple times when I have wanted a simple status of a repository. When working from the console, there is git-status which shows things in a human parsable format, but for scripts we need something more robust.

We can ue git-status with the –porcelain=2 flag to provide a lot more information, in a more easily machine parsable format. Seeing how starship parsed git-status helped me on this path.

Using this information, I wrote my own git-pending command to parse this data, into a form I could script against more easily.

Basic usage

By running it in a directory, it gives a simple status while returning 1 for scripting purposes

git-pending
.M content/blog/2025/desktop-environment-wishlist.markdown
.M layouts/partials/post-taxonomies.html
? content/blog/2025/git-pending.markdown

If there are no local pending changes, then it will check the remote push status.

git pending
commits are not pushed
f8baed0 (HEAD -> feed-merge, origin/feed-merge) Stubs

By default, it will check with only the locally cached information, but you can also add the --fetch flag for it to update the local remotes to check against.

This is not significantly different from running git-status directly, but gives us a base for report views

Report

The main reason for writing this, was to provide a --report view, that I could check multiple repos more easily.

First, we want to register repos that we want to check.

git-pending --register # Will register the current repo
git-pending --register /path/to/repo # Will register a repo in a different location

After this we can now get a report view

git-pending --report
# HELP repo_dirty Number of files in modified/uncommited state
# TYPE repo_dirty gauge
repo_dirty{path="/path/to/myrepo1"} 3.0
# HELP repo_unpushed Number of commits behind origin
# TYPE repo_unpushed gauge
repo_unpushed{path="/path/to/myrepo1"} 1.0
repo_unpushed{path="/path/to/myrepo2"} 1.0
repo_unpushed{path="/path/to/myrepo3"} 2.0

I picked Prometheus’s textfile collector format, because I wanted to be able to write an alert on this if needed. The use case is one from my previous job, where we might deploy code as a git repository, but wanted to alert if there were any local changes from testing. This allows you to either read via node_exporter or send to pushgateway

git-pending --report > /path/to/node_exporter/collector
git-pending --report --address http://pushgateway:9093

I have only been hacking on this for a few days, but it has been nice to more easily check the status of multiple repositories at a glance. Seeing local commits pending or un-pushed branches usually means I left something in an incomplete state, and this helps me realize and come back to it more quickly.