merge(third_party/git): Merge squashed git subtree at v2.23.0 r/373

Merge commit '1b593e1ea4d2af0f6444d9a7788d5d99abd6fde5' as 'third_party/git'

1 files changed, 387 insertions, 0 deletions

diff --git a/third_party/git/Documentation/git-tag.txt b/third_party/git/Documentation/git-tag.txt
new file mode 100644
index 0000000000..2e5599a67f
--- /dev/null
+++ b/third_party/git/Documentation/git-tag.txt
@@ -0,0 +1,387 @@
+git-tag(1)
+==========
+
+NAME
+----
+git-tag - Create, list, delete or verify a tag object signed with GPG
+
+
+SYNOPSIS
+--------
+[verse]
+'git tag' [-a | -s | -u <keyid>] [-f] [-m <msg> | -F <file>] [-e]
+	<tagname> [<commit> | <object>]
+'git tag' -d <tagname>...
+'git tag' [-n[<num>]] -l [--contains <commit>] [--no-contains <commit>]
+	[--points-at <object>] [--column[=<options>] | --no-column]
+	[--create-reflog] [--sort=<key>] [--format=<format>]
+	[--[no-]merged [<commit>]] [<pattern>...]
+'git tag' -v [--format=<format>] <tagname>...
+
+DESCRIPTION
+-----------
+
+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.
+
+Tag objects (created with `-a`, `-s`, or `-u`) are called "annotated"
+tags; they contain a creation date, the tagger name and e-mail, a
+tagging message, and an optional GnuPG signature. 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.
+
+
+OPTIONS
+-------
+-a::
+--annotate::
+	Make an unsigned, annotated tag object
+
+-s::
+--sign::
+	Make a GPG-signed tag, using the default e-mail address's key.
+	The default behavior of tag GPG-signing is controlled by `tag.gpgSign`
+	configuration variable if it exists, or disabled oder otherwise.
+	See linkgit:git-config[1].
+
+--no-sign::
+	Override `tag.gpgSign` configuration variable that is
+	set to force each and every tag to be signed.
+
+-u <keyid>::
+--local-user=<keyid>::
+	Make a GPG-signed tag, using the given key.
+
+-f::
+--force::
+	Replace an existing tag with the given name (instead of failing)
+
+-d::
+--delete::
+	Delete existing tags with the given names.
+
+-v::
+--verify::
+	Verify the GPG signature of the given tag names.
+
+-n<num>::
+	<num> specifies how many lines from the annotation, if any,
+	are printed when using -l. Implies `--list`.
++
+The default is not to print any annotation lines.
+If no number is given to `-n`, only the first line is printed.
+If the tag is not annotated, the commit message is displayed instead.
+
+-l::
+--list::
+	List tags. With optional `<pattern>...`, e.g. `git tag --list
+	'v-*'`, list only the tags that match the pattern(s).
++
+Running "git tag" without arguments also lists all tags. The pattern
+is a shell wildcard (i.e., matched using fnmatch(3)). Multiple
+patterns may be given; if any of them matches, the tag is shown.
++
+This option is implicitly supplied if any other list-like option such
+as `--contains` is provided. See the documentation for each of those
+options for details.
+
+--sort=<key>::
+	Sort based on the key given.  Prefix `-` to sort in
+	descending order of the value. You may use the --sort=<key> option
+	multiple times, in which case the last key becomes the primary
+	key. Also supports "version:refname" or "v:refname" (tag
+	names are treated as versions). The "version:refname" sort
+	order can also be affected by the "versionsort.suffix"
+	configuration variable.
+	The keys supported are the same as those in `git for-each-ref`.
+	Sort order defaults to the value configured for the `tag.sort`
+	variable if it exists, or lexicographic order otherwise. See
+	linkgit:git-config[1].
+
+--color[=<when>]::
+	Respect any colors specified in the `--format` option. The
+	`<when>` field must be one of `always`, `never`, or `auto` (if
+	`<when>` is absent, behave as if `always` was given).
+
+-i::
+--ignore-case::
+	Sorting and filtering tags are case insensitive.
+
+--column[=<options>]::
+--no-column::
+	Display tag listing in columns. See configuration variable
+	column.tag for option syntax.`--column` and `--no-column`
+	without options are equivalent to 'always' and 'never' respectively.
++
+This option is only applicable when listing tags without annotation lines.
+
+--contains [<commit>]::
+	Only list tags which contain the specified commit (HEAD if not
+	specified). Implies `--list`.
+
+--no-contains [<commit>]::
+	Only list tags which don't contain the specified commit (HEAD if
+	not specified). Implies `--list`.
+
+--merged [<commit>]::
+	Only list tags whose commits are reachable from the specified
+	commit (`HEAD` if not specified), incompatible with `--no-merged`.
+
+--no-merged [<commit>]::
+	Only list tags whose commits are not reachable from the specified
+	commit (`HEAD` if not specified), incompatible with `--merged`.
+
+--points-at <object>::
+	Only list tags of the given object (HEAD if not
+	specified). Implies `--list`.
+
+-m <msg>::
+--message=<msg>::
+	Use the given tag message (instead of prompting).
+	If multiple `-m` options are given, their values are
+	concatenated as separate paragraphs.
+	Implies `-a` if none of `-a`, `-s`, or `-u <keyid>`
+	is given.
+
+-F <file>::
+--file=<file>::
+	Take the tag message from the given file.  Use '-' to
+	read the message from the standard input.
+	Implies `-a` if none of `-a`, `-s`, or `-u <keyid>`
+	is given.
+
+-e::
+--edit::
+	The message taken from file with `-F` and command line with
+	`-m` are usually used as the tag message unmodified.
+	This option lets you further edit the message taken from these sources.
+
+--cleanup=<mode>::
+	This option sets how the tag message is cleaned up.
+	The  '<mode>' can be one of 'verbatim', 'whitespace' and 'strip'.  The
+	'strip' mode is default. The 'verbatim' mode does not change message at
+	all, 'whitespace' removes just leading/trailing whitespace lines and
+	'strip' removes both whitespace and commentary.
+
+--create-reflog::
+	Create a reflog for the tag. To globally enable reflogs for tags, see
+	`core.logAllRefUpdates` in linkgit:git-config[1].
+	The negated form `--no-create-reflog` only overrides an earlier
+	`--create-reflog`, but currently does not negate the setting of
+	`core.logAllRefUpdates`.
+
+--format=<format>::
+	A string that interpolates `%(fieldname)` from a tag ref being shown
+	and the object it points at.  The format is the same as
+	that of linkgit:git-for-each-ref[1].  When unspecified,
+	defaults to `%(refname:strip=2)`.
+
+<tagname>::
+	The name of the tag to create, delete, or describe.
+	The new tag name must pass all checks defined by
+	linkgit:git-check-ref-format[1].  Some of these checks
+	may restrict the characters allowed in a tag name.
+
+<commit>::
+<object>::
+	The object that the new tag will refer to, usually a commit.
+	Defaults to HEAD.
+
+CONFIGURATION
+-------------
+By default, 'git tag' in sign-with-default mode (-s) will use your
+committer identity (of the form `Your Name <your@email.address>`) to
+find a key.  If you want to use a different default key, you can specify
+it in the repository configuration as follows:
+
+-------------------------------------
+[user]
+    signingKey = <gpg-keyid>
+-------------------------------------
+
+`pager.tag` is only respected when listing tags, i.e., when `-l` is
+used or implied. The default is to use a pager.
+See linkgit:git-config[1].
+
+DISCUSSION
+----------
+
+On Re-tagging
+~~~~~~~~~~~~~
+
+What should you do when you tag a wrong commit and you would
+want to re-tag?
+
+If you never pushed anything out, just re-tag it. Use "-f" to
+replace the old one. And you're done.
+
+But if you have pushed things out (or others could just read
+your repository directly), then others will have already seen
+the old tag. In that case you can do one of two things:
+
+. The sane thing.
+  Just admit you screwed up, and use a different name. Others have
+  already seen one tag-name, and if you keep the same name, you
+  may be in the situation that two people both have "version X",
+  but they actually have 'different' "X"'s.  So just call it "X.1"
+  and be done with it.
+
+. The insane thing.
+  You really want to call the new version "X" too, 'even though'
+  others have already seen the old one. So just use 'git tag -f'
+  again, as if you hadn't already published the old one.
+
+However, Git does *not* (and it should not) change tags behind
+users back. So if somebody already got the old tag, doing a
+'git pull' on your tree shouldn't just make them overwrite the old
+one.
+
+If somebody got a release tag from you, you cannot just change
+the tag for them by updating your own one. This is a big
+security issue, in that people MUST be able to trust their
+tag-names.  If you really want to do the insane thing, you need
+to just fess up to it, and tell people that you messed up. You
+can do that by making a very public announcement saying:
+
+------------
+Ok, I messed up, and I pushed out an earlier version tagged as X. I
+then fixed something, and retagged the *fixed* tree as X again.
+
+If you got the wrong tag, and want the new one, please delete
+the old one and fetch the new one by doing:
+
+	git tag -d X
+	git fetch origin tag X
+
+to get my updated tag.
+
+You can test which tag you have by doing
+
+	git rev-parse X
+
+which should return 0123456789abcdef.. if you have the new version.
+
+Sorry for the inconvenience.
+------------
+
+Does this seem a bit complicated?  It *should* be. There is no
+way that it would be correct to just "fix" it automatically.
+People need to know that their tags might have been changed.
+
+
+On Automatic following
+~~~~~~~~~~~~~~~~~~~~~~
+
+If you are following somebody else's tree, you are most likely
+using remote-tracking branches (eg. `refs/remotes/origin/master`).
+You usually want the tags from the other end.
+
+On the other hand, if you are fetching because you would want a
+one-shot merge from somebody else, you typically do not want to
+get tags from there.  This happens more often for people near
+the toplevel but not limited to them.  Mere mortals when pulling
+from each other do not necessarily want to automatically get
+private anchor point tags from the other person.
+
+Often, "please pull" messages on the mailing list just provide
+two pieces of information: a repo URL and a branch name; this
+is designed to be easily cut&pasted at the end of a 'git fetch'
+command line:
+
+------------
+Linus, please pull from
+
+	git://git..../proj.git master
+
+to get the following updates...
+------------
+
+becomes:
+
+------------
+$ git pull git://git..../proj.git master
+------------
+
+In such a case, you do not want to automatically follow the other
+person's tags.
+
+One important aspect of Git is its distributed nature, which
+largely means there is no inherent "upstream" or
+"downstream" in the system.  On the face of it, the above
+example might seem to indicate that the tag namespace is owned
+by the upper echelon of people and that tags only flow downwards, but
+that is not the case.  It only shows that the usage pattern
+determines who are interested in whose tags.
+
+A one-shot pull is a sign that a commit history is now crossing
+the boundary between one circle of people (e.g. "people who are
+primarily interested in the networking part of the kernel") who may
+have their own set of tags (e.g. "this is the third release
+candidate from the networking group to be proposed for general
+consumption with 2.6.21 release") to another circle of people
+(e.g. "people who integrate various subsystem improvements").
+The latter are usually not interested in the detailed tags used
+internally in the former group (that is what "internal" means).
+That is why it is desirable not to follow tags automatically in
+this case.
+
+It may well be that among networking people, they may want to
+exchange the tags internal to their group, but in that workflow
+they are most likely tracking each other's progress by
+having remote-tracking branches.  Again, the heuristic to automatically
+follow such tags is a good thing.
+
+
+On Backdating Tags
+~~~~~~~~~~~~~~~~~~
+
+If you have imported some changes from another VCS and would like
+to add tags for major releases of your work, it is useful to be able
+to specify the date to embed inside of the tag object; such data in
+the tag object affects, for example, the ordering of tags in the
+gitweb interface.
+
+To set the date used in future tag objects, set the environment
+variable GIT_COMMITTER_DATE (see the later discussion of possible
+values; the most common form is "YYYY-MM-DD HH:MM").
+
+For example:
+
+------------
+$ GIT_COMMITTER_DATE="2006-10-02 10:31" git tag -s v1.0.1
+------------
+
+include::date-formats.txt[]
+
+SEE ALSO
+--------
+linkgit:git-check-ref-format[1].
+linkgit:git-config[1].
+
+GIT
+---
+Part of the linkgit:git[1] suite