componhead · July 10, 2025 06:55 · Dec 29, 2022 · Nov 9, 2022 · Nov 9, 2022 · Nov 9, 2022
diff --git a/signing-git-commits.md b/signing-git-commits.md
@@ -45,7 +45,7 @@ pinentry-program /opt/homebrew/bin/pinentry-mac
 **Note**: if you’re on Intel, `/opt/homebrew` should be `/usr/local`.
 
 
-Add the following lines `~/.zshrc` (the `GPG_TTY` environment variable is [a requirement for GPG](https://www.gnupg.org/documentation/manuals/gnupg/Invoking-GPG_002dAGENT.html#Invoking-GPG_002dAGENT); the second line launches the `gpg-agent` when you open a new shell):
+Add the following lines to `~/.zshrc` (the `GPG_TTY` environment variable is [a requirement for GPG](https://www.gnupg.org/documentation/manuals/gnupg/Invoking-GPG_002dAGENT.html#Invoking-GPG_002dAGENT); the second line launches the `gpg-agent` when you open a new shell):
 
 ```bash
 export GPG_TTY=$(tty)
@@ -223,4 +223,17 @@ $ git config --global gpg.x509.program smimesign
 $ git config --global gpg.format x509
 ```
 
-H/t to [@benhickson](https://gist.github.com/phortuin/cf24b1cca3258720c71ad42977e1ba57?permalink_comment_id=4201558#gistcomment-4201558) and [this excellent GitLab guide](https://docs.gitlab.com/ee/user/project/repository/x509_signed_commits/).
+H/t to [@benhickson](https://gist.github.com/phortuin/cf24b1cca3258720c71ad42977e1ba57?permalink_comment_id=4201558#gistcomment-4201558) and [this excellent GitLab guide](https://docs.gitlab.com/ee/user/project/repository/x509_signed_commits/).
+
+### 5. I don’t know what `.zshrc` is or how to edit it
+
+The `.zshrc` file is a configuration file for your zsh shell ([`rc` stands for `runcom`](https://tech.serhatteker.com/post/2020-03/what-does-rc-mean/)) that might not exist yet on your system. You can easily create it like this:
+
+```bash
+$ cd ~
+$ touch .zshrc
+```
+
+These kinds of 'dot files' are usually not edited with standard MacOS apps like TextEdit. You can use `vi` or `nano` from the command line instead. [Find some useful instructions here.](https://superuser.com/a/886135) 
+
+H/t to [@intricateavocado](https://gist.github.com/phortuin/cf24b1cca3258720c71ad42977e1ba57?permalink_comment_id=4397707#gistcomment-4397707)
diff --git a/signing-git-commits.md b/signing-git-commits.md
@@ -223,4 +223,4 @@ $ git config --global gpg.x509.program smimesign
 $ git config --global gpg.format x509
 ```
 
-H/t to [@benhickson](https://gist.github.com/benhickson) and [this excellent GitLab guide](https://docs.gitlab.com/ee/user/project/repository/x509_signed_commits/).
+H/t to [@benhickson](https://gist.github.com/phortuin/cf24b1cca3258720c71ad42977e1ba57?permalink_comment_id=4201558#gistcomment-4201558) and [this excellent GitLab guide](https://docs.gitlab.com/ee/user/project/repository/x509_signed_commits/).
diff --git a/signing-git-commits.md b/signing-git-commits.md
@@ -223,4 +223,4 @@ $ git config --global gpg.x509.program smimesign
 $ git config --global gpg.format x509
 ```
 
-H/t to @benhickson and [this excellent GitLab guide](https://docs.gitlab.com/ee/user/project/repository/x509_signed_commits/).
+H/t to [@benhickson](https://gist.github.com/benhickson) and [this excellent GitLab guide](https://docs.gitlab.com/ee/user/project/repository/x509_signed_commits/).
diff --git a/signing-git-commits.md b/signing-git-commits.md
@@ -171,14 +171,14 @@ Open VSCode, go to Preferences > Settings, and search for `git.enableCommitSigni
 
 ## Troubleshooting
 
-### 1.
+### 1. Kill the agent
 If for some reason you can’t sign, simply kill the agent. [It will restart when needed](https://superuser.com/a/1150399):
 
 ```bash
 $ gpgconf --kill gpg-agent
 ```
 
-### 2.
+### 2. Older/remote shells
 On older MacOS versions or certain (remote) shells, you might encounter the error `inappropriate ioctl for device`. (This error might also turn up if you haven’t configured the `GPG_TTY` environment variable correctly, see above for instructions.) [More context here](https://d.sb/2016/11/gpg-inappropriate-ioctl-for-device-errors). You can fix this by using the so called ‘loopback’ option to enter your passphrase directly on the CLI.
 
 Edit `gpg.conf` and add:
@@ -195,10 +195,32 @@ allow-loopback-pinentry
 
 Now, when the agent wants your passphrase it will simply render a basic password input on the CLI:
 
-```
+```bash
 $ echo 'it works' | gpg --clearsign
 Enter passphrase:
 ```
 
-### 3.
-If you use SourceTree, you should point it to the right binary. A solution is posted on [Stack Overflow](https://stackoverflow.com/a/27069408/554821), make sure to also follow [this comment](https://stackoverflow.com/questions/26697343/why-is-the-gnupg-sign-checkbox-disabled-in-sourcetree#comment86720717_27069408).
+### 3. Using SourceTree
+If you use SourceTree, you should point it to the right binary. A solution is posted on [Stack Overflow](https://stackoverflow.com/a/27069408/554821), make sure to also follow [this comment](https://stackoverflow.com/questions/26697343/why-is-the-gnupg-sign-checkbox-disabled-in-sourcetree#comment86720717_27069408).
+
+### 4. X.509 Certificate
+If the commit still can’t be signed, it could be that you use an X.509 certificate to sign your commits (this might be the case in a corporate environment, for example). Tell Git about it:
+
+```bash
+$ git config --global gpg.x509.program gpg
+```
+
+If that doesn’t cut it, install `smimesign`, an S/MIME signing utility for use with Git with Homebrew:
+
+```bash
+$ brew install smimesign
+```
+
+Then, configure git to use an X.509 certificate and `smimesign` as the gpg program. 
+
+```bash
+$ git config --global gpg.x509.program smimesign
+$ git config --global gpg.format x509
+```
+
+H/t to @benhickson and [this excellent GitLab guide](https://docs.gitlab.com/ee/user/project/repository/x509_signed_commits/).
diff --git a/signing-git-commits.md b/signing-git-commits.md
@@ -52,6 +52,12 @@ export GPG_TTY=$(tty)
 gpgconf --launch gpg-agent
 ``` 
 
+To effectuate the changes to `.zshrc`, type:
+
+```bash
+$ source ~/.zshrc
+```
+
 ## Create GPG keypair
 
 Now that your environment is properly set up, we need to generate a public/private GPG keypair.
@@ -173,7 +179,7 @@ $ gpgconf --kill gpg-agent
 ```
 
 ### 2.
-On older MacOS versions or certain remote shells, you might encounter the error `inappropriate ioctl for device`. [More context here](https://d.sb/2016/11/gpg-inappropriate-ioctl-for-device-errors). You can fix this by using the so called ‘loopback’ option to enter your passphrase directly on the CLI.
+On older MacOS versions or certain (remote) shells, you might encounter the error `inappropriate ioctl for device`. (This error might also turn up if you haven’t configured the `GPG_TTY` environment variable correctly, see above for instructions.) [More context here](https://d.sb/2016/11/gpg-inappropriate-ioctl-for-device-errors). You can fix this by using the so called ‘loopback’ option to enter your passphrase directly on the CLI.
 
 Edit `gpg.conf` and add:
 
@@ -195,4 +201,4 @@ Enter passphrase:
 ```
 
 ### 3.
-If you use SourceTree, you should point it to the right binary. A solution is posted on [Stack Overflow](https://stackoverflow.com/a/27069408/554821), make sure to follow [this comment](https://stackoverflow.com/questions/26697343/why-is-the-gnupg-sign-checkbox-disabled-in-sourcetree#comment86720717_27069408).
+If you use SourceTree, you should point it to the right binary. A solution is posted on [Stack Overflow](https://stackoverflow.com/a/27069408/554821), make sure to also follow [this comment](https://stackoverflow.com/questions/26697343/why-is-the-gnupg-sign-checkbox-disabled-in-sourcetree#comment86720717_27069408).
diff --git a/signing-git-commits.md b/signing-git-commits.md
@@ -165,12 +165,14 @@ Open VSCode, go to Preferences > Settings, and search for `git.enableCommitSigni
 
 ## Troubleshooting
 
+### 1.
 If for some reason you can’t sign, simply kill the agent. [It will restart when needed](https://superuser.com/a/1150399):
 
 ```bash
 $ gpgconf --kill gpg-agent
 ```
 
+### 2.
 On older MacOS versions or certain remote shells, you might encounter the error `inappropriate ioctl for device`. [More context here](https://d.sb/2016/11/gpg-inappropriate-ioctl-for-device-errors). You can fix this by using the so called ‘loopback’ option to enter your passphrase directly on the CLI.
 
 Edit `gpg.conf` and add:
@@ -190,4 +192,7 @@ Now, when the agent wants your passphrase it will simply render a basic password
 ```
 $ echo 'it works' | gpg --clearsign
 Enter passphrase:
-```
+```
+
+### 3.
+If you use SourceTree, you should point it to the right binary. A solution is posted on [Stack Overflow](https://stackoverflow.com/a/27069408/554821), make sure to follow [this comment](https://stackoverflow.com/questions/26697343/why-is-the-gnupg-sign-checkbox-disabled-in-sourcetree#comment86720717_27069408).
diff --git a/signing-git-commits.md b/signing-git-commits.md
@@ -116,7 +116,7 @@ sec   rsa4096/56667778 2021-11-12 [SC] [expires: 2023-11-12]
 uid         [ultimate] username <[email protected]>
 ```
 
-The `56667778` bit after `rsa4096/` is your short key ID. We need it to configure Git to sign commits and tags. Replace the ID below with your own:
+The `56667778` bit after `rsa4096/` is your short key ID. We need it to configure Git to sign commits and tags. Replace the `user.signingkey` value below with your own key ID:
 
 ```bash
 $ git config --global user.signingkey 56667778

diff --git a/signing-git-commits.md b/signing-git-commits.md
@@ -116,7 +116,7 @@ sec   rsa4096/56667778 2021-11-12 [SC] [expires: 2023-11-12]
 uid         [ultimate] username <[email protected]>
 ```
 
-We need the ID to configure Git, and tell Git to use GPG signing when committing and tagging commits. Replace the ID below with your own:
+The `56667778` bit after `rsa4096/` is your short key ID. We need it to configure Git to sign commits and tags. Replace the ID below with your own:
 
 ```bash
 $ git config --global user.signingkey 56667778

diff --git a/signing-git-commits.md b/signing-git-commits.md
@@ -100,7 +100,7 @@ it works
 
 ## Adding to Git
 
-We need to add your key to your git config, and to GitHub. First, you need to find the key ID. These are the last 8 characters of the key that was printed to the terminal before. You can retrieve them:
+We need to add your key to your git config, and to GitHub. First, you need to find the key ID. The (short) ID uses the last 8 characters of the key that was printed to the terminal before. You can retrieve it:
 
 ```bash
 $ gpg --list-secret-keys --keyid-format SHORT

diff --git a/signing-git-commits.md b/signing-git-commits.md
@@ -165,11 +165,10 @@ Open VSCode, go to Preferences > Settings, and search for `git.enableCommitSigni
 
 ## Troubleshooting
 
-If for some reason you can’t sign, simply restart the agent:
+If for some reason you can’t sign, simply kill the agent. [It will restart when needed](https://superuser.com/a/1150399):
 
 ```bash
 $ gpgconf --kill gpg-agent
-$ gpgconf --launch gpg-agent
 ```
 
 On older MacOS versions or certain remote shells, you might encounter the error `inappropriate ioctl for device`. [More context here](https://d.sb/2016/11/gpg-inappropriate-ioctl-for-device-errors). You can fix this by using the so called ‘loopback’ option to enter your passphrase directly on the CLI.

diff --git a/signing-git-commits.md b/signing-git-commits.md
@@ -153,9 +153,9 @@ $ gpg --armor --export 56667778 | pbcopy
 
 The `| pbcopy` part will pipe the output of the first part directly to your copy-paste memory. 
 
-Go to the [GitHub SSH and GPG keys section](https://github.com/settings/keys), click `[New GPG key]` and paste into the box. Click [Add GPG key], and you’re done!
+Go to the [GitHub SSH and GPG keys section](https://github.com/settings/keys), click [New GPG key] and paste into the box. Click [Add GPG key], and you’re done!
 
-After all this, and after having made your first signed commit, you can see the ‘Verified’ badge on GitHub for that commit ([see an example here](https://github.com/phortuin/gist-ssg/commit/5bd42616d2395f5511faa84cf02be82619d3c161)). Your GPG key ID will be shown when the badge is clicked. 
+After getting this done, and after having made your first signed commit, you can see the ‘Verified’ badge on GitHub for that commit ([see an example here](https://github.com/phortuin/gist-ssg/commit/5bd42616d2395f5511faa84cf02be82619d3c161)). Your GPG key ID will be shown when the badge is clicked. 
 
 ## Visual Studio Code
 

diff --git a/signing-git-commits.md b/signing-git-commits.md
@@ -68,7 +68,7 @@ A wizard is printed to your terminal. You should configure as follows:
 - Real name: `<your github username>`
 - Email address: `<your email address>`
 
-**Note**: I heartily recommend setting your email address to your 'noreply' GitHub address: `<username>@users.noreply.github.com`. You can find your email address on the [GitHub Email settings page](https://github.com/settings/emails). Note that if you created a GitHub account after July 2017, your address will also have an ID prefixed to your username; [read more here](https://docs.github.com/en/account-and-profile/setting-up-and-managing-your-github-user-account/managing-email-preferences/setting-your-commit-email-address).
+**Note**: I heartily recommend setting your email address to your 'noreply' GitHub address: `[email protected]`. You can find your email address on the [GitHub Email settings page](https://github.com/settings/emails). Note that if you created a GitHub account after July 2017, your address will also have an ID prefixed to your username; [read more here](https://docs.github.com/en/account-and-profile/setting-up-and-managing-your-github-user-account/managing-email-preferences/setting-your-commit-email-address).
 
 The final step in setting up the GPG keypair is typing a passphrase. Make sure it is strong and you have it safely stored in your password vault (I recommend [Bitwarden](https://bitwarden.com/)). Whoever has your passphrase can sign your commits and there is no way to prove it wasn’t you.
 

diff --git a/signing-git-commits.md b/signing-git-commits.md
@@ -39,7 +39,7 @@ $ brew install pinentry-mac
 If you installed `pinentry-mac`, make sure to configure the agent. Open the `gpg-agent.conf` file and add this line:
 
 ```bash
-pinentry-program opt/homebrew/bin/pinentry-mac
+pinentry-program /opt/homebrew/bin/pinentry-mac
 ```
 
 **Note**: if you’re on Intel, `/opt/homebrew` should be `/usr/local`.

diff --git a/signing-git-commits.md b/signing-git-commits.md
@@ -151,11 +151,17 @@ You need to copy the whole block and add it to GitHub. If you’re not sure what
 $ gpg --armor --export 56667778 | pbcopy
 ```
 
-The `| pbcopy` part will pipe the output of the first part directly to your copy and paste memory. Go to the [GitHub SSH and GPG keys section](https://github.com/settings/keys), click `[New GPG key]` and paste into the box. Click [Add GPG key], and it’s done.
+The `| pbcopy` part will pipe the output of the first part directly to your copy-paste memory. 
 
-If you use Visual Studio Code, you can turn on signing by changing a setting. Open VSCode, go to Preferences > Settings, and search for `git.enableCommitSigning`. Turn this setting on, and you’re good to go.
+Go to the [GitHub SSH and GPG keys section](https://github.com/settings/keys), click `[New GPG key]` and paste into the box. Click [Add GPG key], and you’re done!
 
-After you’ve turned on signing and made a commit, you can see the ‘Verified’ badge on GitHub. Your GPG key ID will be shown there as well. 
+After all this, and after having made your first signed commit, you can see the ‘Verified’ badge on GitHub for that commit ([see an example here](https://github.com/phortuin/gist-ssg/commit/5bd42616d2395f5511faa84cf02be82619d3c161)). Your GPG key ID will be shown when the badge is clicked. 
+
+## Visual Studio Code
+
+If you use Visual Studio Code, you can turn on signing by changing a setting.
+
+Open VSCode, go to Preferences > Settings, and search for `git.enableCommitSigning`. Turn this setting on, and you’re good to go.
 
 ## Troubleshooting
 

diff --git a/signing-git-commits.md b/signing-git-commits.md
@@ -23,7 +23,7 @@ Open the `gpg.conf` file and add:
 use-agent
 ```
 
-In `gpg-agent.conf`, add the following lines to make sure your credentials are 'kept alive' ([source](https://superuser.com/questions/624343/keep-gnupg-credentials-cached-for-entire-user-session)):
+In `gpg-agent.conf`, add the following lines to make sure your credentials are ‘kept alive’ ([source](https://superuser.com/questions/624343/keep-gnupg-credentials-cached-for-entire-user-session)):
 
 ```bash
 default-cache-ttl 34560000

diff --git a/signing-git-commits.md b/signing-git-commits.md
@@ -30,7 +30,7 @@ default-cache-ttl 34560000
 max-cache-ttl 34560000
 ```
 
-Optionally, you can install a GUI for entering your passphrase. You don’t need to, but the default is a CLI program and might not provide a nice user experience.
+Optionally, you can install a GUI for entering your passphrase. You don’t need to, but the default is a CLI program and might not provide a nice user experience. With `pinentry-mac` you can choose to save your passphrase in your MacOS keychain. That’s up to your personal preference.
 
 ```bash
 $ brew install pinentry-mac
@@ -44,6 +44,7 @@ pinentry-program opt/homebrew/bin/pinentry-mac
 
 **Note**: if you’re on Intel, `/opt/homebrew` should be `/usr/local`.
 
+
 Add the following lines `~/.zshrc` (the `GPG_TTY` environment variable is [a requirement for GPG](https://www.gnupg.org/documentation/manuals/gnupg/Invoking-GPG_002dAGENT.html#Invoking-GPG_002dAGENT); the second line launches the `gpg-agent` when you open a new shell):
 
 ```bash

diff --git a/signing-git-commits.md b/signing-git-commits.md
@@ -39,9 +39,11 @@ $ brew install pinentry-mac
 If you installed `pinentry-mac`, make sure to configure the agent. Open the `gpg-agent.conf` file and add this line:
 
 ```bash
-pinentry-program $(brew --prefix)/bin/pinentry-mac
+pinentry-program opt/homebrew/bin/pinentry-mac
 ```
 
+**Note**: if you’re on Intel, `/opt/homebrew` should be `/usr/local`.
+
 Add the following lines `~/.zshrc` (the `GPG_TTY` environment variable is [a requirement for GPG](https://www.gnupg.org/documentation/manuals/gnupg/Invoking-GPG_002dAGENT.html#Invoking-GPG_002dAGENT); the second line launches the `gpg-agent` when you open a new shell):
 
 ```bash

diff --git a/signing-git-commits.md b/signing-git-commits.md
@@ -2,6 +2,8 @@ Based on [this blogpost](https://withblue.ink/2020/05/17/how-and-why-to-sign-git
 
 To [sign Git commits](https://docs.github.com/en/authentication/managing-commit-signature-verification/generating-a-new-gpg-key), you need a gpg key. GPG stands for GNU Privacy Guard and is the de facto implementation of the [OpenPGP message format](https://www.ietf.org/rfc/rfc4880.txt). PGP stands for ‘Pretty Good Privacy’ and is a standard to sign and encrypt messages.
 
+## Setting up
+
 Install with Homebrew:
 
 ```bash
@@ -36,7 +38,7 @@ $ brew install pinentry-mac
 
 If you installed `pinentry-mac`, make sure to configure the agent. Open the `gpg-agent.conf` file and add this line:
 
-```
+```bash
 pinentry-program $(brew --prefix)/bin/pinentry-mac
 ```
 
@@ -47,10 +49,12 @@ export GPG_TTY=$(tty)
 gpgconf --launch gpg-agent
 ``` 
 
+## Create GPG keypair
+
 Now that your environment is properly set up, we need to generate a public/private GPG keypair.
 
 ```bash
-gpg --full-gen-key
+$ gpg --full-gen-key
 ```
 
 A wizard is printed to your terminal. You should configure as follows:
@@ -59,66 +63,123 @@ A wizard is printed to your terminal. You should configure as follows:
 - Keysize: `4096`
 - Expiration: `2y` (your key will expire after 2 years; you should set a reminder somewhere)
 - Real name: `<your github username>`
-- Email address: 
+- Email address: `<your email address>`
+
+**Note**: I heartily recommend setting your email address to your 'noreply' GitHub address: `<username>@users.noreply.github.com`. You can find your email address on the [GitHub Email settings page](https://github.com/settings/emails). Note that if you created a GitHub account after July 2017, your address will also have an ID prefixed to your username; [read more here](https://docs.github.com/en/account-and-profile/setting-up-and-managing-your-github-user-account/managing-email-preferences/setting-your-commit-email-address).
 
-Your real name. You could use your GitHub username here if you’d like.
-Email address. If you plan to use this key for more than just Git, you might want to put your real email address. If it’s just for GitHub, you can use the @users.noreply.github.com email that GitHub generates for you: you can find it on the Email settings page.
-You will be asked to type a passphrase which is used to encrypt your secret key on disk. This is important, otherwise attackers could steal your secret key, and then they’d be able to sign messages and Git commits pretending to be you.
+The final step in setting up the GPG keypair is typing a passphrase. Make sure it is strong and you have it safely stored in your password vault (I recommend [Bitwarden](https://bitwarden.com/)). Whoever has your passphrase can sign your commits and there is no way to prove it wasn’t you.
 
-ding wordt gemaakt, ziet er oz uit
+After creating the keypair, output similar to the following is printed to your terminal:
 
+```bash
+pub   rsa4096 2021-11-12 [SC] [expires: 2023-11-12]
+      AAABBBCCCDDDEEEFFF1112223334445556667778
+uid                      username <[email protected]>
 ```
-pub   rsa4096 2021-11-11 [SC] [expires: 2023-11-11]
-      54829FF855AF65C595E6F7C33F296E2FC9ED8D20
-uid                      phortuin <[email protected]>
+
+The string of characters is your key ID. To confirm you can sign messages with your newly created key, enter in your terminal:
+
+```bash
+$ echo 'it works' | gpg --clearsign
+```
+
+A message similar to this should appear:
+
+```bash
+-----BEGIN PGP SIGNED MESSAGE-----
+Hash: SHA256
+
+it works
+-----BEGIN PGP SIGNATURE-----
+<many characters>
+-----END PGP SIGNATURE-----
 ```
 
-dan 
+## Adding to Git
 
-gpg --list-secret-keys --keyid-format SHORT
+We need to add your key to your git config, and to GitHub. First, you need to find the key ID. These are the last 8 characters of the key that was printed to the terminal before. You can retrieve them:
 
+```bash
+$ gpg --list-secret-keys --keyid-format SHORT
 ```
-/Users/phortuin/.gnupg/pubring.kbx
+
+Outputs:
+
+```bash
+/Users/username/.gnupg/pubring.kbx
 ----------------------------------
-sec   rsa4096/C9ED8D20 2021-11-11 [SC] [expires: 2023-11-11]
-      54829FF855AF65C595E6F7C33F296E2FC9ED8D20
-uid         [ultimate] phortuin <phortuin@users.noreply.github.com>
+sec   rsa4096/56667778 2021-11-12 [SC] [expires: 2023-11-12]
+      AAABBBCCCDDDEEEFFF1112223334445556667778
+uid         [ultimate] username <username@users.noreply.github.com>
 ```
 
-now you can do 
+We need the ID to configure Git, and tell Git to use GPG signing when committing and tagging commits. Replace the ID below with your own:
 
-echo "hello world" | gpg --clearsign
-If your GPG agent is having issues, you can restart it with:
+```bash
+$ git config --global user.signingkey 56667778
+$ git config --global commit.gpgSign true
+$ git config --global tag.gpgSign true
+```
 
-gpgconf --kill gpg-agent
-gpgconf --launch gpg-agent
+Git needs to know your email, and it needs to be the same as the one for your GPG key. This email address needs to be verified on GitHub as well. If you use your ‘private’ GitHub email, that’s already the case.
 
-still issues (inappropriate ioctl for device)
+```bash
+$ git config --global user.email [email protected]
+```
 
-https://d.sb/2016/11/gpg-inappropriate-ioctl-for-device-errors
+Finally, you need to add your public GPG key to GitHub. Again, make sure to replace the ID with your own ID:
 
-gpg.conf: pinentry-mode loopback
-gpg-agent.conf allow-loopback-pinentry
+```bash
+$ gpg --armor --export 56667778
+```
 
-loopback lets you enter your passphrase directly on the CLI. this is less useful if you are triggering gpg session from within vscode for instance (a gui like pinentry-mac is handier)
+Outputs: 
 
-## adding to Git
+```bash
+-----BEGIN PGP PUBLIC KEY BLOCK-----
 
-git config --global user.signingkey C9ED8D20
+<many characters>
+-----END PGP PUBLIC KEY BLOCK-----
+```
 
-git config --global commit.gpgSign true
-git config --global tag.gpgSign true
+You need to copy the whole block and add it to GitHub. If you’re not sure what to copy, use this command:
 
-make sure git knows your email
+```
+$ gpg --armor --export 56667778 | pbcopy
+```
+
+The `| pbcopy` part will pipe the output of the first part directly to your copy and paste memory. Go to the [GitHub SSH and GPG keys section](https://github.com/settings/keys), click `[New GPG key]` and paste into the box. Click [Add GPG key], and it’s done.
+
+If you use Visual Studio Code, you can turn on signing by changing a setting. Open VSCode, go to Preferences > Settings, and search for `git.enableCommitSigning`. Turn this setting on, and you’re good to go.
 
-git config --global user.email [email protected]
+After you’ve turned on signing and made a commit, you can see the ‘Verified’ badge on GitHub. Your GPG key ID will be shown there as well. 
 
-get public key
+## Troubleshooting
 
-gpg --armor --export C9ED8D20
+If for some reason you can’t sign, simply restart the agent:
 
-add here: https://github.com/settings/keys
+```bash
+$ gpgconf --kill gpg-agent
+$ gpgconf --launch gpg-agent
+```
 
-in vscode search
+On older MacOS versions or certain remote shells, you might encounter the error `inappropriate ioctl for device`. [More context here](https://d.sb/2016/11/gpg-inappropriate-ioctl-for-device-errors). You can fix this by using the so called ‘loopback’ option to enter your passphrase directly on the CLI.
 
-git.enableCommitSigning
+Edit `gpg.conf` and add:
+
+```bash
+pinentry-mode loopback
+```
+
+Edit `gpg-agent.conf` and add:
+
+```bash
+allow-loopback-pinentry
+```
+
+Now, when the agent wants your passphrase it will simply render a basic password input on the CLI:
+
+```
+$ echo 'it works' | gpg --clearsign
+Enter passphrase:
+```
diff --git a/signing-git-commits.md b/signing-git-commits.md
@@ -40,26 +40,26 @@ If you installed `pinentry-mac`, make sure to configure the agent. Open the `gpg
 pinentry-program $(brew --prefix)/bin/pinentry-mac
 ```
 
-Add the following lines `~/.zshrc`. 
-- The `GPG_TTY` environment variable is [a requirement for GPG](https://www.gnupg.org/documentation/manuals/gnupg/Invoking-GPG_002dAGENT.html#Invoking-GPG_002dAGENT)
-- The second line launches the `gpg-agent` when you open a new shell
+Add the following lines `~/.zshrc` (the `GPG_TTY` environment variable is [a requirement for GPG](https://www.gnupg.org/documentation/manuals/gnupg/Invoking-GPG_002dAGENT.html#Invoking-GPG_002dAGENT); the second line launches the `gpg-agent` when you open a new shell):
 
 ```bash
 export GPG_TTY=$(tty)
 gpgconf --launch gpg-agent
 ``` 
 
-Now that your environment is properly set up, we need to generate a key.
-
-To start, generate a new GPG key pair (public and private):
+Now that your environment is properly set up, we need to generate a public/private GPG keypair.
 
+```bash
 gpg --full-gen-key
-Configure the key with:
+```
+
+A wizard is printed to your terminal. You should configure as follows:
 
-Kind of key: type 4 for (4) RSA (sign only)
-Keysize: 4096
-Expiration: choose a reasonable value, for example 2y for 2 years (it can be renewed)
-Then answer a few questions:
+- Kind of key: `4` (RSA, sign only)
+- Keysize: `4096`
+- Expiration: `2y` (your key will expire after 2 years; you should set a reminder somewhere)
+- Real name: `<your github username>`
+- Email address: 
 
 Your real name. You could use your GitHub username here if you’d like.
 Email address. If you plan to use this key for more than just Git, you might want to put your real email address. If it’s just for GitHub, you can use the @users.noreply.github.com email that GitHub generates for you: you can find it on the Email settings page.

diff --git a/signing-git-commits.md b/signing-git-commits.md
@@ -40,7 +40,9 @@ If you installed `pinentry-mac`, make sure to configure the agent. Open the `gpg
 pinentry-program $(brew --prefix)/bin/pinentry-mac
 ```
 
-Add these lines to your bash/zsh `rc` or `_config` files (when in doubt, add them to `~/.zshrc`). The `GPG_TTY` environment variable is [a requirement for GPG](https://www.gnupg.org/documentation/manuals/gnupg/Invoking-GPG_002dAGENT.html#Invoking-GPG_002dAGENT), the second line launches the `gpg-agent` when you open a new shell:
+Add the following lines `~/.zshrc`. 
+- The `GPG_TTY` environment variable is [a requirement for GPG](https://www.gnupg.org/documentation/manuals/gnupg/Invoking-GPG_002dAGENT.html#Invoking-GPG_002dAGENT)
+- The second line launches the `gpg-agent` when you open a new shell
 
 ```bash
 export GPG_TTY=$(tty)

diff --git a/signing-git-commits.md b/signing-git-commits.md
@@ -34,20 +34,21 @@ Optionally, you can install a GUI for entering your passphrase. You don’t need
 $ brew install pinentry-mac
 ```
 
-If you installed `pinentry-mac`, make sure to configure the agent. Open the `gpg-agent.conf` file and add a new line:
+If you installed `pinentry-mac`, make sure to configure the agent. Open the `gpg-agent.conf` file and add this line:
 
 ```
 pinentry-program $(brew --prefix)/bin/pinentry-mac
 ```
 
-
-Then open zshrc and add
+Add these lines to your bash/zsh `rc` or `_config` files (when in doubt, add them to `~/.zshrc`). The `GPG_TTY` environment variable is [a requirement for GPG](https://www.gnupg.org/documentation/manuals/gnupg/Invoking-GPG_002dAGENT.html#Invoking-GPG_002dAGENT), the second line launches the `gpg-agent` when you open a new shell:
 
 ```bash
 export GPG_TTY=$(tty)
 gpgconf --launch gpg-agent
 ``` 
 
+Now that your environment is properly set up, we need to generate a key.
+
 To start, generate a new GPG key pair (public and private):
 
 gpg --full-gen-key

diff --git a/signing-git-commits.md b/signing-git-commits.md
@@ -1,5 +1,3 @@
-# Setup MacOS for signing Git commits
-
 Based on [this blogpost](https://withblue.ink/2020/05/17/how-and-why-to-sign-git-commits.html).
 
 To [sign Git commits](https://docs.github.com/en/authentication/managing-commit-signature-verification/generating-a-new-gpg-key), you need a gpg key. GPG stands for GNU Privacy Guard and is the de facto implementation of the [OpenPGP message format](https://www.ietf.org/rfc/rfc4880.txt). PGP stands for ‘Pretty Good Privacy’ and is a standard to sign and encrypt messages.
@@ -23,23 +21,22 @@ Open the `gpg.conf` file and add:
 use-agent
 ```
 
-In 
+In `gpg-agent.conf`, add the following lines to make sure your credentials are 'kept alive' ([source](https://superuser.com/questions/624343/keep-gnupg-credentials-cached-for-entire-user-session)):
 
+```bash
+default-cache-ttl 34560000
+max-cache-ttl 34560000
+```
 
-You can install a programme to enter your passphrase, but you don’t need to. 
+Optionally, you can install a GUI for entering your passphrase. You don’t need to, but the default is a CLI program and might not provide a nice user experience.
 
 ```bash
 $ brew install pinentry-mac
 ```
 
-
-Open `gpg-agent.conf` file and add (this will keep your credentials alive and set `pinentry-mac` as pin app)
+If you installed `pinentry-mac`, make sure to configure the agent. Open the `gpg-agent.conf` file and add a new line:
 
 ```
-# https://superuser.com/questions/624343/keep-gnupg-credentials-cached-for-entire-user-session
-default-cache-ttl 34560000
-max-cache-ttl 34560000
-
 pinentry-program $(brew --prefix)/bin/pinentry-mac
 ```
 

diff --git a/signing-git-commits.md b/signing-git-commits.md
@@ -2,34 +2,36 @@
 
 Based on [this blogpost](https://withblue.ink/2020/05/17/how-and-why-to-sign-git-commits.html).
 
-To [sign Git commits](https://docs.github.com/en/authentication/managing-commit-signature-verification/generating-a-new-gpg-key), you need a gpg key. GPG stands for Gnu Privacy Guard and is the de facto implementation of the [OpenPGP message format](https://www.ietf.org/rfc/rfc4880.txt). PGP stands for ‘Pretty Good Privacy’ and is a standard to sign and encrypt messages.
-
+To [sign Git commits](https://docs.github.com/en/authentication/managing-commit-signature-verification/generating-a-new-gpg-key), you need a gpg key. GPG stands for GNU Privacy Guard and is the de facto implementation of the [OpenPGP message format](https://www.ietf.org/rfc/rfc4880.txt). PGP stands for ‘Pretty Good Privacy’ and is a standard to sign and encrypt messages.
 
 Install with Homebrew:
 
 ```bash
 $ brew install gpg
 ```
 
-You can install a programme to enter your passphrase, but you don’t need to. 
+Create config files for `gpg` and the `gpg-agent`. The agent will make sure you don’t have to type in your GPG passphrase for every commit.
 
 ```bash
-$ brew install pinentry-mac
+$ mkdir ~/.gnupg
+$ touch ~/.gnupg/gpg.conf ~/.gnupg/gpg-agent.conf
 ```
 
-Create config files for gpg:
+Open the `gpg.conf` file and add:
 
 ```bash
-$ mkdir ~/.gnupg
-$ touch ~/.gnupg/gpg.conf
-$ touch ~/.gnupg/gpg-agent.conf
+use-agent
 ```
 
-Open the `gpg.conf` file and add
+In 
 
+
+You can install a programme to enter your passphrase, but you don’t need to. 
+
+```bash
+$ brew install pinentry-mac
 ```
-use-agent
-```
+
 
 Open `gpg-agent.conf` file and add (this will keep your credentials alive and set `pinentry-mac` as pin app)
 
@@ -41,7 +43,6 @@ max-cache-ttl 34560000
 pinentry-program $(brew --prefix)/bin/pinentry-mac
 ```
 
-(on Intel, use `/usr/local`)
 
 Then open zshrc and add
 

diff --git a/gistfile1.txt → signing-git-commits.md b/gistfile1.txt → signing-git-commits.md
diff --git a/gistfile1.txt b/gistfile1.txt
@@ -0,0 +1,123 @@
+# Setup MacOS for signing Git commits
+
+Based on [this blogpost](https://withblue.ink/2020/05/17/how-and-why-to-sign-git-commits.html).
+
+To [sign Git commits](https://docs.github.com/en/authentication/managing-commit-signature-verification/generating-a-new-gpg-key), you need a gpg key. GPG stands for Gnu Privacy Guard and is the de facto implementation of the [OpenPGP message format](https://www.ietf.org/rfc/rfc4880.txt). PGP stands for ‘Pretty Good Privacy’ and is a standard to sign and encrypt messages.
+
+
+Install with Homebrew:
+
+```bash
+$ brew install gpg
+```
+
+You can install a programme to enter your passphrase, but you don’t need to. 
+
+```bash
+$ brew install pinentry-mac
+```
+
+Create config files for gpg:
+
+```bash
+$ mkdir ~/.gnupg
+$ touch ~/.gnupg/gpg.conf
+$ touch ~/.gnupg/gpg-agent.conf
+```
+
+Open the `gpg.conf` file and add
+
+```
+use-agent
+```
+
+Open `gpg-agent.conf` file and add (this will keep your credentials alive and set `pinentry-mac` as pin app)
+
+```
+# https://superuser.com/questions/624343/keep-gnupg-credentials-cached-for-entire-user-session
+default-cache-ttl 34560000
+max-cache-ttl 34560000
+
+pinentry-program $(brew --prefix)/bin/pinentry-mac
+```
+
+(on Intel, use `/usr/local`)
+
+Then open zshrc and add
+
+```bash
+export GPG_TTY=$(tty)
+gpgconf --launch gpg-agent
+``` 
+
+To start, generate a new GPG key pair (public and private):
+
+gpg --full-gen-key
+Configure the key with:
+
+Kind of key: type 4 for (4) RSA (sign only)
+Keysize: 4096
+Expiration: choose a reasonable value, for example 2y for 2 years (it can be renewed)
+Then answer a few questions:
+
+Your real name. You could use your GitHub username here if you’d like.
+Email address. If you plan to use this key for more than just Git, you might want to put your real email address. If it’s just for GitHub, you can use the @users.noreply.github.com email that GitHub generates for you: you can find it on the Email settings page.
+You will be asked to type a passphrase which is used to encrypt your secret key on disk. This is important, otherwise attackers could steal your secret key, and then they’d be able to sign messages and Git commits pretending to be you.
+
+ding wordt gemaakt, ziet er oz uit
+
+```
+pub   rsa4096 2021-11-11 [SC] [expires: 2023-11-11]
+      54829FF855AF65C595E6F7C33F296E2FC9ED8D20
+uid                      phortuin <[email protected]>
+```
+
+dan 
+
+gpg --list-secret-keys --keyid-format SHORT
+
+```
+/Users/phortuin/.gnupg/pubring.kbx
+----------------------------------
+sec   rsa4096/C9ED8D20 2021-11-11 [SC] [expires: 2023-11-11]
+      54829FF855AF65C595E6F7C33F296E2FC9ED8D20
+uid         [ultimate] phortuin <[email protected]>
+```
+
+now you can do 
+
+echo "hello world" | gpg --clearsign
+If your GPG agent is having issues, you can restart it with:
+
+gpgconf --kill gpg-agent
+gpgconf --launch gpg-agent
+
+still issues (inappropriate ioctl for device)
+
+https://d.sb/2016/11/gpg-inappropriate-ioctl-for-device-errors
+
+gpg.conf: pinentry-mode loopback
+gpg-agent.conf allow-loopback-pinentry
+
+loopback lets you enter your passphrase directly on the CLI. this is less useful if you are triggering gpg session from within vscode for instance (a gui like pinentry-mac is handier)
+
+## adding to Git
+
+git config --global user.signingkey C9ED8D20
+
+git config --global commit.gpgSign true
+git config --global tag.gpgSign true
+
+make sure git knows your email
+
+git config --global user.email [email protected]
+
+get public key
+
+gpg --armor --export C9ED8D20
+
+add here: https://github.com/settings/keys
+
+in vscode search
+
+git.enableCommitSigning