git-changelists 1.1.5

Git subcommand for named changelist support. Group working directory files by intent, then stage, commit, or branch by changelist.

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.

git‑cl operates on file level. It groups and stages whole files by intent, while leaving patch‑level editing to other Git tools.

Why git-cl?

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

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?: 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