README

The git-user-bend CLI is a utility tool for managing the Git user configuration (i.e. name and email) of a given Git repository. With it you can create a set of personas and easily bend them when doing company work, open source development, or pair programming sessions.

With the in Git 2.13 introduced conditional configuration includes you can set a .gitconfig for a group of repositories, which already might suit your needs.

Known relatives

This CLI is influenced by the Gas Ruby gem and might also contain elements of pair.

Installation

The git-user-bend CLI should be installed globally through Composer.

composer global require stolt/git-user-bend

Make sure that the path to your global vendor binaries directory is in your $PATH. You can determine the location of your global vendor binaries directory via composer global config bin-dir --absolute. This way the git-user-bend executable can be located.

Since the default name of the CLI is quite a mouthful, an alias which can be placed in ~/.aliases, ~/.zshrc or the like might come in handy. The alias shown next assumes that $COMPOSER_HOME is ~/.config/composer and not ~/.composer.

alias gub='~/.config/composer/vendor/bin/git-user-bend $@'

Tip

As of release v1.2.1 it's also possible to install and use git-user-bend via a PHAR file.

Usage

Run the git-user-bend whoami CLI within a Git repository (or an argumented one) and it will allow you to view the currently used persona respectively the Git user configuration details.

The personas and their usage frequencies are stored in a JSON based global storage file called .gub.personas in the $HOME directory of your system.

Via a .gub dotfile it's also possible to add the details of single persona directly into a project repository. This is mostly oriented for repository maintainers working on multiple machines and with multiple personas. To keep your email address private consider using your username@users.noreply.github.com email address, for details see Setting your email in Git.

Available commands

To create a new persona the add command is available. It allows you to define an alias linked to persona details, which are basically the username and email. Every added persona is stored in the global storage file.

git-user-bend add <alias> <name> <email>
git-user-bend add "oss" "Raphael Stolt" "raphaelstolt@users.noreply.github.com"
git-user-bend add "com" "Raphael Stolt" "raphael.stolt@company.com"

To create a persona from a local .gub dotfile, local Git repository user details, or from global Git user details the import command can be used. When a persona should be created from the Git user details its alias has to be provided.

git-user-bend import [<alias>] [<directory>] [--from-dotfile]

To create a local .gub dotfile from an existing persona the export command is available.

git-user-bend export <alias> [<directory>]

To remove a defined persona from the global storage the retire command can be used.

git-user-bend retire <alias>

To view all defined personas the personas command is at your service. Via the --edit|-e option the global storage file called .gub.personas will be editable via the defined $EDITOR.

git-user-bend personas [--edit|-e]

To bend the persona of a Git repository, the use command is there to change the Git user configuration to the aliased user details. When using the --from-dotfile option the persona defined in a .gub dotfile is used. When an aliased persona from the global storage should be used its alias has to be provided. When a pair should be used their aliases have to be provided as a comma-separated list.

git-user-bend use [<alias>|<alias1,aliasN>] [<directory>] [--from-dotfile]

To reset the Git repository user to the values before, the reset command is available.

git-user-bend reset [<directory>]

To start a pair programming session, which will be identifiable in the Git commits, the pair command merges the user details of several personas into one pair. The email of the first persona alias in the comma-separated list will be used for the Git user.email configuration. If the --branch|-b is provided, a new Git branch will be created to pair in.

git-user-bend pair "<alias1,aliasN>" [<directory>] [--branch|-b]

To end a pair programming session and restore the default user.name and user.email the unpair command is available.

git-user-bend unpair <directory>

To check the persona, pair or respectively the Git user configuration of a repository the whoami command is a pleasant shortcut.

git-user-bend whoami [<directory>]

Running tests

composer test

License

This library and its CLI are licensed under the MIT license. Please see LICENSE.md for more details.

Changelog

Please see CHANGELOG.md for more details.

Code of Conduct

Please see CONDUCT.md for more details.

Contributing

Please see CONTRIBUTING.md for more details.