Use Sphinx manpage references where applicable

In docstrings within the git module.

This makes text of the same general form as, e.g.

    git-rev-parse

or

    ``git rev-parse``

or URLs that link directly to a documentation page equivalent to a
manpage or that link to the first section where preceding material
is trivial...

...instead be in the form:

    :manpage:`git-rev-parse(1)`

with variations as appropriate, for example changing

    gitglossary(7)

to

    :manpage:`gitglossary(7)`

and making other changes accordingly, such as adjusting phrasing
and the use of hyphens in a small number of cases.

Together with c5a29a9, which made such references linkify to the'
official online documentation for Git, this makes it so that when
git subcommands are mentioned in docstrings, the Sphinx autodoc
generated documentation in the API Reference page now renders them
as links to the relevant documentation page.

Links to specific sections where it matters or potentially matters
that it goes to that section are not replaced. In particular, links
to specific entries in gitglossary(7) are not replaced. To do this
properly would involve adding a new Sphinx role for it, which would
work well in the rendered documentation but could be unclear when
the documentation is read in docstrings appearing in the code.

Author: EliahKagan

Diff for: git/cmd.py

@@ -901,7 +901,8 @@ def working_dir(self) -> Union[None, PathLike]:
     def version_info(self) -> Tuple[int, ...]:
         """
         :return: Tuple with integers representing the major, minor and additional
-            version numbers as parsed from ``git version``. Up to four fields are used.
+            version numbers as parsed from :manpage:`git-version(1)`. Up to four fields
+            are used.
 
             This value is generated on demand and is cached.
         """
