Skip to content

mit.md

Latest commit

 

History

History
405 lines (301 loc) · 11.3 KB

mit.md

File metadata and controls

405 lines (301 loc) · 11.3 KB

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        │
╰─────────┴─────────────────┴────────────────────┴─────────────╯

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

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::serialise_authors_error

  × could not parse author configuration
   ╭────
 1 │ Hello, I am a broken file
   · ▲    ▲
   · │    ╰── invalid in toml: 
   · ╰── invalid in yaml: 
   ╰────
  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::serialise_authors_error

  × could not parse author configuration
   ╭────
 1 │ Hello, I am a broken file
   · ▲    ▲
   · │    ╰── invalid in toml: 
   · ╰── invalid in yaml: 
   ╰────
  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`