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.
A key benefit of git-commitflow is that it gives you full visibility into your changes before they are committed, keeping your Git history clean.
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 -m 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 and manually stash, and rebase an unnecessary merge commit.
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 prompt supports 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.) - Synchronizing changes before finalizing the commit: it first 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). - It commits the changes (
git commit).
Optional (-p flag) makes git-commitflow push updates to the remote repository (git push). The references are only pushed when they have never been pushed before.
When prompted for a commit message, the user can press the up arrow to quickly access previous messages via the readline prompt history. Entering /edit opens the default Git editor, similar to the behavior when executing git commit -a.
- git >= 2.6
- Python and pip
Here is how to install git-commitflow using pip:
pip install --user git-commitflowThe pip command above will install the git-commitflow executable in ~/.local/bin/git-commitflow.
The git-commitflow CLI supports optional dependencies that extend its functionality. These extras can be installed based on environment requirements.
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]"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]"To install both extras at once, use a comma-separated list:
pip install --user "git-commitflow[colors,proctitle]"To use the tool within your Git repository, run:
git commitflowThis 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: Once you validate your commit message, the tool synchronizes the branch and finalizes the commit.
If you also wish to push the changes, you can use the --push option:
git commitflow --pushThe 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.
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.
To enhance your workflow, add the following aliases to your ~/.gitconfig file:
[alias]
ci = commitflow
cip = commitflow --pushWith these aliases, you can use the commands git ci to commit changes and git cip to commit and push in a single step.
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/.