@@ -1038,9 +1039,9 @@ def execute(
             3. Deeper descendants do not receive signals, though they may sometimes
                terminate as a consequence of their parent processes being killed.
             4. `kill_after_timeout` uses ``SIGKILL``, which can have negative side
-               effects on a repository. For example, stale locks in case of ``git gc``
-               could render the repository incapable of accepting changes until the lock
-               is manually removed.
+               effects on a repository. For example, stale locks in case of
+               :manpage:`git-gc(1)` could render the repository incapable of accepting
+               changes until the lock is manually removed.
 
         :param with_stdout:
             If ``True``, default ``True``, we open stdout on the created process.

Diff for: git/config.py

@@ -270,7 +270,7 @@ def get_config_path(config_level: Lit_config_levels) -> str:
 class GitConfigParser(cp.RawConfigParser, metaclass=MetaParserBuilder):
     """Implements specifics required to read git style configuration files.
 
-    This variation behaves much like the ``git config`` command, such that the
+    This variation behaves much like the :manpage:`git-config(1)` command, such that the
     configuration will be read on demand based on the filepath given during
     initialization.
 

Diff for: git/diff.py

@@ -222,8 +222,8 @@ def diff(
             to be read and diffed.
 
         :param kwargs:
-            Additional arguments passed to ``git diff``, such as ``R=True`` to swap both
-            sides of the diff.
+            Additional arguments passed to :manpage:`git-diff(1)`, such as ``R=True`` to
+            swap both sides of the diff.
 
         :return:
             A :class:`DiffIndex` representing the computed diff.
@@ -590,7 +590,7 @@ def _index_from_patch_format(cls, repo: "Repo", proc: Union["Popen", "Git.AutoIn
             The repository we are operating on.
 
         :param proc:
-            ``git diff`` process to read from
+            :manpage:`git-diff(1)` process to read from
             (supports :class:`Git.AutoInterrupt <git.cmd.Git.AutoInterrupt>` wrapper).
 
         :return:

Diff for: git/index/base.py

@@ -225,11 +225,11 @@ def write(
 
         :param ignore_extension_data:
             If ``True``, the TREE type extension data read in the index will not be
-            written to disk. NOTE that no extension data is actually written.
-            Use this if you have altered the index and would like to use
-            ``git write-tree`` afterwards to create a tree representing your written
-            changes. If this data is present in the written index, ``git write-tree``
-            will instead write the stored/cached tree.
+            written to disk. NOTE that no extension data is actually written. Use this
+            if you have altered the index and would like to use
+            :manpage:`git-write-tree(1)` afterwards to create a tree representing your
+            written changes. If this data is present in the written index,
+            :manpage:`git-write-tree(1)` will instead write the stored/cached tree.
             Alternatively, use :meth:`write_tree` to handle this case automatically.
         """
         # Make sure we have our entries read before getting a write lock.
@@ -343,7 +343,7 @@ def from_tree(cls, repo: "Repo", *treeish: Treeish, **kwargs: Any) -> "IndexFile
                tree, tree 3 is the 'other' one.
 
         :param kwargs:
-            Additional arguments passed to ``git read-tree``.
+            Additional arguments passed to :manpage:`git-read-tree(1)`.
 
         :return:
             New :class:`IndexFile` instance. It will point to a temporary index location
@@ -355,9 +355,9 @@ def from_tree(cls, repo: "Repo", *treeish: Treeish, **kwargs: Any) -> "IndexFile
             automatically resolve more cases in a commonly correct manner. Specify
             ``trivial=True`` as a keyword argument to override that.
 
-            As the underlying ``git read-tree`` command takes into account the current
-            index, it will be temporarily moved out of the way to prevent any unexpected
-            interference.
+            As the underlying :manpage:`git-read-tree(1)` command takes into account the
+            current index, it will be temporarily moved out of the way to prevent any
+            unexpected interference.
         """
         if len(treeish) == 0 or len(treeish) > 3:
             raise ValueError("Please specify between 1 and 3 treeish, got %i" % len(treeish))
@@ -470,10 +470,10 @@ def _write_path_to_stdin(
             In that case, it will return ``None``.
 
         :note:
-            There is a bug in git-update-index that prevents it from sending reports
-            just in time. This is why we have a version that tries to read stdout and
-            one which doesn't. In fact, the stdout is not important as the piped-in
-            files are processed anyway and just in time.
+            There is a bug in :manpage:`git-update-index(1)` that prevents it from
+            sending reports just in time. This is why we have a version that tries to
+            read stdout and one which doesn't. In fact, the stdout is not important as
+            the piped-in files are processed anyway and just in time.
 
         :note:
             Newlines are essential here, git's behaviour is somewhat inconsistent on
@@ -782,11 +782,12 @@ def add(
                 directories like ``lib``, which will add all the files within the
                 directory and subdirectories.
 
-                This equals a straight ``git add``.
+                This equals a straight :manpage:`git-add(1)`.
 
                 They are added at stage 0.
 
-            - :class:~`git.objects.blob.Blob` or :class:`~git.objects.submodule.base.Submodule` object
+            - :class:~`git.objects.blob.Blob` or
+              :class:`~git.objects.submodule.base.Submodule` object
 
                 Blobs are added as they are assuming a valid mode is set.
 
@@ -818,8 +819,8 @@ def add(
         :param force:
             **CURRENTLY INEFFECTIVE**
             If ``True``, otherwise ignored or excluded files will be added anyway. As
-            opposed to the ``git add`` command, we enable this flag by default as the
-            API user usually wants the item to be added even though they might be
+            opposed to the :manpage:`git-add(1)` command, we enable this flag by default
+            as the API user usually wants the item to be added even though they might be
             excluded.
 
         :param fprogress:
@@ -850,8 +851,8 @@ def add(
         :param write_extension_data:
             If ``True``, extension data will be written back to the index. This can lead
             to issues in case it is containing the 'TREE' extension, which will cause
-            the ``git commit`` command to write an old tree, instead of a new one
-            representing the now changed index.
+            the :manpage:`git-commit(1)` command to write an old tree, instead of a new
+            one representing the now changed index.
 
             This doesn't matter if you use :meth:`IndexFile.commit`, which ignores the
             'TREE' extension altogether. You should set it to ``True`` if you intend to
@@ -1008,8 +1009,8 @@ def remove(
             uncommitted changes in it.
 
         :param kwargs:
-            Additional keyword arguments to be passed to ``git rm``, such as ``r`` to
-            allow recursive removal.
+            Additional keyword arguments to be passed to :manpage:`git-rm(1)`, such as
+            ``r`` to allow recursive removal.
 
         :return:
             List(path_string, ...) list of repository relative paths that have been
@@ -1058,7 +1059,7 @@ def move(
             skipped.
 
         :param kwargs:
-            Additional arguments you would like to pass to ``git mv``, such as
+            Additional arguments you would like to pass to :manpage:`git-mv(1)`, such as
             ``dry_run`` or ``force``.
 
         :return:
@@ -1224,7 +1225,7 @@ def checkout(
             prior and after a file has been checked out.
 
         :param kwargs:
-            Additional arguments to be passed to ``git checkout-index``.
+            Additional arguments to be passed to :manpage:`git-checkout-index(1)`.
 
         :return:
             Iterable yielding paths to files which have been checked out and are
@@ -1243,8 +1244,8 @@ def checkout(
             The checkout is limited to checking out the files in the index. Files which
             are not in the index anymore and exist in the working tree will not be
             deleted. This behaviour is fundamentally different to ``head.checkout``,
-            i.e. if you want ``git checkout`` like behaviour, use ``head.checkout``
-            instead of ``index.checkout``.
+            i.e. if you want :manpage:`git-checkout(1)`-like behaviour, use
+            ``head.checkout`` instead of ``index.checkout``.
         """
         args = ["--index"]
         if force:
@@ -1416,14 +1417,14 @@ def reset(
             raised.
 
         :param kwargs:
-            Additional keyword arguments passed to ``git reset``.
+            Additional keyword arguments passed to :manpage:`git-reset(1)`.
 
         :note:
             :meth:`IndexFile.reset`, as opposed to
             :meth:`HEAD.reset <git.refs.head.HEAD.reset>`, will not delete any files in
             order to maintain a consistent working tree. Instead, it will just check out
             the files according to their state in the index.
-            If you want ``git reset``-like behaviour, use
+            If you want :manpage:`git-reset(1)`-like behaviour, use
             :meth:`HEAD.reset <git.refs.head.HEAD.reset>` instead.
 
         :return:

Diff for: git/index/typ.py

@@ -130,8 +130,7 @@ def stage(self) -> int:
             * 3 = stage of entries from the 'right' side of the merge
 
         :note:
-            For more information, see:
-            http://www.kernel.org/pub/software/scm/git/docs/git-read-tree.html
+            For more information, see :manpage:`git-read-tree(1)`.
         """
         return (self.flags & CE_STAGEMASK) >> CE_STAGESHIFT
 

Diff for: git/objects/base.py

@@ -45,7 +45,7 @@ class Object(LazyMixin):
     * :class:`Commit <git.objects.commit.Commit>`
     * :class:`TagObject <git.objects.tag.TagObject>`
 
-    See gitglossary(7) on:
+    See :manpage:`gitglossary(7)` on:
 
     * "object": https://git-scm.com/docs/gitglossary#def_object
     * "object type": https://git-scm.com/docs/gitglossary#def_object_type

Diff for: git/objects/blob.py

@@ -19,7 +19,8 @@
 class Blob(base.IndexObject):
     """A Blob encapsulates a git blob object.
 
-    See gitglossary(7) on "blob": https://git-scm.com/docs/gitglossary#def_blob_object
+    See :manpage:`gitglossary(7)` on "blob":
+    https://git-scm.com/docs/gitglossary#def_blob_object
     """
 
     DEFAULT_MIME_TYPE = "text/plain"

Diff for: git/objects/commit.py

@@ -65,7 +65,7 @@
 class Commit(base.Object, TraversableIterableObj, Diffable, Serializable):
     """Wraps a git commit object.
 
-    See gitglossary(7) on "commit object":
+    See :manpage:`gitglossary(7)` on "commit object":
     https://git-scm.com/docs/gitglossary#def_commit_object
 
     :note:
@@ -269,8 +269,9 @@ def count(self, paths: Union[PathLike, Sequence[PathLike]] = "", **kwargs: Any)
             actually containing the paths.
 
         :param kwargs:
-            Additional options to be passed to ``git rev-list``. They must not alter the
-            output style of the command, or parsing will yield incorrect results.
+            Additional options to be passed to :manpage:`git-rev-list(1)`. They must not
+            alter the output style of the command, or parsing will yield incorrect
+            results.
 
         :return:
             An int defining the number of reachable commits
@@ -307,14 +308,14 @@ def iter_items(
             The :class:`~git.repo.base.Repo`.
 
         :param rev:
-            Revision specifier. See git-rev-parse for viable options.
+            Revision specifier. See :manpage:`git-rev-parse(1)` for viable options.
 
         :param paths:
             An optional path or list of paths. If set only :class:`Commit`\s that
             include the path or paths will be considered.
 
         :param kwargs:
-            Optional keyword arguments to ``git rev-list`` where:
+            Optional keyword arguments to :manpage:`git-rev-list(1)` where:
 
             * ``max_count`` is the maximum number of commits to fetch.
             * ``skip`` is the number of commits to skip.
@@ -353,7 +354,7 @@ def iter_parents(self, paths: Union[PathLike, Sequence[PathLike]] = "", **kwargs
             contain at least one of the paths.
 
         :param kwargs:
-            All arguments allowed by ``git rev-list``.
+            All arguments allowed by :manpage:`git-rev-list(1)`.
 
         :return:
             Iterator yielding :class:`Commit` objects which are parents of ``self``
@@ -404,7 +405,7 @@ def trailers_list(self) -> List[Tuple[str, str]]:
         """Get the trailers of the message as a list.
 
         Git messages can contain trailer information that are similar to RFC 822 e-mail
-        headers (see: https://git-scm.com/docs/git-interpret-trailers).
+        headers. See :manpage:`git-interpret-trailers(1)`.
 
         This function calls ``git interpret-trailers --parse`` onto the message to
         extract the trailer information, returns the raw trailer data as a list.
@@ -456,7 +457,7 @@ def trailers_dict(self) -> Dict[str, List[str]]:
         """Get the trailers of the message as a dictionary.
 
         Git messages can contain trailer information that are similar to RFC 822 e-mail
-        headers (see: https://git-scm.com/docs/git-interpret-trailers).
+        headers. See :manpage:`git-interpret-trailers(1)`.
 
         This function calls ``git interpret-trailers --parse`` onto the message to
         extract the trailer information. The key value pairs are stripped of leading and
@@ -499,7 +500,7 @@ def _iter_from_process_or_stream(cls, repo: "Repo", proc_or_stream: Union[Popen,
         from our lighting fast object database.
 
         :param proc:
-            ``git rev-list`` process instance - one sha per line.
+            :manpage:`git-rev-list(1)` process instance - one sha per line.
 
         :return:
             Iterator supplying :class:`Commit` objects
@@ -596,8 +597,8 @@ def create_from_tree(
 
         :note:
             Additional information about the committer and author are taken from the
-            environment or from the git configuration. See git-commit-tree for more
-            information.
+            environment or from the git configuration. See :manpage:`git-commit-tree(1)`
+            for more information.
         """
         if parent_commits is None:
             try:

Diff for: git/objects/submodule/base.py

@@ -342,7 +342,7 @@ def _clone_repo(
             Allow unsafe options to be used, like ``--upload-pack``.
 
         :param kwargs:
-            Additional arguments given to ``git clone``.
+            Additional arguments given to :manpage:`git-clone(1)`.
         """
         module_abspath = cls._module_abspath(repo, path, name)
         module_checkout_path = module_abspath
@@ -463,10 +463,10 @@ def add(
             It will be created as required during the repository initialization.
 
         :param url:
-            git-clone compatible URL, see git-clone reference for more information.
-            If ``None``, the repository is assumed to exist, and the url of the first
-            remote is taken instead. This is useful if you want to make an existing
-            repository a submodule of another one.
+            ``git clone ...``-compatible URL. See :manpage:`git-clone(1)` for more
+            information. If ``None``, the repository is assumed to exist, and the URL of
+            the first remote is taken instead. This is useful if you want to make an
+            existing repository a submodule of another one.
 
         :param branch:
             Name of branch at which the submodule should (later) be checked out. The
@@ -696,7 +696,7 @@ def update(
             its value.
 
         :param clone_multi_options:
-            List of ``git clone`` options.
+            List of :manpage:`git-clone(1)` options.
             Please see :meth:`Repo.clone <git.repo.base.Repo.clone>` for details.
             They only take effect with the `init` option.
 

Diff for: git/objects/tag.py

@@ -37,7 +37,7 @@ class TagObject(base.Object):
     """Annotated (i.e. non-lightweight) tag carrying additional information about an
     object we are pointing to.
 
-    See gitglossary(7) on "tag object":
+    See :manpage:`gitglossary(7)` on "tag object":
     https://git-scm.com/docs/gitglossary#def_tag_object
     """
 

Diff for: git/objects/tree.py

@@ -168,7 +168,7 @@ class Tree(IndexObject, git_diff.Diffable, util.Traversable, util.Serializable):
     R"""Tree objects represent an ordered list of :class:`~git.objects.blob.Blob`\s and
     other :class:`Tree`\s.
 
-    See gitglossary(7) on "tree object":
+    See :manpage:`gitglossary(7)` on "tree object":
     https://git-scm.com/docs/gitglossary#def_tree_object
 
     Subscripting is supported, as with a list or dict:

Diff for: git/refs/head.py

@@ -89,7 +89,7 @@ def reset(
             that are to be reset. This allows to partially reset individual files.
 
         :param kwargs:
-            Additional arguments passed to ``git reset``.
+            Additional arguments passed to :manpage:`git-reset(1)`.
 
         :return:
             self

Diff for: git/refs/symbolic.py

@@ -173,8 +173,7 @@ def dereference_recursive(cls, repo: "Repo", ref_path: Union[PathLike, None]) ->
     def _check_ref_name_valid(ref_path: PathLike) -> None:
         """Check a ref name for validity.
 
-        This is based on the rules described in:
-        https://git-scm.com/docs/git-check-ref-format/#_description
+        This is based on the rules described in :manpage:`git-check-ref-format(1)`.
         """
         previous: Union[str, None] = None
         one_before_previous: Union[str, None] = None

Diff for: git/refs/tag.py

@@ -124,7 +124,7 @@ def create(
             If ``True``, force creation of a tag even though that tag already exists.
 
         :param kwargs:
-            Additional keyword arguments to be passed to ``git tag``.
+            Additional keyword arguments to be passed to :manpage:`git-tag(1)`.
 
         :return:
             A new :class:`TagReference`.