SQ-GIT(1)

SQ-GIT 💅 (section 1 of the manual, bestie)

okay so this is the user commands corner of the manual for sq-git, and today we're hyperfixating on the log subcommand. grab a strawberry 🍓, we're verifying commits.

---

✨ NAME ✨

sq-git-log — Lists and verifies commits. that's it. that's the whole job. 👑

---

🌸 SYNOPSIS 🌸

sq-git log [OPTIONS] COMMIT_RANGE

---

🦋 DESCRIPTION 🦋

Lists and verifies commits. iconic. no notes. ✨

So like, it lists and verifies that the commits going from the given trust root all the way to the target commit actually adhere to the policy. vibe check, but for your git history.

A version is considered authenticated if there's a path from the trust root to the target commit where every single commit on that path can be authenticated by its parent. literally a chain of trust, a little relay race of signatures. 🏃♀️

Now, the spicy part. If the key that signed a commit is hard revoked, then that commit is considered bad. sq-git looks for hard revocations in all of the commits it examines. so the way that a project maintainer can add a hard revocation to a commit's policy file and it will cause later and earlier commits signed with that key to be considered invalid. not just forward — backward too. this is useful when a key has been compromised. 🚨

When a key has been hard revoked, downstream users either need to start using a more recent trust root, or the upstream project maintainers need to audit the relevant commits. If the commits are considered benign, they can be added to a goodlist using sq-git policy goodlist. 📝

And then — when a commit is considered authenticated but the certificate has been hard revoked, sq-git looks to see whether the commit has been goodlisted by a commit that is on an authenticated path from the commit in question to the target. If so, the commit is considered to be authenticated. slay, redemption arc. 🫶

---

💖 OPTIONS 💖

🎀 Subcommand options

• --keep-going — Continues to check commits even when it is clear that the target commit cannot be authenticated.

Causes sq-git log to continue to check commits rather than stopping as soon as it is clear that the version can't be authenticated. like bestie, we already know the ending, but we're gonna read every page anyway. 📖

• --policy-file=POLICY — Use an alternate policy.

The default policy is the openpgp-policy.toml file in the root of the repository's working tree. (so that's the one it grabs unless you say otherwise 💁♀️)

• --prune-certs — After authenticating the current version, prunes the certificates.

After authenticating the current version, prunes unused components of the certificates. In particular, subkeys that were not used to verify a signature, and user IDs that were never considered primary are removed. ✂️

This does not remove unused certificates from the policy file; this just minimizes them.

This requires the retire-user capability. don't forget or it's not happening 💅

• --trust-root=COMMIT — Specifies the trust root.

If no policy is specified, then the value of the git repository's sequoia.trustRoot configuration key is used as the trust root. 🔑

• COMMIT_RANGE — The commits to check.

If not specified, HEAD is authenticated with respect to the trust root.

If a single commit ID is specified, the specified commit is authenticated with respect to the trust root.

If a commit range like 3895a3a..3b388ae is specified, the end of the range is authenticated with respect to the trust root, and there must be an authenticated path from the trust root via the start of the range to the end of the range.

🌈 Global options

See sq-git(1) for a description of the global options. (yes, more lore, go read it 🫶)

---

⭐ SEE ALSO ⭐

sq-git(1).

For the full documentation see <https://sequoia-pgp.gitlab.io/sequoia-git>. 📚

---

👑 VERSION 👑

0.6.0

---

k bye bestie, that's the whole page — brought to you by Sequoia PGP, version 0.6.0, and the letter SQ-GIT(1). mwah. 💜🧚✨