git-workflow 0.3.0

Demos

Starting a project branch:

Commit message will include the specified ticket number:

Different branches can use different commit templates:

👆 You can also use command line arguments to skip the prompts. Each workflow command supports a variety of command line options.

Demo

Demo

Demo

Demo

Python 3.6+

This package was developed using features that require Python 3.6 or greater (developed using Python 3.9.2).

You can use this guide to install Python 3 on macOS.

Git 2.23+

This package uses features that require Git 2.23 or greater.

To install an updated version of git on macOS using Homebrew:

brew install git

Note: Make sure /usr/local/bin is added to your PATH. You can do this by adding the following to your .bashrc:

export PATH="/usr/local/bin:$PATH"

Option 1: Configure Global .gitignore (RECOMMENDED)

1. Create a global gitignore file, e.g. ~/.gitignore_global

2. Set the global git config for core.excludesfile to the path of your global gitignore, e.g.:

   git config --global core.excludesfile ~/.gitignore_global

3. Add the following to your global gitignore:

   # Commit message templates
   .gitmessage_local*

For more information on core.excludesfile:

• GitHub - Ignoring files

• Git Configuration - core.excludesfile

Option 2: Ignore for a Single Repo

To ignore generated template files in a single git repo, add the following to the .gitignore file:

# Commit message templates
.gitmessage_local*

Prereq: Enable Tab Completion in Bash

If you haven’t already, you will need to enable tab completion in Bash. You can follow this guide to enable Bash Completion on macOS.

Activate Tab Completion

After setting up tab completion for Bash, you need to activate tab completion for argcomplete. This can be done a couple of ways depending on your Bash version.

activate-global-python-argcomplete

eval "$(register-python-argcomplete workflow)"

Usage

usage: workflow start [-h] [-V] [-c <client> | -C] [-d <description>] [-i <initials>] [-s] [-t <ticket#> | -T] [-b <branch> | -B | -r <tag>] [-P]

Create a new branch.

General:
  -h, --help            Show this help message and exit
  -V, --version         Show version number and exit

Branch Name Arguments:
  -c <client>, --client <client>
                        Specify client name
  -C, --no-client       No client name (skips prompt)
  -d <description>, --description <description>
                        Specify branch description
  -i <initials>, --initials <initials>
                        Specify developer initials
  -s, --skip-bad-name-check
                        Skip check for bad branch names

Commit Template Arguments:
  -t <ticket#>, --ticket <ticket#>
                        Specify ticket number (will create commit template)
  -T, --no-ticket       Skip ticket number prompt, don't create commit template (overrides -t)

Branching Arguments:
  -b <branch>, --base-branch <branch>
                        Specify branch to use as base for new branch (default: master)
  -B, --branch-from-current
                        Use currently checked out branch as base (overrides -b)
  -r <tag>, --base-release <tag>
                        Branch from the specified git tag
  -P, --no-pull         Skip pulling changes to base branch

Configs

Command uses the following configs:

• workflow.initials

• workflow.baseBranch

• workflow.badBranchNamePatterns

Usage

usage: workflow finish [-h] [-V] [-f | -c] [<branch>]

Finish a project branch.

General:
  -h, --help          Show this help message and exit
  -V, --version       Show version number and exit

Positional Arguments:
  <branch>            Branch to finish (default: current)

Confirmation Prompt Arguments:
  Override workflow.finishBranchConfirmationPrompt config.

  -f, --force         Skip confirmation prompt (if configured)
  -c, --confirmation  Prompt for confirmation before deleting

Configs

Command uses the following configs:

• workflow.baseBranch

• workflow.finishBranchConfirmationPrompt

Usage

usage: workflow set-template [-h] [-V] [<ticket>]

Configure git commit template for a branch.

General:
  -h, --help     Show this help message and exit
  -V, --version  Show version number and exit

Positional Arguments:
  <ticket>       Ticket number to use in commit template

Configs

Command uses the following configs:

• workflow.commitTemplateFilenameFormat

• workflow.commitTemplateFormat

• workflow.ticketInputFormatRegex

• workflow.ticketFormatCapitalize

• workflow.ticketInputFormatRegex

• workflow.initials

Usage

usage: workflow unset-template [-h] [-V] [-f | -c] [<branch>]

Remove commit template for a branch.

General:
  -h, --help          Show this help message and exit
  -V, --version       Show version number and exit

Positional Arguments:
  <branch>            Branch to unset template for (default: current)

Confirmation Prompt Arguments:
  Override workflow.unsetTemplateConfirmationPrompt config.

  -f, --force         Skip confirmation prompt (if configured)
  -c, --confirmation  Prompt for confirmation before unsetting

Configs

Command uses the following configs:

• workflow.unsetTemplateConfirmationPrompt

Usage

usage: workflow cleanup [-h] [-V] [-B] [-o] [-f | -c]

Tidy up workflow-related files and configs.

General:
  -h, --help            Show this help message and exit
  -V, --version         Show version number and exit

Cleanup Options:
  -B, --include-current-branch
                        Unset template for current branch too
  -o, --orphans-only    Only clean up templates without a branch

Confirmation Prompt Arguments:
  Override workflow.cleanupConfirmationPrompt config.

  -f, --force           Skip confirmation prompt (if configured)
  -c, --confirmation    Prompt for confirmation before cleaning up templates

Configs

Command uses the following configs:

• workflow.cleanupConfirmationPrompt

workflow.baseBranch

Default: master

Branch to use as a base when creating a new branch using workflow start.

E.g.: To base branches off of develop:

git config workflow.baseBranch develop

workflow.badBranchNamePatterns

Set to a space-separated string of phrases or patterns that should not appear in a standard branch name. If set, workflow start will check for these before attempting to create a new branch.

E.g.: if standard branch names shouldn’t include the words -web or -plugins:

git config workflow.badBranchNamePatterns "-web -plugins"

workflow.commitTemplateFormat

Default: '[{ticket}] '

Format of commit template body. Supports the following placeholders:

• {ticket}: Replaced with ticket number

• {branch}: Replaced with branch name

• {initials}: Replaced with user initials (if configured)

workflow.commitTemplateFilenameFormat

Default: '{ticket}_{branch}'

Format of commit template filenames. Supports same placeholders as workflow.commitTemplateFormat.

NOTE: Resulting filenames will always begin with '.gitmessage_local_'.

workflow.ticketInputFormatRegex

Default: '[a-zA-Z]+-[0-9]+'

Regex representing the format of a valid ticket number. Default format is 1 or more letters, then a hyphen, then 1 or more numbers. To allow any format, set to '.*'.

workflow.ticketFormatCapitalize

Default: true

If true, letters in the ticket number will be capitalized after validation.

workflow.finishBranchConfirmationPrompt

Default: true

If true, workflow finish will prompt for confirmation before unsetting unless -f is specified. If false, will not prompt for confirmation unless -c is specified.

workflow.unsetTemplateConfirmationPrompt

Default: true

If true, workflow unset-template will prompt for confirmation before unsetting unless -f is specified. If false, will not prompt for confirmation unless -c is specified.

workflow.cleanupConfirmationPrompt

Default: true

If true, workflow cleanup will prompt for confirmation before cleaning unless -f is specified. If false, will not prompt for confirmation unless -c is specified.