git-secrets

===========
git-secrets
===========

-------------------------------------------------------------------------------------------
Prevents you from committing passwords and other sensitive information to a git repository.
-------------------------------------------------------------------------------------------

.. contents:: :depth: 2

Synopsis
--------

::

    git secrets --scan [-r|--recursive] [--cached] [--no-index] [--untracked] [<files>...]
    git secrets --scan-history
    git secrets --install [-f|--force] [<target-directory>]
    git secrets --list [--global]
    git secrets --add [-a|--allowed] [-l|--literal] [--global] <pattern>
    git secrets --add-provider [--global] <command> [arguments...]
    git secrets --register-aws [--global]
    git secrets --aws-provider [<credentials-file>]


Description
-----------

``git-secrets`` scans commits, commit messages, and ``--no-ff`` merges to
prevent adding secrets into your git repositories. If a commit,
commit message, or any commit in a ``--no-ff`` merge history matches one of
your configured prohibited regular expression patterns, then the commit is
rejected.


Installing git-secrets
----------------------

``git-secrets`` must be placed somewhere in your PATH so that it is picked up
by ``git`` when running ``git secrets``.

\*nix (Linux/macOS)
~~~~~~~~~~~~~~~~~~~

You can use the ``install`` target of the provided Makefile to install ``git secrets`` and the man page.
You can customize the install path using the PREFIX and MANPREFIX variables.

::

    make install

Windows
~~~~~~~

Run the provided ``install.ps1`` powershell script. This will copy the needed files
to an installation directory (``%USERPROFILE%/.git-secrets`` by default) and add
the directory to the current user ``PATH``.

::

    PS > ./install.ps1

Homebrew (for macOS users)
~~~~~~~~~~~~~~~~~~~~~~~~~~

::

    brew install git-secrets

.. warning::

    **You're not done yet! You MUST install the git hooks for every repo that
    you wish to use with** ``git secrets --install``.

Here's a quick example of how to ensure a git repository is scanned for secrets
on each commit::

    cd /path/to/my/repo
    git secrets --install
    git secrets --register-aws


Advanced configuration
----------------------

Add a configuration template if you want to add hooks to all repositories you
initialize or clone in the future.

::

    git secrets --register-aws --global


Add hooks to all your local repositories.

::

    git secrets --install ~/.git-templates/git-secrets
    git config --global init.templateDir ~/.git-templates/git-secrets


Add custom providers to scan for security credentials.

::

    git secrets --add-provider -- cat /path/to/secret/file/patterns


Before making public a repository
---------------------------------

With git-secrets is also possible to scan a repository including all revisions:

::

    git secrets --scan-history


Options
-------

Operation Modes
~~~~~~~~~~~~~~~

Each of these options must