Skip to content

mit.md

Latest commit

 

History

History
587 lines (440 loc) · 16.5 KB

mit.md

File metadata and controls

587 lines (440 loc) · 16.5 KB
Raw

Authors

This is the git mit part of the tool.

Setup

To get started with this tool you'll need a git repository

git init .

You'll need to install the hooks into this repository

git mit-install

Configuring

For this example we'll be using the same configuration as you can generate from the example command.

You can see this configuration yourself by running

git-mit-config mit example
[ae]
name = "Anyone Else"
email = "anyone@example.com"

[bt]
name = "Billie Thompson"
email = "billie@example.com"
signingkey = "0A46826A"

[se]
name = "Someone Else"
email = "someone@example.com"

You can use YAML too

---
ae:
  name: Anyone Else
  email: anyone@example.com
bt:
  name: Billie Thompson
  email: billie@example.com
  signingkey: 0A46826A
se:
  name: Someone Else
  email: someone@example.com

To make keeping this file updated straightforward, there are some commands for adding and removing authors to the git repository.

You can quickly add a new author by running

git mit-config mit set jd "Jane Doe" "jd@example.com"

To override an existing user temporarily

git mit-config mit set se "Someone Else" "se@example.com"

You can use these straight away, you don't have to update your authors file.

git mit jd

However, if you want to make it more permanent, you can output the configuration with these added authors by running the generate command

git mit-config mit generate
[ae]
name = "Anyone Else"
email = "anyone@example.com"

[bt]
name = "Billie Thompson"
email = "billie@example.com"
signingkey = "0A46826A"

[jd]
name = "Jane Doe"
email = "jd@example.com"

[se]
name = "Someone Else"
email = "se@example.com"

To get a summary of the authors that are configured run

git mit-config mit available
╭─────────┬─────────────────┬────────────────────┬─────────────╮
│ Initial ┆ Name            ┆ Email              ┆ Signing Key │
╞═════════╪═════════════════╪════════════════════╪═════════════╡
│ ae      ┆ Anyone Else     ┆ anyone@example.com ┆ None        │
├╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌┤
│ bt      ┆ Billie Thompson ┆ billie@example.com ┆ 0A46826A    │
├╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌┤
│ jd      ┆ Jane Doe        ┆ jd@example.com     ┆ None        │
├╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌┤
│ se      ┆ Someone Else    ┆ se@example.com     ┆ None        │
╰─────────┴─────────────────┴────────────────────┴─────────────╯

Initials can contain dots, which is useful when your initials would otherwise collide with someone else's.

git mit-config mit set b.t "Boop Test" "b.t@example.com"
git mit b.t

Running the command

We can then use this by passing -c to the git-mit command.

git mit -c "../git-mit.toml" ae bt se

It's exactly the same for a YAML configuration

git mit -c "git-mit.yml" ae bt se

Or you can use the environment variables

export GIT_MIT_AUTHORS_CONFIG="../git-mit.toml"
git mit -c "$HOME/git-mit.toml" ae bt se

Or just put it at the default location

git mit ae bt se

Then next when you make a commit the Co-authored-by trailers will be set of the author initials you selected.

echo "# Hello, world!" > README.md

git add .
git commit --message="Initial Commit" --quiet
git show --pretty='format:author: [%an %ae] signed-by: [%GS] 
---
%B' -q
author: [Anyone Else anyone@example.com] signed-by: [] 
---
Initial Commit

Co-authored-by: Billie Thompson <billie@example.com>
Co-authored-by: Someone Else <se@example.com>

You don't need to constantly pass the config everywhere though, you can set an environment variable.

export GIT_MIT_AUTHORS_CONFIG="$HOME/git-mit.toml"
git mit se ae

So next time we commit

echo "Lorem Ipsum" >> README.md

git commit --all --message="Second Commit" --quiet
git show --pretty='format:author: [%an %ae] signed-by: [%GS] 
---
%B' -q

The author configuration will be updated like this

author: [Someone Else se@example.com] signed-by: [] 
---
Second Commit

Co-authored-by: Anyone Else <anyone@example.com>

If for some reason you've already added the author we won't duplicate it

echo "Lorem Ipsum" >> README.md

git commit --all --message="Second Commit

Co-authored-by: Anyone Else <anyone@example.com>
" --quiet
git show --pretty='format:author: [%an %ae] signed-by: [%GS] 
---
%B' -q

The author configuration will be updated like this

author: [Someone Else se@example.com] signed-by: [] 
---
Second Commit

Co-authored-by: Anyone Else <anyone@example.com>

Rebases

By default, we won't change the commit on rebase.

git mit-config mit set-non-clean-behaviour no-change
git mit-config mit non-clean-behaviour
no-change

If we have two diverging branches

echo "Lorem Ipsum" >> new-so-no-conflicts.md
git switch -c rebase-demo-branch
git switch -
git commit --all --message="Diverging commit" --quiet
git switch -

Now you can rebase changes without adding any additional trailers

git mit bt se
echo "Lorem Ipsum" >> README.md

git commit --all --message="Rebase behaviour
" --quiet
git show --pretty='format:author: [%an %ae] signed-by: [%GS] 
---
%B' -q
author: [Billie Thompson billie@example.com] signed-by: [] 
---
Rebase behaviour

Co-authored-by: Someone Else <se@example.com>

If you rebase, the commit stays the same, and the author does not change

git mit bt ae
git rebase --reset-author-date "-"
git show --pretty='format:author: [%an %ae] signed-by: [%GS] 
---
%B' -q
author: [Billie Thompson billie@example.com] signed-by: [] 
---
Rebase behaviour

