Install¶

gitbulk ships two ways. Both require the GitHub CLI (gh) and git, authenticated for your account — gitbulk shells out to them for everything.

• As a single binary — recommended if you just want to use gitbulk.
• From source — if you want to develop or contribute.

As a single binary¶

Download the release asset with gh (this works even while the repo is private, since gh is authenticated) and let it install itself onto your PATH:

gh release download --repo dhh1128/gitbulk --pattern gitbulk --dir /tmp \
  && chmod +x /tmp/gitbulk \
  && /tmp/gitbulk install

gitbulk install copies the binary into ~/.local/bin (the XDG user-bin directory, and exactly where bin/gitbulk-cron looks), marks it executable, and prints a shell-specific PATH hint if that directory isn't already on your PATH. Pass --dir <path> to install elsewhere.

The binary is a self-contained zipapp; it needs only Python 3.10+ on the machine (PyYAML is vendored in). It is not truly standalone — it runs under the system python3.

Updating¶

gitbulk update            # download + verify (sha256) + atomically replace
gitbulk update --check    # just report whether a newer release exists

update never replaces the binary mid-command and never fires from cron: a "newer version available" notice only appears on an interactive terminal, and is suppressed by --no-update-check or GITBULK_NO_UPDATE_CHECK=1 (which bin/gitbulk-cron sets).

If you installed gitbulk with pip/pipx instead of the binary, gitbulk update declines to clobber it and points you at pip install -U gitbulk / pipx upgrade gitbulk.

From source¶

For development and contributing:

git clone https://github.com/dhh1128/gitbulk
cd gitbulk
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[test]"
pytest

The developer README has the full contributor workflow, and AGENTS.md is the authoritative behavioral contract for anyone — human or AI — changing the code.

Next steps¶

Once gitbulk is on your PATH, configure it and then run your first report.