Skip to main content

git-commitflow - Never make mistakes when committing using Git

License

The git-commitflow tool is an interactive command-line interface that combines git add, git diff, git commit, and git push into a single, mistake-proof workflow.

One of the main benefits of git-commitflow is that it gives you full visibility into your changes before they are committed.

Every developer has experienced the consequences of running Git commands from muscle memory at the end of a long coding session.

For example, you finally fix a bug, run git add . and git commit -a -m "Commit message." without inspecting the full diff, and push to the remote repository, only to realize moments later that your commit included leftover debug statements, temporary configuration edits, or untracked files. Even when the changes are clean, discovering after committing that the remote branch has diverged forces you to stop, manually stash, and rebase an unnecessary merge commit.

The workflow

Running git-commitflow guides you through the following steps in order:

  • Prompting to add files (git add).
  • Displaying git diff to verify accuracy and prevent mistakes before committing.
  • Prompting to enter a commit message. (The interactive prompt supports Tab autocompletion for commands such as /reset to cancel the diff and hard reset the repository, /edit to open the Git editor, and /skip to exit the program without making any changes.)
  • It commits the changes (git commit).
  • Optional (-p / --push flag): Synchronizes changes and pushes updates to the remote repository (git push). Before pushing, it fetches remote changes and attempts a fast-forward merge (--ff-only); if the merge fails, it prompts the user to confirm whether to proceed with a rebase (--rebase and --autostash). The references are only pushed when they have never been pushed before.

Interactive prompt features

When prompted for a commit message, the interactive prompt (powered by prompt_toolkit) supports:

  • Use the standard arrow keys (Up, Down, Left, Right) or Vim-style Alt+k (up), Alt+j (down), Alt+h (left), and Alt+l (right) to move the cursor and cycle through previous commit messages stored in the repository's history.
  • Jump by word backward using Alt+Shift+Left and forward using Alt+Shift+Right.
  • Press Tab to autocomplete built-in slash commands (/reset, /edit, /skip) without distracting pop-up menus appearing while you type.
  • Entering /edit opens the default Git editor, similar to the behavior when executing git commit -a.

Requirements

  • git >= 2.6
  • Python, pip, and prompt_toolkit (installed automatically with pip)

Installation

Here is how to install git-commitflow using pip:

pip install --user git-commitflow

The pip command above will install the git-commitflow executable in ~/.local/bin/git-commitflow.

Optional Python Dependencies

The git-commitflow CLI supports optional dependencies that extend its functionality. These extras can be installed based on environment requirements.

Colored Terminal Output

The following installs colorama to provide consistent cross-platform ANSI color support. This enhances the readability of standard output and error messages.

pip install --user "git-commitflow[colors]"

Custom Process Title

The following installs setproctitle to rename the running process from python to git-commitflow. This simplifies identification and management in system monitoring tools such as top, htop, and ps.

pip install --user "git-commitflow[proctitle]"

Install both

To install both extras at once, use a comma-separated list:

pip install --user "git-commitflow[colors,proctitle]"

Usage

Example usage

To use the tool within your Git repository, run:

git commitflow

This command will guide you through the following steps interactively:

  • Stage untracked files: Prompts you to git add any untracked files that haven't been staged.
  • Review changes: Displays a diff of your changes, allowing you to confirm whether you want to proceed with the commit.
  • Commit changes: Enter a commit message (using arrow keys or Alt+h/j/k/l to navigate history and text, Alt+Shift+Left/Alt+Shift+Right to jump words, or Tab to complete /reset, /edit, and /skip) to finalize the commit.

If you also wish to synchronize and push the changes, you can use the --push option:

git commitflow --push

The references are pushed only if they have not been pushed previously. The git-commitflow tool keeps track of the references that have been pushed, preventing the same reference from being pushed multiple times. This minimizes redundant pushes.

Command-line arguments

usage: git-commitflow [--option] [args]

Git commitflow command-line interface.

positional arguments:
  files       Files to commit. If none are specified, commits all files.

options:
  -h, --help  show this help message and exit
  -p, --push  Git push after a successful commit.

Customizations

Git configuration alias

To enhance your workflow, add the following aliases to your ~/.gitconfig file:

[alias]
ci = commitflow
cip = commitflow --push

With these aliases, you can use the commands git ci to commit changes and git cip to commit and push in a single step.

License

Copyright (c) 2020-2026 James Cherti

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see https://www.gnu.org/licenses/.

Metadata

Release files for git-commitflow 1.2.4

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-commitflow 1.2.4
File Size Uploaded Provenance Actions
git_commitflow-1.2.4.tar.gz 30.4 kB Without provenance Details for git_commitflow-1.2.4.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for git-commitflow 1.2.4
File Interpreter ABI Platform Actions
git_commitflow-1.2.4-py3-none-any.whl Python 3 none any Details for git_commitflow-1.2.4-py3-none-any.whl

Total release size: 58.7 kB

Release files / git_commitflow-1.2.4.tar.gz

Download URL git_commitflow-1.2.4.tar.gz
Size 30.4 kB
Tags Source
SHA-256 checksum
How to use checksums
9d437d494f6b277918cd81c19b11812512af81ffd5317c342fd981fce84cd277
BLAKE2b-256 checksum
How to use checksums
74a6681c3ac2fd7fa62bacaa6e5922771b3bcbb2db443a73af93d54704a3ca62
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.7

Release files / git_commitflow-1.2.4-py3-none-any.whl

Download URL git_commitflow-1.2.4-py3-none-any.whl
Size 28.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
9ef8b18d32e178dd5551e237cc1d03d6171c0213403b6e7cb36f156003c45707
BLAKE2b-256 checksum
How to use checksums
2c42649121dca1009af69e44917bc544a66590faa59f4b12f2f74ded27f24b48
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.7

Security for git-commitflow 1.2.4

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