git-cl

April 20, 2026 · View on GitHub

A pre-staging layer for organising changes in Git

Tutorial Paper Story DOI PyPI Tests GitHub stars

git-cl is a command-line tool that brings changelist support to Git, inspired by Subversion. It adds a pre-staging review layer that lets you organise modified files into named groups before staging or committing. Changelists can be stashed selectively and promoted to dedicated branches — enabling a late-binding branching workflow where the branch decision follows the code, not the other way around.

Features

Workflow

  • Pre-staging review: group changed files by intent before staging
  • Organise multiple concerns on a single branch
  • Stage and commit changes by intent
  • Stash changelists and resume work later
  • Late-binding branching: promote a changelist to a dedicated branch

Scope: operates at file level — patch-level editing is left to other Git tools.

Technical

  • Local-only metadata (.git/cl.json)
  • Simple CLI: git cl <command>
  • Interoperable with community VS Code extension

Demo

git-cl demo: creating changelists, viewing status, and branching

Quick Start

Install via pip

pip install git-changelists

The PyPI package is named git-changelists to avoid namespace conflicts; it installs the git-cl command.

Install via wget

mkdir -p ~/bin
wget https://raw.githubusercontent.com/BHFock/git-cl/main/git-cl -O ~/bin/git-cl
chmod +x ~/bin/git-cl

Make sure ~/bin is listed in your $PATH.

Verify installation

git cl --version
git cl help

Use changelists inside a Git repository

git cl add fixup file1.py
git cl status
git cl commit fixup -m "Fix file1"

Common Commands

# Add files to a changelist
git cl add docs-fix README.md docs/index.md

# See changes grouped by changelist
git cl status

# Stage or commit changelists
git cl stage docs-fix
git cl commit docs-fix -m "Update documentation layout and intro"

# Keep the changelist after committing
git cl commit docs-fix -m "Fix bug" --keep

# Remove a file from its changelist
git cl remove README.md

# Delete a changelist
git cl delete docs-fix

# Late-binding branching: create a branch from a changelist (auto-stash/unstash)
git cl br docs-fix

Documentation

📘 Tutorial: Guide with examples and FAQ

📘 Design Notes: Technical architecture

📘 Tests: Test suite and shell walkthroughs

📘 Why git-cl exists: History and motivation

📘 Paper: Design, workflow, and related work

Notes

  • Requires Python 3.9+ and Git
  • Local-only; designed for single-user workflows
  • Always inspect downloaded scripts before executing, see source
  • For security concerns, see SECURITY

License

BSD 3-Clause — see LICENSE | CONTRIBUTING