Skip to main content

A python program that helps you write commits following commit conventions

Project description

Commit Helper

Build Status Maintainability codebeat badge Codacy Badge

What does it do?

The commit-helper do exactly what it's name suggest: helps you create and maintain your commit policy by tailoring your commit message into a commit convention.

Why should I use this?

Keeping a commit policy may sound like an easy thing to do, but in reality we both know that it isn't.

Sometimes we, the developers, go full-loco while programming and make mistakes when commiting. That's fine, everyone makes mistakes. But, what if those mistakes could be avoided?


Initial commit

Normal commit

Commit without generating a configuration file

Co-authored commit

Fast commit

Debugging and commiting

All-in-one commit


Getting help for writing in a convention


In order to install one of our older versions, check our previous releases. To install the latest (pip) version, just follow the commands below:

$ pip3 install commit-helper

Updating your current version

If you already have one of our pip releases installed in your machine and want to update to the latest version, use the command:

$ pip3 install --upgrade commit-helper

Usage and configuration

This program has a cli that you can take advantage of. Running commit --help will show you the usage and options for your commit. All of them are optional for the sake of not losing your precious time.

 $ commit -h
usage: commit [-h] [-t TAG] [-m MESSAGE] [-ct CONTEXT] [-ca CO_AUTHOR] [-nf]
              [-c {angular,karma,tagged,symphony,message}] [-d]

A commit formatter tool to help you follow commit conventions.

optional arguments:
  -h, --help            show this help message and exit
  -t TAG, --tag TAG     Pass your commit tag directly
  -m MESSAGE, --message MESSAGE
                        Pass your commit message directly
  -ct CONTEXT, --context CONTEXT
                        Pass your commit context directly
  -ca CO_AUTHOR, --co-author CO_AUTHOR
                        Make your friend an co-author to the commit
  -nf, --no-file        Disables the creation of a commiter.yml or commit-helper.yml file
  -c {angular,karma,tagged,symphony,message}, --convention {angular,karma,tagged,symphony,message}
                        Selects a convention to be used for the commit.
                        Required if there's no commiter.yml or commit-helper.yml file.
  -d, --debug           Toggles debug option

So, if you want to write a co-authored commit, you should use:

$ commit --co-author "foo bar doritous <>"

Or if you are using this for the first time in your project:

$ commit --convention tagged

To work even more smoothly, have in your working directory a file named commiter.yml or commit-helper.yml. In this file you must pass the commit convention that you want to use, following the example:

convention: angular   # tag(context): commit message

# or

convention: karma   # tag(context): commit message

# or

convention: tagged # TAG: commit message

# or

convention: symphony  # [Tag] commit message

# and if you're feeling adventurous

convention: none      # Commit message

In case that you or your organization does already have a commit convention that is not listed above, you can configure it in the commiter.yml or commit-helper.yml file as following:

convention: custom
# considering a commit message like '{add} (stuff) ~> in file'
commit_pattern: '{tag} (context) ~> message'
# tag, message and context are reserved words that will be replaced in your commit message
context: true # this is a must have field! If your pattern doesn't have one, assign false to it

Supported conventions available:

  • angular
  • karma
  • tagged
  • symphony
  • atom
  • only message (no convention)
  • a custom one that you may create :)


If after you've installed commit-helper the commit or commit-helper commands are not usable at the command line, check if $HOME/.local/bin is on your PATH. If not, add it on your .bashrc file by running:

$ echo "export PATH=$HOME/.local/bin:$PATH" >> .bashrc

Project's maintainers

Name Username
André de Sousa Costa Filho @andre-filho

Our collaborators

Name Username
Arthur José Benedito de Oliveira Assis @arthur0496
Matheus Richard Torres Gomes de Melo @MatheusRich

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for commit-helper, version 3.4.18
Filename, size File type Python version Upload date Hashes
Filename, size commit_helper-3.4.18-py2.py3-none-any.whl (27.2 kB) File type Wheel Python version py2.py3 Upload date Hashes View
Filename, size commit-helper-3.4.18.tar.gz (25.5 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring DigiCert DigiCert EV certificate Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page