Pinning¶
Usage snippets name a reference, and there are two honest ways to write one.
--pin sha (default)¶
Resolves to exactly one commit however the tag moves afterwards, with the version alongside so the line stays readable. This is correct everywhere, which is why it is the default.
--pin version¶
Shorter and legible, and equal in integrity to a SHA only where the publishing repository has enabled immutable releases. GitHub then locks a release tag to its commit and forbids reusing the name, even after the release is deleted.
It is a claim about the publisher, not a preference
Choosing `version` for a repository without immutable releases produces
snippets that look pinned and are not. Nothing here can detect the
difference: asking GitHub would put a network call in the middle of a
generator whose whole point is reproducible output.
Set it once, in a configuration file, rather than on every invocation: