gitcarousel

A standalone tmux git dashboard that rotates through multiple repositories.

gitcarousel opens a narrow tmux pane and shows a compact, colored git dashboard for one repository at a time, cycling to the next on a timer and redrawing so the data stays current. For the selected repo it renders:

1. A header: a short repo label, the current branch (or a short commit id when detached), a clean or dirty marker, and the position in the rotation (for example 2/3).
2. A changes section built from git status --short --branch: staged, unstaged, and untracked files, compact and colored.
3. A divider, then a commit graph built from git log --graph --oneline --decorate (the last dozen or so commits).

It is a generic tool that knows nothing about any particular workflow. You give it a list of repos and it rotates through them. The repo list lives in a plain text file that the engine re reads on every tick, so any external tool can retarget the dashboard just by rewriting that file. No signals, no restart.

Requirements

Bash, tmux, and git. Nothing else to install. It runs on Linux, macOS, and WSL.

Install

gitcarousel is a single executable bash script. Put it anywhere on your PATH:

git clone https://github.com/karotkriss/gitcarousel.git
ln -s "$PWD/gitcarousel/gitcarousel" ~/.local/bin/gitcarousel

Or copy the gitcarousel file wherever you keep your scripts and mark it executable with chmod +x.

Usage

Run these from inside a tmux session.

gitcarousel open [flags]   # create the dashboard pane and start rotating
gitcarousel close          # remove the dashboard pane(s) it created
gitcarousel --help         # show usage

open splits the current window to create a narrow right hand column and starts rendering. close removes every dashboard pane in the current tmux session.

Flags for open

Flag	Default	Meaning
--target-file <path>	~/.gitcarousel/targets	File holding the repo list, re read every tick. Overridable with $GITCAROUSEL_TARGET_FILE.
--repos <p1,p2,...>	(none)	Inline repo list instead of a target file. Each item may carry a |label suffix.
--interval <seconds>	4	Rotation period, a positive integer.
--width <cols>	50	Pane width, a positive integer.
--count <n>	12	Commit graph length, a positive integer.
--no-rotate	(rotates)	Pin to the first repo, still redrawing for fresh data.

A value that is not a positive integer for --interval, --width, or --count is rejected. The tool prints a warning to stderr and falls back to that flag's default. A value-taking flag given with no value, or an unknown flag, exits with an error instead.

Driving it through a target file

This is the intended way to use it. A separate tool writes the target file; gitcarousel just reads it.

# Start the dashboard pointed at a file.
gitcarousel open --target-file ~/.gitcarousel/targets --interval 3 --width 48

# Any tool can now retarget the dashboard by rewriting that file.
# The pane picks up the change on the next tick, with no restart.
cat > ~/.gitcarousel/targets <<'EOF'
/home/me/work/api        | API
/home/me/work/web        | Web
/home/me/work/infra
EOF

Target file format

One repo path per line, with an optional label after a TAB or a |:

# Lines starting with # are comments. Blank lines are ignored.
/home/me/work/api                  (label defaults to the basename: "api")
/home/me/work/web        | Web      (explicit label after a pipe)
/home/me/work/infra<TAB>Infra       (explicit label after a tab)

When no label is given the basename of the path is used. An empty or missing file shows a quiet idle placeholder rather than an error, so it is safe to point the dashboard at a file before anything has written to it.

Inline list (no file)

For a quick, static dashboard you can pass the repos directly:

gitcarousel open --repos "/home/me/work/api|API,/home/me/work/web|Web" --interval 5

With an inline list the rotation still redraws each tick so git data stays fresh, but the set of repos is fixed for the life of the pane.

How any tool can feed it

The decoupling is the whole point: the engine never needs to know who is feeding it. A consumer writes the target file (one repo path per line, optional label after a tab or pipe), and the dashboard reflects it on the next tick. That consumer can be a shell script, an editor plugin, a CI watcher, or anything else that can write a file.

Development

The script is structured so its pure logic is testable without tmux. Parsing the target file, computing the rotation index, and formatting a repo's header, changes, and graph are all plain functions you can source and call directly.

tests/run.sh        # run the unit tests
shellcheck gitcarousel tests/run.sh

See CONTRIBUTING.md for the full setup, test, and pull request flow, and AGENTS.md for project internals.

License

MIT. See LICENSE.