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

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

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.3.0
File Size Uploaded Provenance Actions
git_changelists-1.3.0.tar.gz 65.1 kB Without provenance Details for git_changelists-1.3.0.tar.gz

Built distribution (wheel)

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

Total release size: 101.1 kB

Release files / git_changelists-1.3.0.tar.gz

Download URL git_changelists-1.3.0.tar.gz
Size 65.1 kB
Tags Source
SHA-256 checksum
How to use checksums
2391fc22f8d74928734bc781050d3d3fbe5891570b857453efb76d26b022c7d5
BLAKE2b-256 checksum
How to use checksums
1e31d42f93fc393ef90ac472edbc6f8ab232be37e4538f48c7f2fed76e6c5fd3
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.3.0-py3-none-any.whl

Download URL git_changelists-1.3.0-py3-none-any.whl
Size 36.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
1acf0ef34119ed8ae4e9baff5324b4b315c18be1299b32bbc44b780972781249
BLAKE2b-256 checksum
How to use checksums
77659fedf6d9b38030626d451df5030b7175cfb63628b5e96e33bb523517521d
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.3.0

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