Skip to main content

git-cl

A pre-staging layer for organising changes in Git

Tutorial DOI PyPI Tests

Git Changelists

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, .git/cl-stashes.json)
  • Simple CLI: git cl <command>

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

Optional: prune automatically after every commit

Files committed with plain git commit stay in their changelist. With Git 2.54 or later, this hook removes them after every commit, in all your repositories:

git config --global hook.git-cl-prune.event post-commit
git config --global hook.git-cl-prune.command "git cl prune --quiet"

For older Git versions and how to turn the hook off, see the tutorial.

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

# Remove files without changes from all changelists
git cl prune

# Set a changelist aside and restore it later
git cl stash docs-fix
git cl unstash 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

Ecosystem

git-cl is CLI-only by design. Its stable metadata files and command interface allow editors and other tools to build on it.

Further independently maintained integrations are welcome, see integration guidance.

git-cl was mentioned in Git Rev News Edition #140.

Notes

  • Requires Python 3.9+ and Git
  • Coloured git cl status output needs the optional colorama package (pip install colorama); without it, output is plain text
  • 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.

Metadata

Release files for git-changelists 1.4.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for git-changelists 1.4.2
File Size Uploaded Provenance Actions
git_changelists-1.4.2.tar.gz 69.1 kB Without provenance Details for git_changelists-1.4.2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for git-changelists 1.4.2
File Interpreter ABI Platform Actions
git_changelists-1.4.2-py3-none-any.whl Python 3 none any Details for git_changelists-1.4.2-py3-none-any.whl

Total release size: 106.3 kB

Release files / git_changelists-1.4.2.tar.gz

Download URL git_changelists-1.4.2.tar.gz
Size 69.1 kB
Tags Source
SHA-256 checksum
How to use checksums
88cc7f73d4e5ed26e167c699385b03572b17b4151813d3e9a2342c71baddef5e
BLAKE2b-256 checksum
How to use checksums
44f2291f306195a8e1baf04320e053606f5d917d63e942f8d25697ed9ae05913
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.13.12

Release files / git_changelists-1.4.2-py3-none-any.whl

Download URL git_changelists-1.4.2-py3-none-any.whl
Size 37.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
84190c546a47357c2e244f004e7c0823fb3fdce130043fa4aa469b97d4ae2740
BLAKE2b-256 checksum
How to use checksums
149b08b5597cafeb785422ecee2f00a55c370abc7477dcc341515ffd07e940d3
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.13.12

Security for git-changelists 1.4.2

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page