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`](https://github.com/kejadlen/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:
```sh
# 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 git@github.com: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
Co-authored-by: Naomi Nagata
Co-authored-by: Chrisjen Avasarala
# soloing
git author ca
# commit
git commit
# the commit message is pre-populated as:
Authored-by: Chrisjen Avasarala
```
## 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](https://github.com/bats-core/bats-core)
to verify the functionality of this script.
```bash
# run the tests
make
```
You are welcome to extend this utility. Please make sure adding new tests to cover your
scenario first.