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.1

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.1
File Size Uploaded Provenance Actions
git_changelists-1.4.1.tar.gz 69.0 kB Without provenance Details for git_changelists-1.4.1.tar.gz

Built distribution (wheel)

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

Total release size: 106.3 kB

Release files / git_changelists-1.4.1.tar.gz

Download URL git_changelists-1.4.1.tar.gz
Size 69.0 kB
Tags Source
SHA-256 checksum
How to use checksums
720bef47ef7bcf05b097a8f887fd703099f84ce29c6dccde245978312dd35eb8
BLAKE2b-256 checksum
How to use checksums
751c4b6be7832fd7db5ef29ba0a22ae0a8eb162c4d79f8063cf54c4188c2e741
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.1-py3-none-any.whl

Download URL git_changelists-1.4.1-py3-none-any.whl
Size 37.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
c8d0948c0face6d327bb2e0921cf10eeee59ab41fe2678f2bc998fa94677bab5
BLAKE2b-256 checksum
How to use checksums
f2908c62dbf08f0b3c0b82f6c84be5054a3d3af01847d7520c369f667b24a54e
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.1

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