doc: add info about tag restriction

Signed-off-by: Frantisek Hrbata <frantisek@hrbata.com>

diff --git a/Documentation/git-mr-tag.txt b/Documentation/git-mr-tag.txt
index 5192e5a73f04e4ba59b7e8ee636956480801022d..9fa84f14f4ea0b4cfc59a528d312966953b4739d 100644 (file)
--- a/Documentation/git-mr-tag.txt
+++ b/Documentation/git-mr-tag.txt
@@ -20,11 +20,11 @@ Allows to attach tag to MR or commits. Each commit is identified by its
 commits are specified, it's used by default. This means you can attach tag
 to each commit, but also to the MR as a whole. Tag name can consist of
 alphanumeric chars only. Convention is to use uppercase letters for MR tags,
-because commit tags can be squashed into the MR commit in 'git-mr-show' if the
-*-s* option is used. This helps to avoid mixing of MR and commit tags.
-If MR is not specified with the *-m* option, 'HEAD' is used by default.
-Note that MR has to be specified along with the commits and commits have to be
-part of the MR.
+because commit tags can be squashed into the MR commit in
+link:git-mr-show.html[git-mr-show(1)] if the *-s* option is used. This helps
+to avoid mixing of MR and commit tags. If MR is not specified with the *-m*
+option, 'HEAD' is used by default. Note that MR has to be specified along
+with the commits and commits have to be part of the MR.
 
 User tags have reference under MR and user namespace
 'refs/mrs/<mr-sha-1>/<user>/tags' and tags are stored separately for each user.
@@ -33,11 +33,16 @@ accordingly. The tip of tags ref always contains the full set of user's tags.
 The raw format can be displayed with
 'git show refs/mrs/<mr-sha-1>/<user>/tags:tags'.
 
+There is one special tag reference 'refs/mrs/<mr-sha-1>/<user>/mr' for each
+MR. It contains basic MR tags, which cannot be changed and can be set
+by the MR author only. The special tags are described in *RESERVED TAGS*
+section.
+
 Each tag can have multiple values set by different users, so each tag value
-is tight with user who set it. This allows 'git-mr-show' to display tag
-values for selected users only. Also different users can use the same tag name
-and assign it different values. Tag is uniquely identified with tag name, value
-and user who set this value.
+is tight with user who set it. This allows link:git-mr-show.html[git-mr-show(1)]
+to display tag values for selected users only. Also different users can use the
+same tag name and assign it different values. Tag is uniquely identified with
+tag name, value and user who set this value.
 
 New tag value can be added with the *-a* option. If tag already exists, it's not
 added. Only unique tags are stored. Removing tag with the *-r* option has to
@@ -71,6 +76,31 @@ OPTIONS
     are removed.
 
 
+RESERVED TAGS
+-------------
+Even though tags are generic, there are two restrictions.
+
+. Basic MR tags created during link:git-mr-create.html[git-mr-create(1)] and
+stored under 'refs/mrs/<mr-sha-1>/<user>/mr'. These tags are reserved and
+cannot be changed. Users are not allowed to add these tag names and
+their correctness is enforced with link:git-mr-update.html[git-mr-update(1)] git
+hook.
+
+* 'M': MR SHA-1
+* 'B': MR base SHA-1
+* 'A': MR author
+* 'C': MR commit list
+* 'CC': MR commit count
+* 'AN': MR author name
+* 'AE': MR author email
+* 'AT': MR author date, UNIX timestamp
+
+. Tag names which can be set and modified by the MR author only.
+
+* 'S': MR subject
+* 'D': MR description
+
+
 EXAMPLES
 --------
 `$ git mr-tag -a -t NOTE -v "This is my MR note"`::