Metadata-Version: 2.1
Name: git_workflow
Version: 0.1.1
Summary: Utilities for streamlining our git workflow.
Home-page: https://github.com/connordelacruz/git-workflow
Author: Connor de la Cruz
Author-email: connor.c.delacruz@gmail.com
License: MIT
Description: ==================
        Git Workflow Tools
        ==================
        
        .. contents::
        
        Overview
        ========
        
        This package contains command line tools to streamline common tasks in our git workflow.
        
        Start New Branch with Commit Template
        -------------------------------------
        
        .. todo DEMOS
        
        To start a new branch, run:
        
        ::
        
            workflow start
        
        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#>] 
        
        Finish a Branch
        ---------------
        
        .. todo DEMOS
        
        When you're finished with a project branch that has been merged, run:
        
        ::
        
            workflow finish
        
        This will clean up configs, remove the branch's commit template, and delete the branch.
        
        Create a Commit Template for an Existing Branch
        -----------------------------------------------
        
        .. todo DEMOS
        
        If you already have a branch created and would like to create a commit template, run:
        
        ::
        
            workflow set-template
        
        
        Remove a Branch's Commit Template
        ---------------------------------
        
        .. todo DEMOS
        
        To remove a branch's commit template without deleting the branch, run:
        
        ::
        
            workflow unset-template
        
        ..
            TODO
            Tidy Up Commit Templates
            ------------------------
            Doc when implemented, include demos
        
        
        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.
        
        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>`_
        
        
        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*
        
        
        Workflow Commands
        =================
        .. todo insert sections for remaining commands 
        
        **Usage:** ``workflow <command>``
        
        ``start``
        ---------
        
        Create 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 initials
        
        Script will prompt for details and format appropriately (i.e. no
        spaces/underscores, all lowercase).
        
        
        Usage
        ~~~~~
        
        ::
        
            usage: workflow start [-h] [-V] [-c <client> | -C] [-d <description>] [-i <initials>] [-s] [-t <ticket#> | -T] [-b <branch> | -B | -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)
              -P, --no-pull         Skip pulling changes to base branch.
            
        
        Configs
        ~~~~~~~
        
        Command uses the following configs:
        
        - `workflow.initials`_
        - `workflow.baseBranch`_
        - `workflow.badBranchNamePatterns`_
        
        
        ``finish``
        ----------
        
        Finish a project branch.
        
        By default, this command will prompt for confirmation unless ``--force`` is
        specified. Once confirmed, this command will:
        
        - Unset the commit template of the project branch
        - Checkout the base branch and pull latest updates
        - Attempt to delete the project branch using ``git branch -d``, which may
          fail if the project branch has not been fully merged
        
        
        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`_
        
        
        ``set-template``
        ----------------
        
        Create 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 number ``AB-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).
        
        
        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`_
        
        
        ``unset-template``
        ------------------
        
        Remove commmit template for a branch.
        
        By default, this command will prompt for confirmation before removing the
        commit template unless ``--force`` is specified.
        
        
        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`_
        
        
        Git Configurations
        ==================
        
        Workflow commands will use the following git configs if set:
        
        User Details
        ------------
        
        ``workflow.initials``
        ~~~~~~~~~~~~~~~~~~~~~
        
        The user's initials.
        
        If set, ``workflow start`` will skip the prompt for your initials and use this value.
        
        **E.g.:** To set your initials to "cd":
        
        ::
        
            git config --global workflow.initials cd
        
        
        Branches
        --------
        
        ``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.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.
        
        
        Commit Templates
        ----------------
        
        ``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.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.
        
        
        Ticket Numbers
        --------------
        
        ``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.
        
        
        Future Updates
        ==============
        
        Implement Remaining Core Commands
        ---------------------------------
        
        Implement the remaining commands from the original `bash scripts <https://github.com/connordelacruz/git-workflow-scripts>`_:
        
        - ``workflow cleanup``: Tidy up workflow-related files and configs.
        
        New Commands
        ------------
        
        - ``workflow rename``: Rename a branch while maintaining its current commit template.
        
        Enhancements
        ------------
        
        - Support ``--verbosity`` argument on all commands.
        - Support using a git tag for a base instead of a branch with ``workflow start``.
        - Support command tab completion with `argcomplete <https://kislyuk.github.io/argcomplete/>`_.
        
        Documentation
        -------------
        
        - Add demo GIFs of commands in action to README.
        - Generate API docs using Sphinx.
        
Platform: UNKNOWN
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Environment :: Console
Classifier: Environment :: Console :: Curses
Classifier: Topic :: Software Development :: Version Control :: Git
Classifier: Topic :: Software Development
Classifier: Development Status :: 3 - Alpha
Requires-Python: >=3.6
Provides-Extra: dev
