doc: add git-mr-comment-list.txt

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

diff --git a/Documentation/git-mr-comment-list.txt b/Documentation/git-mr-comment-list.txt
new file mode 100644 (file)
index 0000000..057e387
--- /dev/null
+++ b/Documentation/git-mr-comment-list.txt
@@ -0,0 +1,112 @@
+GIT-MR-COMMENT-LIST(1)
+======================
+:doctype: manpage
+
+
+NAME
+----
+git-mr-comment-list - List comments for MRs
+
+
+SYNOPSIS
+--------
+*git-mr-comment-list* ['OPTIONS'] ['MR' ['MR' ...]]
+
+
+DESCRIPTION
+-----------
+This is one of three basic commands for 'MR' review, along with
+link:git-mr-comment-show.html[git-mr-comment-show(1)] and
+link:git-mr-reply.html[git-mr-reply(1)]. It lists comments for specific 'MRs' or
+all comments if the *-A* option is used. The output format can be adjusted
+with *--fmt*.
+
+The listed comments can be restricted with the *-n* option to display unread
+comments only. Since comments are stored as git commit messages, other filtering
+is possible by using 'git-log' features like *--grep*, *--before* or *--after*.
+
+
+OPTIONS
+-------
+*-A, --all*::
+    List comments for all MRs. MRs entered as positional arguments or on stdin
+    are ignored.
+
+*-, --stdin*::
+    List comments for MRs from stdin. MRs entered as positional arguments are
+    ignored.
+
+*--fmt* 'FMT'::
+    Python's formatted string for comments. Default value is
+    `"{f:2.2} {m:.16} {c:.16} {s:70.70} {n:20.20} {d}"`.
+    Please see *FORMAT* and *RESOURCES* sections for more details.
+
+*--grep* 'PATTERN'::
+    Limit the comments output to ones with message that matches the specified
+    'PATTERN'. Can be used multiple times.
+
+*-E, --extended-regexp*::
+    Use extended regular expressions instead of the default basic regular expressions.
+
+*--all-match*::
+    Limit the comments output to ones that match all given *--grep*.
+
+*-i, --regexp-ignore-case*::
+    Match the regular expression limiting patterns without regard to letter case.
+
+*--after* 'DATE'::
+    Limit the comments output to ones more recent than a specific date.
+
+*--before* 'DATE'::
+    Limit the comments output to ones older than a specific date.
+
+*--author* 'PATTERN'::
+    Limit the comments output to ones that were created by user matching PATTERN. Can be used multiple times.
+
+*--to* 'PATTERN'::
+    Limit the comments output to ones that were addressed to user matching PATTERN. Can be used multiple times.
+
+*-r, --read-revs* 'FILE'::
+    Read revs for previously read comments from 'FILE'
+    (default: $HOME/.gimrr/comment.revs). This info is used for reporting
+    unread comments.
+
+*-n, --new-only*::
+    List new comments only. This omits comments read by the *-r* option.
+
+
+FORMAT
+------
+* 'f': 'N' flag for unread comment
+* 'c': comment SHA-1
+* 's': comment subject
+* 'n': comment author name
+* 'e': comment author email
+* 'd': comment author date
+* 'm': SHA-1 of MR to which the comment belongs to
+
+EXAMPLES
+--------
+`$ git mr-comment-list`::
+  List comments for current(HEAD) MR.
+
+`$ git mr-comment-list -A`::
+  List comments all comments for all MRs.
+
+`$ git mr-comment-list -A -n`::
+  List only all new comments for all MRs.
+
+`$ git mr-comment-list -A -n`::
+  List only all new comments for all MRs.
+
+`$ git mr-comment-list --to 'john@doe.com' --author 'john@smith.com' --grep '^BUG' --after 'Sat Dec 19 13:10:42 2020 +0100'`::
+  List only comments to 'john@doe.com' from 'john@smith.com' which contain like starting with 'BUG' and were sent after 'Sat Dec 19 13:10:42 2020 +0100'.
+
+
+SEE ALSO
+--------
+link:git-mr.html[git-mr(1)]
+
+RESOURCES
+---------
+Python's format string syntax: <https://docs.python.org/3.2/library/string.html#formatstrings>