format-signature Git Command Guide

The git format-signature format defines how cryptographic signatures are embedded in Git objects and transactions. It supports multiple signature algorithms including PGP, SSH, and X.509, enabling secure verification of commits, tags, and push operations.

Cryptographic Signature Format Specification

Signature Algorithms:

Format	Header Start	Header End	Key Type
PGP	-----BEGIN PGP SIGNATURE-----	-----END PGP SIGNATURE-----	OpenPGP
SSH	-----BEGIN SSH SIGNATURE-----	-----END SSH SIGNATURE-----	RSA/ECDSA/Ed25519
X.509	-----BEGIN SIGNED MESSAGE-----	-----END SIGNED MESSAGE-----	Certificate

Embedding in Objects:

Tag Objects:

object <sha1>
type tag
tag <tagname>
tagger <name> <email> <timestamp>

[tag message]

gpgsig sha256 ssh <signature block>
-----BEGIN SSH SIGNATURE-----
<encoded signature data>
-----END SSH SIGNATURE-----

Commit Objects:

tree <sha1>
parent <sha1>
author <name> <email> <timestamp>
committer <name> <email> <timestamp>

<commit message>

gpgsig sha1 openpgp
-----BEGIN PGP SIGNATURE-----
<PGP signature data>
-----END PGP SIGNATURE-----

Signature Creation Process:

1. Extract Payload: Remove existing signatures from object content
2. Hash Payload: Generate cryptographic hash (SHA-1, SHA-256, etc.)
3. Sign Hash: Create detached signature using private key
4. Embed Signature: Append signature block to object content
5. Update Object: Re-hash object with embedded signatures

Verification Process:

Tag Verification:

git verify-tag <tagname>

Checks signature against tag’s tagged object

Commit Verification:

git verify-commit <commit>

Validates commit signature integrity

Log with Signature Status:

git log --show-signature

Shows signature verification status for each commit

Supported GPG Formats:

gpg.format	Description	Algorithm Support
gpg	Traditional PGP/GPG	RSA, DSA, ElGamal, ECDSA
ssh	SSH signing keys	RSA, ECDSA, Ed25519
x509	X.509 certificates	Multiple elliptic curves

Caution

Unsigned objects can be modified by anyone. Signed objects provide authenticity but not necessarily trust. Different programs may support different signature formats.

Examples of git signature operations:

Create signed commit

git commit -S -m "Signed commit message"

Creates commit with GPG signature

Create signed tag

git tag -s v1.0 -m "Release version 1.0"

Creates annotated tag with signature

Verify all tags

git tag -v | head -5

Verifies signature validity for recent tags

Show commit signature details

git show --show-signature HEAD

Displays commit with signature verification

Configure signature format

git config gpg.format ssh

Uses SSH keys instead of GPG for signing

Import SSH signing key

git config user.signingKey "$(cat ~/.ssh/id_ed25519.pub)"

Sets SSH public key for commit signing

Check signature status

git log --show-signature -1

Shows signature verification for latest commit

Configure OpenPGP program

git config gpg.program gpg2

Uses GPG2 instead of default GPG

Tip

Use git config commit.gpgSign true to sign all commits by default. Test signatures with git verify-commit before sharing.

How do I check which signature formats my Git supports?

Git supports signature formats based on available signing programs. Use --show-signature options in git log and git show to verify signature status.

How do commits and tags differ in signature embedding?

Commits embed signatures directly in object content with gpgsig headers. Tags place signatures after the tag payload, which includes the tagged object reference.

Can I use multiple signature formats in one repository?

Yes, different commits and tags can use different signature formats based on gpg.format configuration at signing time. Mix PGP, SSH, and X.509 signatures freely.

What happens if I modify a signed object?

Signature verification will fail with “gpg: BAD signature” or similar. Changed content invalidates the cryptographic signature.

How do merge commits handle signatures?

Merge commits can be signed, but individual parent commits maintain their own signatures. Use --no-gpg-sign for merges if signatures are problematic.

Can I configure Git to sign all operations?

commit.gpgSign affects commits, tag.gpgSign controls tags. Push operations have separate signature mechanisms via hooks.

What if my GPG key expires?

Expired keys cause verification failures. Use --allow-expired in gpg commands or update keys in Git configuration.

How do I troubleshoot signature verification issues?

Check key presence with gpg --list-keys, test signature creation, verify git config settings, and ensure gpg-agent is running.

Can X.509 certificates be used for Git signing?

Yes, Git supports X.509 certificates through gpg.format=x509, but requires compatible OpenPGP implementation supporting certificate signing.

What’s the difference between signer and committer identity?

Signatures verify the Signer’s identity, but commits record the Author’s and Committer’s identities separately in the commit headers.

Applications of the signature format

1. Commit Authenticity: Ensures commits come from claimed author/developer
2. Tag Integrity: Provides tamper-proof release versioning
3. Audit Compliance: Maintains verifiable change history for regulatory requirements
4. Two-Person Review: Ensures merged code is verified by both author and reviewer
5. Supply Chain Security: Prevents unauthorized code modifications in deployment pipelines
6. Copyright Assignment: Provides legal attribution and non-repudiation for intellectual property