jolly-github-toolbelt 2.1.0
A collection of tools around Git and GitHub to make developers' lives easier.
License: MIT
Requires Python: >=3.6,<4.0

GitHub Tools
============

A collection of tools around Git and GitHub to make developers' lives easier.

- `gt-assign-pr`_
- `gt-pr-doc-link`_

gt-assign-pr
------------

A simple helper to assign a given PR to as set of users from the CLI.

Usage
~~~~~

This tool requires the use of a token (see `Using Tokens`_).
By simply providing a ``owner``, ``repository``, ``pr_number``
and as many users as desired,
you can assign the given PR to those users.
By default, currently assigned users are kept,
but they can be removed using the ``--clear-current`` flag.

gt-pr-doc-link
--------------

A simple helper to post a link to docs back to a PR when run in a Jenkins job.

Usage
~~~~~

This tool requires the use of a token (see `Using Tokens`_).
In addition,
this tool requires a ``BUILD_URL`` environment variable to be present
(present automatically in a Jenkins job),
and to have the docs already built
and available via a URL subpath from the job URL,
as would be generated by the `Jenkins HTML Publisher`_ plugin.

Using Tokens
------------

In order to provide for maximum flexibility,
these tools are designed to work with GitHub Personal Access Tokens,
which are needed for people using two-factor authentication
or have access protected by SAML single sign on (SSO).
GitHub provides instruction to `obtain a token`_.
The token can be provided to all commands
either via the ``--token TOKEN`` flag,
or by setting ``GH_TOKEN`` in your environment.

Custom GitHub URL
-----------------

By default, this project works with https://github.com.
In order to use an alternate URL, such as an enterprise install,
you can provide the URL via an environment variable: ``GT_GH_URL``.

pre-commit hooks
================

This repository also provides three hooks, documented below,
that can be installed by hand or via `pre-commit`_:

gt-commit-msg
-------------

Ensure that a commit message conforms to some best practices:

#. Subject lines should not be longer than 50 characters
#. Wrap the body at 72 characters
#. Separate the subject from body with a blank line.

These are taken from `A Note About Git Commit Messages`_.

gt-self-check
-------------

Can perform validations before making a commit.
If an executable file named ``self-check.sh`` exists
in the root of the repository and a Python, Ruby, or Gherkin file was changed,
the checker is executed
and the return status serves as a gate for the commit to occur.
The check can be bypassed via ``git commit -n``.

gt-prepare-commit-msg
---------------------

Prepare a commit message by including an appropriate prefix,
when possible, based on the branch name.
If the branch name contains a JIRA ID, that is included in the prefix.
If the branch name also contains either "FF" or "Spike",
that is appended to the prefix.
If a branch name, without including a JIRA ID,
contains "FF", "Spike", "Enhancement" or "Fix",
those phrases are set as the prefix.
All searches are case-insensitive.


.. _`Jenkins HTML Publisher`: https://plugins.jenkins.io/htmlpublisher
.. _`pre-commit`: https://pre-commit.com
.. _`A Note About Git Commit Messages`: https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
.. _`obtain a token`: https://help.github.com/en/articles/creating-a-personal-access-token-for-the-command-line