Co-authored-by: Someone Else <se@example.com>

The alternative setting is to modify the co-authored by trailers.

git mit-config mit set-non-clean-behaviour add-to
git mit-config mit non-clean-behaviour
add-to

Now you can rebase changes without adding any additional trailers

git mit bt ae
git rebase --reset-author-date "-"
git show --pretty='format:author: [%an %ae] signed-by: [%GS] 
---
%B' -q
author: [Billie Thompson billie@example.com] signed-by: [] 
---
Rebase behaviour

Co-authored-by: Someone Else <se@example.com>
Co-authored-by: Anyone Else <anyone@example.com>

Signed Commits

The command also works with signed commits

The bt user has a valid gpg key.

git mit bt
echo "Delores Et" >> README.md

git commit --all --gpg-sign --message="Third Commit" --quiet
git show --pretty='format:author: [%an %ae] signed-by: [%GS] 
---
%B' -q
author: [Billie Thompson billie@example.com] signed-by: [Billie Thompson <billie@example.com>] 
---
Third Commit

Rotation

When pairing or mob programming you might want to rotate who appears as the primary author on each commit, so that credit is distributed evenly. This is an opt-in behaviour, just like the rebase behaviour above.

There are three rotation strategies:

  • off disables rotation (the default)
  • round-robin rotates through the authors in order, one per commit
  • random shuffles the authors randomly on each commit

By default rotation is off.

git-mit-config mit rotation
off

You can turn rotation on by running

git-mit-config mit set-rotation round-robin
git-mit-config mit rotation
round-robin

To see the effect, let's set up three authors and make a series of commits. Each commit will have a different primary author because the configuration rotates after every commit.

git mit bt se ae

The first commit has Billie Thompson as the author

echo "Rotation test" >> README.md
git commit --all --message="Rotation commit one" --quiet
git show --pretty='format:author: [%an %ae] signed-by: [%GS] 
---
%B' -q
author: [Billie Thompson billie@example.com] signed-by: [] 
---
Rotation commit one

Co-authored-by: Someone Else <se@example.com>
Co-authored-by: Anyone Else <anyone@example.com>

The author has now rotated, so the next commit will have Someone Else as the author

echo "Rotation test" >> README.md
git commit --all --message="Rotation commit two" --quiet
git show --pretty='format:author: [%an %ae] signed-by: [%GS] 
---
%B' -q
author: [Someone Else se@example.com] signed-by: [] 
---
Rotation commit two

Co-authored-by: Anyone Else <anyone@example.com>
Co-authored-by: Billie Thompson <billie@example.com>

And the third commit completes the cycle with Anyone Else as the author

echo "Rotation test" >> README.md
git commit --all --message="Rotation commit three" --quiet
git show --pretty='format:author: [%an %ae] signed-by: [%GS] 
---
%B' -q
author: [Anyone Else anyone@example.com] signed-by: [] 
---
Rotation commit three

Co-authored-by: Billie Thompson <billie@example.com>
Co-authored-by: Someone Else <se@example.com>

You can turn rotation off by running

git-mit-config mit set-rotation off
git-mit-config mit rotation
off

When rotation is off the author no longer changes between commits

echo "Rotation test" >> README.md
git commit --all --message="No rotation commit" --quiet
git show --pretty='format:author: [%an %ae] signed-by: [%GS] 
---
%B' -q
author: [Billie Thompson billie@example.com] signed-by: [] 
---
No rotation commit

Co-authored-by: Someone Else <se@example.com>
Co-authored-by: Anyone Else <anyone@example.com>

Random rotation

You can also shuffle authors randomly on each commit.

git-mit-config mit set-rotation random
git-mit-config mit rotation
random

With random rotation enabled, each commit gets a randomly chosen primary author from the configured set.

echo "Random rotation test" >> README.md
git commit --all --message="Random rotation commit" --quiet

Turn rotation off again

git-mit-config mit set-rotation off
git-mit-config mit rotation
off

Errors

If your authors file is broken like the one below (or for any other reason)

Hello, I am a broken file

You'll get an error when you run the command

git mit -c "broken.toml" ae bt se
Error: mit_commit_message_lints::mit::lib::authors::deserialise_authors_error

  × could not parse author configuration
   ╭────
 1 │ Hello, I am a broken file
   · ▲    ▲
   · │    ╰─┤ invalid in toml: TOML parse error at line 1, column 6
   · │      │   |
   · │      │ 1 | Hello, I am a broken file
   · │      │   |      ^
   · │      │ key with no value, expected `=`
   · │      │ 
   · ╰── invalid in yaml: expected mapping start at line 1, column 1
   ╰────
  help: `git mit-config mit example` can show you an example of what it should
        look like, or you can generate one using `git mit-config mit generate`
        after setting up some authors with `git mit-config mit set`

Same applies for git mit-config mit generate

git mit-config mit generate -c "broken.toml"
Error: mit_commit_message_lints::mit::lib::authors::deserialise_authors_error

  × could not parse author configuration
   ╭────
 1 │ Hello, I am a broken file
   · ▲    ▲
   · │    ╰─┤ invalid in toml: TOML parse error at line 1, column 6
   · │      │   |
   · │      │ 1 | Hello, I am a broken file
   · │      │   |      ^
   · │      │ key with no value, expected `=`
   · │      │ 
   · ╰── invalid in yaml: expected mapping start at line 1, column 1
   ╰────
  help: `git mit-config mit example` can show you an example of what it should
        look like, or you can generate one using `git mit-config mit generate`
        after setting up some authors with `git mit-config mit set`