From: Daniele Segato Date: Mon, 29 Jul 2013 18:02:07 GMT Subject: Re: [PATCHv3] git-tag man: when to use lightweight or annotated tags Message-ID: <51F6AE1F.7080607@gmail.com> In-Reply-To: <20130726193643.GH14690@google.com> On 07/26/2013 09:36 PM, Jonathan Nieder wrote: > Eventually the description section should probably be tweaked to start > by explaining what the command is actually for. ;-) Elaborating from this suggestion you gave me I tried to rewrite/rearrange the description moving things around a little. Here's what I've come out with, what do you think about it? DESCRIPTION ----------- A tag is a non-mutable reference name (in `refs/tags/`) to an object (usually a commit). If one of `-d/-l/-v` options is given the command will delete, list or verify tags. If one of `-a`, `-s`, or `-u ` is passed, the command creates both the reference and a 'tag' object containing a creation date, the tagger name and e-mail, a tag message and an optional GnuPG signature. Unless `-m ` or `-F ` is given, an editor is started for the user to type in the tag message. Otherwise just a tag reference for the SHA-1 object name of the commit object is created (i.e. a lightweight tag). Unless `-f` is given, the named tag must not yet exist. If `-m ` or `-F ` is given and `-a`, `-s`, and `-u ` are absent, `-a` is implied. A GnuPG signed tag object will be created when `-s` or `-u ` is used. When `-u ` 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. Tag objects (created with `-a`, `s`, or `-u`) are called "annotated" tags; whereas a "lightweight" tag is simply a name for an object (usually a commit object). Annotated tags are meant for release while lightweight tags are meant for private or temporary object labels. For this reason, some git commands for naming objects (like `git describe`) will ignore lightweight tags by default. -- Cheers, Daniele Segato