vmware-archive / git-author

An easy way to setup multiple authors based on `git commit --template`. It depends on git-together
BSD 3-Clause "New" or "Revised" License
30 stars 11 forks source link

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.