VMware has ended active development of this project, this repository will no longer be updated.

git-author

A simple tool to add multiple authors to commit messages. Under the hood it is based on git commit --template and depends on git-together.

Setup

Installation

Because git-author is a shell wrapper around git-together, both must be installed on the system.

MacOS

brew install pivotal/tap/git-author

Linux

The git-together and git-author executables must be installed somewhere on your path so that git recognizes commands that begin with git together or git author.

Install and configure git-together

You can follow the instructions here: https://github.com/kejadlen/git-together We suggest using git config --global for the following instructions, since it's better to share the same git-together settings across all repos.

For your convenience, only the necessary settings are repeated here:

# include git-together configuration in ~/.gitconfig
git config --global --add include.path ~/.git-together

# Add the below line to your .bashrc to disable the
# `--signoff`s added by `git-together commit`.
export GIT_TOGETHER_NO_SIGNOFF=1

Note: Because git-author calls git-together directly to generate a commit template file, aliasing git to git-together is not strictly necessary, unless you want git author info to alternate among members of the pair or mob as you make commits. With Co-authored-by: in the commit message, Github will show all authors regardless of the git author info.

Install git-author

git clone [email protected]:pivotal/git-author
./git-author/setup.sh

Usage

Set the authors as below:

# pairing with James and Naomi
git author jh nn

# soloing
git author jh

# mobbing
git author jh nn ca

# show who are included in current ~/.git-author-template
git author

After doing so, git commit will now automatically include all of the authors in the commit message with the prefix Co-authored-by: or Authored-by if there is only one author. For example:

# mobbing
git author jh nn ca

# commit
git commit

# the commit message is pre-populated as:


Co-authored-by: James Holden <[email protected]>
Co-authored-by: Naomi Nagata <[email protected]>
Co-authored-by: Chrisjen Avasarala <[email protected]>


# soloing
git author ca

# commit
git commit

# the commit message is pre-populated as:


Authored-by: Chrisjen Avasarala <[email protected]>

Story Numbers

Often when making commits, we like to append the commit message with a story number, e.g. [#12345678]. To automate this process, you can set the $STORY_NUM environment variable to a value such as '#12345678 story title'. Run git author again for the story number to appear in the commit message. This will result in the below being appended to the commit message template:

[#12345678]
# story title

Co-authored-by: ...
Co-authored-by: ...

Additionally, if you set git config --global git-author.includeBlankStoryNum true, then if you didn't set $STORY_NUM, empty story number brackets ('[]') will be appended to prompt you to fill it in.

Global vs. Local git-together Settings

By default, git-together will be called with --global, hence a system-wide configuration of authors are set.

However, for special cases, people like to use non-global configurations just for given set of git repos. To support that usage, we introduced another environment variable GIT_AUTHOR_LOCAL.

If this variable it set git-together will be called without --global flag. Here is the example usage for non-global usage:

GIT_AUTHOR_LOCAL=1 git author jh

If people always wants to use it without --global, then can put this environment in their shell environment, e.g. .bashrc.

Why

git-together is a wonderful tool to change the author and commit fields in the git commit object, and rotate the authors automatically to evenly distribute the credit.

However, both the git author and commit fields may change or be lost in the future due to merging, rebasing, and cherry-picking.

Also, git-together cannot put multiple authors directly into same commit, e.g. it only supports one Signed-off-by: message generated by git commit --signoff.

git-author is created to extend the git-together capability, so that all the authorship information will be captured as part of the commit message, hence, it won't care about who actually tracked in the author and commit fields in the git log.

See this discussion on the open source GPDB project's mailing list: https://groups.google.com/a/greenplum.org/forum/#!msg/gpdb-dev/qHqa9UbFpSA/u0Y0g2rqAAAJ

Development

git-author is a bash script, we used bats to verify the functionality of this script.

# run the tests
make

You are welcome to extend this utility. Please make sure adding new tests to cover your scenario first.