git-commitflow - Never make mistakes when committing using Git
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 diffto verify accuracy and prevent mistakes before committing. - Prompting to enter a commit message. (The interactive prompt supports
Tabautocompletion for commands such as/resetto cancel the diff and hard reset the repository,/editto open the Git editor, and/skipto exit the program without making any changes.) - It commits the changes (
git commit). - Optional (
-p/--pushflag): 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 (--rebaseand--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-styleAlt+k(up),Alt+j(down),Alt+h(left), andAlt+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+Leftand forward usingAlt+Shift+Right. - Press
Tabto autocomplete built-in slash commands (/reset,/edit,/skip) without distracting pop-up menus appearing while you type. - Entering
/editopens the default Git editor, similar to the behavior when executinggit 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 addany 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/lto navigate history and text,Alt+Shift+Left/Alt+Shift+Rightto jump words, orTabto 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/.
Links
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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.