README.rst.j2

==================
Git Workflow Tools
==================

|github|
|pypi|
|license|
|pythonversions|

.. |github| image:: https://img.shields.io/badge/GitHub--green.svg?style=social&logo=github
    :alt: GitHub
    :target: https://github.com/connordelacruz/git-workflow

.. |pypi| image:: https://img.shields.io/pypi/v/git-workflow.svg
    :alt: PyPI
    :target: https://pypi.org/project/git-workflow/

.. |license| image:: https://img.shields.io/pypi/l/git-workflow.svg
    :alt: License

.. |pythonversions| image:: https://img.shields.io/pypi/pyversions/git-workflow.svg
    :alt: Python Versions
    :target: https://pypi.org/project/git-workflow/


.. contents::
    :depth: 2

Overview
========

This package contains command line tools to streamline common tasks in our git workflow.

{# Shorthand to include demo gifs #}
{% macro demo_gif(path) -%}
.. image:: https://raw.githubusercontent.com/connordelacruz/git-workflow/assets/{{path}}
{%- endmacro %}
Start New Branch with Commit Template
-------------------------------------

To start a new branch, run:

::

    {{workflow.command}} {{start.command}}

This 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#>] 

Demos
~~~~~

Starting a project branch:

{{ demo_gif('start/0-start-prompt.gif') }}

Commit message will include the specified ticket number:

{{ demo_gif('start/1-commit-message.gif') }}

Different branches can use different commit templates:

{{ demo_gif('start/2-args-and-per-branch.gif') }}

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


Finish a Branch
---------------

When you're finished with a project branch that has been merged, run:

::

    {{workflow.command}} {{finish.command}}

This will clean up configs, remove the branch's commit template, and delete the branch.

Demo
~~~~~

{{ demo_gif('finish/0-finish.gif') }}


Create a Commit Template for an Existing Branch
-----------------------------------------------

If you already have a branch created and would like to create a commit template, run:

::

    {{workflow.command}} {{set_template.command}}

Demo
~~~~~

{{ demo_gif('set-template/0-set-template.gif') }}


Remove a Branch's Commit Template
---------------------------------

To remove a branch's commit template without deleting the branch, run:

::

    {{workflow.command}} {{unset_template.command}}

Demo
~~~~~

{{ demo_gif('unset-template/0-unset-template.gif') }}


Cleanup All Commit Templates in a Repo
--------------------------------------

If you have a bunch of lingering commit templates and would like to tidy up, run:

::

    {{workflow.command}} {{cleanup.command}}

By 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.

Demo
~~~~~

{{ demo_gif('cleanup/0-cleanup.gif') }}


Setup
=====

Prerequisites
-------------

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 <https://docs.python-guide.org/starting/install3/osx/#doing-it-right>`_.

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 <https://brew.sh/>`_:

::

    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"


Installation
------------

Once you have the above prerequisites installed, you can install it using ``pip`` (or ``pip3`` depending on how you installed Python 3):

::

    pip install git-workflow


Configure Git to Ignore Commit Template Files
---------------------------------------------

These commands generate files for commit templates, which you likely do not want to track in your repos.

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 <https://docs.github.com/en/github/using-git/ignoring-files#configuring-ignored-files-for-all-repositories-on-your-computer>`_
- `Git Configuration - core.excludesfile <https://git-scm.com/book/en/v2/Customizing-Git-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*


Configure Your Initials
-----------------------

By default, ``workflow {{start.command}}`` will prompt you for your initials every time you start a new branch. You can set the git config ``workflow.initials`` to skip this prompt, e.g. to set your initials to "cd":

::

    git config --global workflow.initials cd

For more information, see the `Git Configurations`_ section below.


(Optional) Enable Tab Completion for Workflow Commands
------------------------------------------------------

This package utilizes `argcomplete <https://pypi.org/project/argcomplete/>`_ to support tab completion in Bash. Some additional setup is required to enable tab completion.

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 <https://sourabhbajaj.com/mac-setup/BashCompletion/>`_.

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.

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-argcomplete

Then restart Bash for these changes to take effect.

**Note:** The default version of Bash on macOS is 3.2.57. You can follow `this guide to update to a newer version <https://itnext.io/upgrading-bash-on-macos-7138bd1066ba>`_.

Option 2: Activate Completion for Just This Package
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

If 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 Commands
=================

{# Formats RST header for a command #}
{% macro command_header(command) -%}
``{{command}}``
{{ '-' * (command|length() + 4) }}
{%- endmacro %}
{# Usage sections #}
{% macro command_usage(help_text) -%}
Usage
~~~~~

::

    {{help_text}}
{%- endmacro %}
{# Details on configs #}
{% macro command_configs(command) -%}
{% if command.configs_used|length > 0 %}
Configs
~~~~~~~

Command uses the following configs:

{% for config_name in command.configs_used %}
- `workflow.{{config_name}}`_
{% endfor %}
{% endif %}
{%- endmacro %}

**Usage:** ``workflow <command>``

{# --- start --- #}
{{ command_header(start.command) }}

{{ start.doc }}

{{ command_usage(start.help) }}

{{ command_configs(start) }}

{# --- finish --- #}
{{ command_header(finish.command) }}

{{ finish.doc }}

{{ command_usage(finish.help) }}

{{ command_configs(finish) }}

{# --- set-template --- #}
{{ command_header(set_template.command) }}

{{ set_template.doc }}

{{ command_usage(set_template.help) }}

{{ command_configs(set_template) }}

{# --- unset-template --- #}
{{ command_header(unset_template.command) }}

{{ unset_template.doc }}

{{ command_usage(unset_template.help) }}

{{ command_configs(unset_template) }}

{# --- cleanup --- #}
{{ command_header(cleanup.command) }}

{{ cleanup.doc }}

{{ command_usage(cleanup.help) }}

{{ command_configs(cleanup) }}

Git Configurations
==================

Workflow commands will use the following git configs if set:

User Details
------------

``workflow.initials``
~~~~~~~~~~~~~~~~~~~~~

{{ configs.INITIALS }}

Branches
--------

``workflow.baseBranch``
~~~~~~~~~~~~~~~~~~~~~~~

{{ configs.BASE_BRANCH }}

``workflow.badBranchNamePatterns``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

{{ configs.BAD_BRANCH_NAME_PATTERNS }}

Commit Templates
----------------

``workflow.commitTemplateFormat``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

{{ configs.COMMIT_TEMPLATE_FORMAT }}

``workflow.commitTemplateFilenameFormat``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

{{ configs.COMMIT_TEMPLATE_FILENAME_FORMAT }}

Ticket Numbers
--------------

``workflow.ticketInputFormatRegex``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

{{ configs.TICKET_INPUT_FORMAT_REGEX }}

``workflow.ticketFormatCapitalize``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

{{ configs.TICKET_FORMAT_CAPITALIZE }}

Confirmation Prompts
--------------------

``workflow.finishBranchConfirmationPrompt``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

{{ configs.FINISH_BRANCH_CONFIRMATION_PROMPT }}

``workflow.unsetTemplateConfirmationPrompt``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

{{ configs.UNSET_TEMPLATE_CONFIRMATION_PROMPT }}

``workflow.cleanupConfirmationPrompt``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

{{ configs.CLEANUP_CONFIRMATION_PROMPT }}

Future Updates
==============

Planned
-------

- Config to disable "Client" prompt.
- Add ``-R``/``--branch-from-latest-release`` to ``workflow start``

Backburner
----------

Low-priority updates that may be added in a future release:

- Generate API docs using Sphinx.
- Support ``--verbosity`` argument on all commands.
- ``rename`` command: renames branch while keeping its commit template configured.