> and there’s really good man page documentation now
Well, my pet peeve has always been git-tag. When I discuss about technical documentation, I actually use man git-tag as a reference of what NOT to do.
The summary (called NAME in manpages):
git-tag - Create, list, delete or verify a tag object signed with GPG
... which might make sense but is already confusing to a beginner because of its reference to GPG (are all tags signed with GPG?).
But DESCRIPTION is actually the best:
Add a tag reference in refs/tags/, unless -d/-l/-v is given to delete, list or verify tags.
Unless -f is given, the named tag must not yet exist.
If one of -a, -s, or -u <keyid> is passed, the command creates a tag object, and requires a tag message.
Unless -m <msg> or -F <file> is given, an editor is started for the user to type in the tag message.
If -m <msg> or -F <file> is given and -a, -s, and -u <keyid> are absent, -a is implied.
Otherwise, a tag reference that points directly at the given object (i.e., a lightweight tag) is created.
A GnuPG signed tag object will be created when -s or -u <keyid> is used. When -u <keyid> is not used, the
committer identity for the current user is used to find the GnuPG key for signing. The configuration
variable gpg.program is used to specify custom GnuPG binary.
[... spoiler: it doesn't get any better]
So this should be a description that makes beginners understand git-tag.
Instead, it is a sequence of unrelated sentences that merely describes functionalities in response to command line arguments, in a very convoluted way (I think "If -m <msg> or -F <file> is given and -a, -s, and -u <keyid> are absent, -a is implied" is a little gem).
This is how I would write it:
Create, view, and delete tags.
By default, it creates a new “lightweight” tag, which is simple a reference to the current commit (eg: “git tag v1.2”). If you specify “-a”, a “annotated” tag is created instead; an annotated tag is still a reference to the current commit, but also remembers the date in which it was created, who created it, and optionally saves a message associated to the tag (like a “commit” message for the tag).
Annotated tags can also be cryptographically signed with GnuPG, using “-s” instead of “-a”.
You can also tag a commit which is not the current head by simply specifying it on the command line (eg: “git tag v1.2 abcde1234”).
Use “git tag -l” to view the list of all tags.
Use “git tag -d” to delete a tag.
So I think git still has a long way to go with documentation.