Pair harmoniously! Working in a pair doesn't mean you've both lost your
identity. git-duet
helps with blaming/praising by using stuff that's already
in git
without littering your repo history with fictitous user identities. It
does so by utilizing git
s commit committer attributes to store the identity
of the second pair.
Example:
$ cat <<-EOF > ~/.git-authors
authors:
jd: Jane Doe; jane
fb: Frances Bar
email:
domain: awesometown.local
EOF
$ git duet jd fb
GIT_AUTHOR_NAME='Jane Doe'
GIT_AUTHOR_EMAIL='jane@awesometown.local'
GIT_COMMITTER_NAME='Frances Bar'
GIT_COMMITTER_EMAIL='f.bar@awesometown.local'
$ touch foo
$ git duet-commit -a -m 'initial commit'
[master (root-commit) ce78563] initial commit
Author: Jane Doe <jane@awesometown.local>
1 file changed, 0 insertions(+), 0 deletions(-)
create mode 100644 foo
$ git show --format=full
commit ce7856371e3e3a6d05f1b66af96f086df071e783
Author: Jane Doe <jane@awesometown.local>
Commit: Frances Bar <f.bar@awesometown.local>
initial commit
Signed-off-by: Frances Bar <f.bar@awesometown.local>
diff --git a/foo b/foo
new file mode 100644
index 0000000..e69de29
Options:
- See releases page for binary downloads, place in your
$PATH
. - Install using Homebrew from the git-duet homebrew tap
- Build from source:
GOVENDOREXPERIMENT=1 go get github.com/git-duet/git-duet/...
Make an authors file with email domain, or if you're already using
git pair, just symlink your
~/.pairs
file over to ~/.git-authors
.
authors:
jd: Jane Doe; jane
fb: Frances Bar
email:
domain: awesometown.local
git duet
will use the git pair
YAML structure if it has to (the
difference is the top-level key being pairs
instead of authors
) e.g.:
pairs:
jd: Jane Doe; jane
fb: Frances Bar
email:
domain: awesometown.local
If you want your authors file to live somewhere else, just tell
git-duet
about it via the GIT_DUET_AUTHORS_FILE
environmental
variable, e.g.:
export GIT_DUET_AUTHORS_FILE=$HOME/.secret-squirrel/git-authors
# ...
git duet jd am
Set two authors (pairing):
git duet jd fb
Set one author (soloing):
git solo jd
Committing (needed to set --signoff
and export environment variables):
$ git duet-commit -v [any other git options]
Reverting (needed to set --signoff
and export environment variables):
git duet-revert -v [any other git options]
Merging (needed to set --signoff
and export environment variables):
git duet-merge -v [any other git options]
Rebasing (resets the author/committer to the current pair):
git rebase -i --exec 'git duet-commit --amend --reset-author'
Suggested aliases:
dci = duet-commit
drv = duet-revert
dmg = duet-merge
drb = rebase -i --exec 'git duet-commit --amend --reset-author'
Note: git-duet
only sets the configuration to use via git duet-commit
,
git duet-revert
, and git duet-merge
. Using git solo
(or git duet
) will
not effect the configured user.name
and user.email
. This allows
git commit
to be used normally outside of git-duet
.
Another option for git rebase
ing with git-duet
is to use
git-duet-rebase.sh courtesy of @pivotaljohn. This
script uses git filter-branch
to update the names of all of the
authors/committers to the currently set pair. It acts on your active branch
(using the passed ref as the start point).
If you're jumping between projects and don't want to think about managing them all individually, you can operate on the global git config:
git solo -g jd
git duet --global jd fb
If you do this habitually, you can set the GIT_DUET_GLOBAL
environment
variable to true
to always operate on the global git config:
export GIT_DUET_GLOBAL=true # consider adding this to your shell profile
git solo jd
You can also set it to false
to always operate on the local config, even if
the global flag is used.
Sometimes while pairing you want to share the authorship love between the
pairs. If you set GIT_DUET_ROTATE_AUTHOR=1
it will swap the author and
committer (if there is one) on every git duet-commit
(after the commit).
This operates on whichever config the authorship was drawn from (e.g. if the
author/committer was set in the repository git config, it will rotate these
even if GIT_DUET_GLOBAL
is specified).
By default, email addresses are constructed from the first initial and
last name ( or optional username after a ;
) plus email domain, e.g.
with the following authors file:
pairs:
jd: Jane Doe; jane
fb: Frances Bar
email:
domain: eternalstench.bog.local
After invoking:
git duet jd fb
Then the configured email addresses will show up like this:
git config user.email
# -> jane@eternalstench.bog.local
git config duet.env.git-author-email
# -> jane@eternalstench.bog.local
git config duet.env.git-committer-email
# -> f.bar@eternalstench.bog.local
A custom email template may be provided via the email_template
config
variable. The template should be a valid Go template string (see
http://golang.org/pkg/text/template/). The object passed in has .Name
,
.Username
, and .Initials
.
Additional functions available to template:
toLower(s)
: lowercases stringtoUpper(s)
: uppercases stringsplit(s, d)
: splits string on delimiterreplace(s, old, new, n)
: replacesold
ins
withnew
n
times (setn
to-1
to replace all)
If you need more complex logic, consider using the lookup function described
below and awk
.
Example:
pairs:
jd: Jane Doe
fb: Frances Bar
email_template: '{{with replace .Name " " "-" -1}}{{toLower .}}{{end}}@hamster.local'
After invoking:
git duet jd fb
Then the configured email addresses will show up like this:
git config user.email
# -> jane-doe@hamster.local
git config duet.env.git-author-email
# -> jane-doe@hamster.local
git config duet.env.git-committer-email
# -> frances-bar@hamster.local
If there are any exceptions to either the default format or a provided
email_template
config var, explicitly setting email addresses by
initials is supported.
pairs:
jd: Jane Doe; jane
fb: Frances Bar
email:
domain: awesometown.local
email_addresses:
jd: jane@awesome.local
Then Jane Doe's email will show up like this:
git solo jd
# ...
git config user.email
# -> jane@awesome.local
Alternatively, if you have some other preferred way to look up email addresses by initials, name or username, just use that instead:
export GIT_DUET_EMAIL_LOOKUP_COMMAND="$HOME/bin/custom-ldap-thingy"
# ... do work
git duet jd fb
# ... observe emails being set via the specified executable
The initials, name, and username will be passed as arguments to the lookup executable. Anything written to standard output will be used as the email address:
$HOME/bin/custom-ldap-thingy 'jd' 'Jane Doe' 'jane'
# -> doej@behemoth.company.local
If nothing is returned on standard output, email construction falls back to the decisions described above.
Since there are multiple ways to determine an author or committer's
email, it is important to note the order of precedence used by git-duet
:
- Email lookup executable configured via the
GIT_DUET_EMAIL_LOOKUP_COMMAND
environmental variable - Email lookup from
email_addresses
in your configuration file - Custom email address from Go template defined in
email_template
in your configuration file (see http://golang.org/pkg/text/template/) - The username after the
;
, followed by@
and the configured email domain - The lower-cased first letter of the author or committer's first name,
followed by
.
followed by the lower-cased last name of the author or committer, followed by@
and the configured email domain (e.g.f.bar@baz.local
)
If you'd like to regularly remind yourself to set the solo or duet
initials, use git duet-pre-commit
in your pre-commit hook:
(in $REPO_ROOT/.git/hooks/pre-commit)
#!/bin/bash
exec git duet-pre-commit
The duet-pre-commit
command will exit with a non-zero status if the
cached author and committer settings are missing or stale. The default
staleness cutoff is 20 minutes,
but may be configured via the GIT_DUET_SECONDS_AGO_STALE
environmental variable,
which should be an integer of seconds, e.g.:
export GIT_DUET_SECONDS_AGO_STALE=60
# ... do work for more than a minute
git commit -v
# ... pre-commit hook fires
If you want to use the default hook (as shown above), install it while in your repo like so:
git duet-install-hook
Don't worry if you forgot you already had a pre-commit
hook installed.
The git duet-install-hook
command will refuse to overwrite it.
In order to have the author and committer properly set when committing
via RubyMine, a git wrapper executable may be used to override any
executions of git commit
. Such an executable is available in the Git
Duet repository, and may be installed somewhere in your $PATH
like so:
\curl -Ls -o ~/scripts/rubymine-git-wrapper https://raw.github.com/git-duet/git-duet/master/scripts/rubymine-git-wrapper
chmod +x ~/bin/rubymine-git-wrapper
Given an install location of ~/bin/rubymine-git-wrapper
as shown
above, you would then update your RubyMine setting in
Preferences => Version Control => Git to set
Path to Git executable to the full path of
~/bin/rubymine-git-wrapper
(with the ~
expanded).
See issue #8 for more details.
Differences from ruby git-duet
- Running
git solo
orgit duet
with no initials outputs configuration in same format as when setting (env variables) - Does not set
user.name
anduser.email
(instead only sets namespaced variables) so thatgit commit
continues to work as normal - Template format is now Go's
text/template
See CONTRIBUTING.md.