git-cl

A pre-staging layer for organising changes in Git

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

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