Package: git-workflow
ContentsOverviewStart New Branch with Commit TemplateFinish a BranchCreate a Commit Template for an Existing BranchRemove a Branch’s Commit TemplateCleanup All Commit Templates in a RepoSetupPrerequisitesInstallationConfigure Git to Ignore Commit Template FilesConfigure Your Initials(Optional) Enable Tab Completion for Workflow CommandsWorkflow Commandsstartfinishset-templateunset-templatecleanupGit ConfigurationsUser DetailsBranchesCommit TemplatesTicket NumbersConfirmation PromptsFuture UpdatesPlannedBackburnerOverviewThis package contains command line tools to streamline common tasks in our git workflow.Start New Branch with Commit TemplateTo start a new branch, run:workflow startThis will prompt you for some information and create a new branch with the following name format:[<client>-]<brief-description>-<yyyymmdd>-<initials>If you provide a ticket number, this will create a git commit message template for the branch. By default, the commit template will be in the following format:[<ticket#>]DemosStarting 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.Finish a BranchWhen you’re finished with a project branch that has been merged, run:workflow finishThis will clean up configs, remove the branch’s commit template, and delete the branch.DemoCreate a Commit Template for an Existing BranchIf you already have a branch created and would like to create a commit template, run:workflow set-templateDemoRemove a Branch’s Commit TemplateTo remove a branch’s commit template without deleting the branch, run:workflow unset-templateDemoCleanup All Commit Templates in a RepoIf you have a bunch of lingering commit templates and would like to tidy up, run:workflow cleanupBy default, this will clean up configs and template files for every branch except the one you have checked out. It will also look for orphaned commit templates with no associated branch and remove them.DemoSetupPrerequisitesPython 3.6+This package was developed using features that requirePython 3.6 or greater(developed using Python 3.9.2).You can usethis guide to install Python 3 on macOS.Git 2.23+This package uses features that requireGit 2.23 or greater.To install an updated version ofgiton macOS usingHomebrew:brew install gitNote:Make sure/usr/local/binis added to yourPATH. You can do this by adding the following to your.bashrc:export PATH="/usr/local/bin:$PATH"InstallationOnce you have the above prerequisites installed, you can install it usingpip(orpip3depending on how you installed Python 3):pip install git-workflowConfigure Git to Ignore Commit Template FilesThese commands generate files for commit templates, which you likely do not want to track in your repos.Option 1: Configure Global .gitignore (RECOMMENDED)Create a global gitignore file, e.g.~/.gitignore_globalSet the global git config forcore.excludesfileto the path of your global gitignore, e.g.:git config --global core.excludesfile ~/.gitignore_globalAdd the following to your global gitignore:# Commit message templates
.gitmessage_local*For more information oncore.excludesfile:GitHub - Ignoring filesGit Configuration - core.excludesfileOption 2: Ignore for a Single RepoTo ignore generated template files in a single git repo, add the following to the.gitignorefile:# Commit message templates
.gitmessage_local*Configure Your InitialsBy default,workflow startwill prompt you for your initials every time you start a new branch. You can set the git configworkflow.initialsto skip this prompt, e.g. to set your initials to “cd”:git config --global workflow.initials cdFor more information, see theGit Configurationssection below.(Optional) Enable Tab Completion for Workflow CommandsThis package utilizesargcompleteto support tab completion in Bash. Some additional setup is required to enable tab completion.Prereq: Enable Tab Completion in BashIf you haven’t already, you will need to enable tab completion in Bash. You can followthis guide to enable Bash Completion on macOS.Activate Tab CompletionAfter setting up tab completion for Bash, you need to activate tab completion forargcomplete. This can be done a couple of ways depending on your Bash version.Option 1: Activate Global Completion for argcomplete (Bash 4.2+)If you have Bash 4.2 or greater, you can simply run the following command:activate-global-python-argcompleteThen restart Bash for these changes to take effect.Note:The default version of Bash on macOS is 3.2.57. You can followthis guide to update to a newer version.Option 2: Activate Completion for Just This PackageIf you’re on an older version of Bash or do not want to enable global completion for some reason, add the following to your.bash_rc:eval "$(register-python-argcomplete workflow)"Then restart Bash for these changes to take effect.Workflow CommandsUsage:workflow <command>startCreate a new branch with the following name format:[<client>-]<brief-description>-<yyyymmdd>-<initials>Where:<client>- (Optional) Client’s name<brief-description>- Description of the work<yyyymmdd>- Today’s date<initials>- Engineer’s initialsScript will prompt for details and format appropriately (i.e. no
spaces/underscores, all lowercase).Usageusage: 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 branchConfigsCommand uses the following configs:workflow.initialsworkflow.baseBranchworkflow.badBranchNamePatternsfinishFinish a project branch.By default, this command will prompt for confirmation unless--forceis
specified. Once confirmed, this command will:Unset the commit template of the project branchCheckout the base branch and pull latest updatesAttempt to delete the project branch usinggit branch-d, which may
fail if the project branch has not been fully mergedUsageusage: 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 deletingConfigsCommand uses the following configs:workflow.baseBranchworkflow.finishBranchConfirmationPromptset-templateCreate and configure commit template for the current branch.By default, the commit template includes the specified ticket number before
the commit message. E.g. for ticket numberAB-12345:[AB-12345] <commit message text starts here>The commit template file will be created in the root of the git repository.
By default, the filename will be in this format:.gitmessage_local_<ticket>_<branch>The format of the filename, commit template body, accepted ticket numbers,
and more can be customized with git configs (see the Configs section below
for details).Usageusage: 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 templateConfigsCommand uses the following configs:workflow.commitTemplateFilenameFormatworkflow.commitTemplateFormatworkflow.ticketInputFormatRegexworkflow.ticketFormatCapitalizeworkflow.ticketInputFormatRegexworkflow.initialsunset-templateRemove commmit template for a branch.By default, this command will prompt for confirmation before removing the
commit template unless--forceis specified.Usageusage: 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 unsettingConfigsCommand uses the following configs:workflow.unsetTemplateConfirmationPromptcleanupTidy up workflow-related files and configs.This command will first list all branches and files that will be affected.
By default, it will then prompt for confirmation unless--forceis
specified. Once confirmed, this command will:Unset the commit templates of all configured branchesRemove any orphan commit template files that have no associated branchBy default, the current branch is omitted from cleanup unless--include-current-branchis specified.Usageusage: 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 templatesConfigsCommand uses the following configs:workflow.cleanupConfirmationPromptGit ConfigurationsWorkflow commands will use the following git configs if set:User Detailsworkflow.initialsThe user’s initials.If set,workflow startwill skip the prompt for your initials and use this value.E.g.:To set your initials to “cd”:git config --global workflow.initials cdBranchesworkflow.baseBranchDefault:masterBranch to use as a base when creating a new branch usingworkflow start.E.g.:To base branches off ofdevelop:git config workflow.baseBranch developworkflow.badBranchNamePatternsSet to aspace-separatedstring of phrases or patterns that
should not appear in a standard branch name. If set,workflow startwill check for these before attempting to create a new
branch.E.g.:if standard branch names shouldn’t include the words-webor-plugins:git config workflow.badBranchNamePatterns "-web -plugins"Commit Templatesworkflow.commitTemplateFormatDefault:'[{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.commitTemplateFilenameFormatDefault:'{ticket}_{branch}'Format of commit template filenames. Supports same placeholders asworkflow.commitTemplateFormat.NOTE:Resulting filenames will always begin with'.gitmessage_local_'.Ticket Numbersworkflow.ticketInputFormatRegexDefault:'[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.ticketFormatCapitalizeDefault:trueIftrue, letters in the ticket number will be capitalized after
validation.Confirmation Promptsworkflow.finishBranchConfirmationPromptDefault:trueIftrue,workflow finishwill prompt for confirmation
before unsetting unless-fis specified. Iffalse, will
not prompt for confirmation unless-cis specified.workflow.unsetTemplateConfirmationPromptDefault:trueIftrue,workflowunset-templatewill prompt for
confirmation before unsetting unless-fis specified. Iffalse, will not prompt for confirmation unless-cis
specified.workflow.cleanupConfirmationPromptDefault:trueIftrue,workflow cleanupwill prompt for confirmation
before cleaning unless-fis specified. Iffalse, will not
prompt for confirmation unless-cis specified.Future UpdatesPlannedConfig to disable “Client” prompt.Add-R/--branch-from-latest-releasetoworkflow startBackburnerLow-priority updates that may be added in a future release:Generate API docs using Sphinx.Support--verbosityargument on all commands.renamecommand: renames branch while keeping its commit template configured.