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

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.

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.
 

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:

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:

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
 

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

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"

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:

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.
 

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
     """
 

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:

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

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

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`.

git/remote.py

@@ -333,8 +333,8 @@ class FetchInfo(IterableObj):
 
     @classmethod
     def refresh(cls) -> Literal[True]:
-        """Update information about which ``git fetch`` flags are supported by the git
-        executable being used.
+        """Update information about which :manpage:`git-fetch(1)` flags are supported
+        by the git executable being used.
 
         Called by the :func:`git.refresh` function in the top level ``__init__``.
         """
@@ -1015,13 +1015,13 @@ def fetch(
             "grab the master branch head from the $URL and store it as my origin
             branch head". And ``git push $URL refs/heads/master:refs/heads/to-upstream``
             means "publish my master branch head as to-upstream branch at $URL".
-            See also git-push(1).
+            See also :manpage:`git-push(1)`.
 
-            Taken from the git manual, gitglossary(7).
+            Taken from the git manual, :manpage:`gitglossary(7)`.
 
-            Fetch supports multiple refspecs (as the underlying git-fetch does) -
-            supplying a list rather than a string for 'refspec' will make use of this
-            facility.
+            Fetch supports multiple refspecs (as the underlying :manpage:`git-fetch(1)`
+            does) - supplying a list rather than a string for 'refspec' will make use of
+            this facility.
 
         :param progress:
             See the :meth:`push` method.
@@ -1040,7 +1040,7 @@ def fetch(
             Allow unsafe options to be used, like ``--upload-pack``.
 
         :param kwargs:
-            Additional arguments to be passed to ``git fetch``.
+            Additional arguments to be passed to :manpage:`git-fetch(1)`.
 
         :return:
             IterableList(FetchInfo, ...) list of :class:`FetchInfo` instances providing
@@ -1104,7 +1104,7 @@ def pull(
             Allow unsafe options to be used, like ``--upload-pack``.
 
         :param kwargs:
-            Additional arguments to be passed to ``git pull``.
+            Additional arguments to be passed to :manpage:`git-pull(1)`.
 
         :return:
             Please see :meth:`fetch` method.
@@ -1170,7 +1170,7 @@ def push(
             Allow unsafe options to be used, like ``--receive-pack``.
 
         :param kwargs:
-            Additional arguments to be passed to ``git push``.
+            Additional arguments to be passed to :manpage:`git-push(1)`.
 
         :return:
             A :class:`PushInfoList` object, where each list member represents an

git/repo/base.py

@@ -149,7 +149,7 @@ class Repo:
         "--config",
         "-c",
     ]
-    """Options to ``git clone`` that allow arbitrary commands to be executed.
+    """Options to :manpage:`git-clone(1)` that allow arbitrary commands to be executed.
 
     The ``--upload-pack``/``-u`` option allows users to execute arbitrary commands
     directly:
@@ -572,7 +572,7 @@ def delete_head(self, *heads: "Union[str, Head]", **kwargs: Any) -> None:
         """Delete the given heads.
 
         :param kwargs:
-            Additional keyword arguments to be passed to ``git branch``.
+            Additional keyword arguments to be passed to :manpage:`git-branch(1)`.
         """
         return Head.delete(self, *heads, **kwargs)
 
@@ -700,7 +700,7 @@ def commit(self, rev: Union[str, Commit_ish, None] = None) -> Commit:
         """The :class:`~git.objects.commit.Commit` object for the specified revision.
 
         :param rev:
-            Revision specifier, see ``git rev-parse`` for viable options.
+            Revision specifier, see :manpage:`git-rev-parse(1)` for viable options.
 
         :return:
             :class:`~git.objects.commit.Commit`
@@ -749,15 +749,15 @@ def iter_commits(
         history of a given ref/commit.
 
         :param rev:
-            Revision specifier, see ``git rev-parse`` for viable options.
+            Revision specifier, see :manpage:`git-rev-parse(1)` for viable options.
             If ``None``, the active branch will be used.
 
         :param paths:
             An optional path or a list of paths. If set, only commits that include the
             path or paths will be returned.
 
         :param kwargs:
-            Arguments to be passed to ``git rev-list``.
+            Arguments to be passed to :manpage:`git-rev-list(1)`.
             Common ones are ``max_count`` and ``skip``.
 
         :note:
@@ -930,8 +930,8 @@ def is_dirty(
         """
         :return:
             ``True`` if the repository is considered dirty. By default it will react
-            like a git-status without untracked files, hence it is dirty if the index or
-            the working copy have changes.
+            like a :manpage:`git-status(1)` without untracked files, hence it is dirty
+            if the index or the working copy have changes.
         """
         if self._bare:
             # Bare repositories with no associated working directory are
@@ -1001,7 +1001,7 @@ def _get_untracked_files(self, *args: Any, **kwargs: Any) -> List[str]:
     def ignored(self, *paths: PathLike) -> List[str]:
         """Checks if paths are ignored via ``.gitignore``.
 
-        This does so using the ``git check-ignore`` method.
+        This does so using the :manpage:`git-check-ignore(1)` method.
 
         :param paths:
             List of paths to check whether they are ignored or not.
@@ -1044,7 +1044,7 @@ def blame_incremental(self, rev: str | HEAD | None, file: str, **kwargs: Any) ->
         :param rev:
             Revision specifier. If ``None``, the blame will include all the latest
             uncommitted changes. Otherwise, anything successfully parsed by
-            ``git rev-parse`` is a valid option.
+            :manpage:`git-rev-parse(1)` is a valid option.
 
         :return:
             Lazy iterator of :class:`BlameEntry` tuples, where the commit indicates the
@@ -1140,7 +1140,7 @@ def blame(
         :param rev:
             Revision specifier. If ``None``, the blame will include all the latest
             uncommitted changes. Otherwise, anything successfully parsed by
-            ``git rev-parse`` is a valid option.
+            :manpage:`git-rev-parse(1)` is a valid option.
 
         :return:
             list: [git.Commit, list: [<line>]]
@@ -1312,7 +1312,8 @@ def init(
             environment variables.
 
         :param kwargs:
-            Keyword arguments serving as additional options to the ``git init`` command.
+            Keyword arguments serving as additional options to the
+            :manpage:`git-init(1)` command.
 
         :return:
             :class:`Repo` (the newly created repo)
@@ -1432,7 +1433,8 @@ def clone(
             See :meth:`Remote.push <git.remote.Remote.push>`.
 
         :param multi_options:
-            A list of ``git clone`` options that can be provided multiple times.
+            A list of :manpage:`git-clone(1)` options that can be provided multiple
+            times.
 
             One option per list item which is passed exactly as specified to clone.
             For example::
@@ -1453,7 +1455,8 @@ def clone(
         :param kwargs:
             * ``odbt`` = ObjectDatabase Type, allowing to determine the object database
               implementation used by the returned :class:`Repo` instance.
-            * All remaining keyword arguments are given to the ``git clone`` command.
+            * All remaining keyword arguments are given to the :manpage:`git-clone(1)`
+              command.
 
         :return:
             :class:`Repo` (the newly cloned repo)
@@ -1551,7 +1554,7 @@ def archive(
             The optional prefix to prepend to each filename in the archive.
 
         :param kwargs:
-            Additional arguments passed to ``git archive``:
+            Additional arguments passed to :manpage:`git-archive(1)`:
 
             * Use the ``format`` argument to define the kind of format. Use specialized
               ostreams to write any format supported by Python.

git/repo/fun.py

@@ -226,7 +226,7 @@ def to_commit(obj: Object) -> "Commit":
 
 
 def rev_parse(repo: "Repo", rev: str) -> AnyGitObject:
-    """Parse a revision string. Like ``git rev-parse``.
+    """Parse a revision string. Like :manpage:`git-rev-parse(1)`.
 
     :return:
         `~git.objects.base.Object` at the given revision.
@@ -239,8 +239,8 @@ def rev_parse(repo: "Repo", rev: str) -> AnyGitObject:
         * :class:`Blob <git.objects.blob.Blob>`
 
     :param rev:
-        ``git rev-parse``-compatible revision specification as string. Please see
-        http://www.kernel.org/pub/software/scm/git/docs/git-rev-parse.html for details.
+        :manpage:`git-rev-parse(1)`-compatible revision specification as string.
+        Please see :manpage:`git-rev-parse(1)` for details.
 
     :raise gitdb.exc.BadObject:
         If the given revision could not be found.

git/types.py

@@ -57,7 +57,8 @@
 * :class:`Commit <git.objects.commit.Commit>`
 * :class:`TagObject <git.objects.tag.TagObject>`
 
-Those GitPython classes represent the four git object types, per gitglossary(7):
+Those GitPython classes represent the four git object types, per
+:manpage:`gitglossary(7)`:
 
 * "blob": https://git-scm.com/docs/gitglossary#def_blob_object
 * "tree object": https://git-scm.com/docs/gitglossary#def_tree_object
@@ -76,7 +77,8 @@
 Tree_ish = Union["Commit", "Tree", "TagObject"]
 """Union of :class:`~git.objects.base.Object`-based types that are sometimes tree-ish.
 
-See gitglossary(7) on "tree-ish": https://git-scm.com/docs/gitglossary#def_tree-ish
+See :manpage:`gitglossary(7)` on "tree-ish":
+https://git-scm.com/docs/gitglossary#def_tree-ish
 
 :note:
     :class:`~git.objects.tree.Tree` and :class:`~git.objects.commit.Commit` are the
@@ -94,7 +96,8 @@
 Commit_ish = Union["Commit", "TagObject"]
 """Union of :class:`~git.objects.base.Object`-based types that are sometimes commit-ish.
 
-See gitglossary(7) on "commit-ish": https://git-scm.com/docs/gitglossary#def_commit-ish
+See :manpage:`gitglossary(7)` on "commit-ish":
+https://git-scm.com/docs/gitglossary#def_commit-ish
 
 :note:
     :class:`~git.objects.commit.Commit` is the only class whose instances are all
@@ -117,8 +120,9 @@
 values in :class:`~git.objects.base.Object` subclasses that represent git objects. These
 literals therefore correspond to the types in the :class:`AnyGitObject` union.
 
-These are the same strings git itself uses to identify its four object types. See
-gitglossary(7) on "object type": https://git-scm.com/docs/gitglossary#def_object_type
+These are the same strings git itself uses to identify its four object types.
+See :manpage:`gitglossary(7)` on "object type":
+https://git-scm.com/docs/gitglossary#def_object_type
 """
 
 Lit_commit_ish = Literal["commit", "tag"]

git/util.py

@@ -558,8 +558,8 @@ def remove_password_if_present(cmdline: Sequence[str]) -> List[str]:
 
 class RemoteProgress:
     """Handler providing an interface to parse progress information emitted by
-    ``git push`` and ``git fetch`` and to dispatch callbacks allowing subclasses to
-    react to the progress."""
+    :manpage:`git-push(1)` and :manpage:`git-fetch(1)` and to dispatch callbacks
+    allowing subclasses to react to the progress."""
 
     _num_op_codes: int = 9
     (
@@ -595,8 +595,8 @@ def __init__(self) -> None:
         self.other_lines: List[str] = []
 
     def _parse_progress_line(self, line: AnyStr) -> None:
-        """Parse progress information from the given line as retrieved by ``git push``
-        or ``git fetch``.
+        """Parse progress information from the given line as retrieved by
+        :manpage:`git-push(1)` or :manpage:`git-fetch(1)`.
 
         - Lines that do not contain progress info are stored in :attr:`other_lines`.
         - Lines that seem to contain an error (i.e. start with ``error:`` or ``fatal:``)
@@ -922,7 +922,8 @@ def __init__(self, total: Total_TD, files: Dict[PathLike, Files_TD]) -> None:
 
     @classmethod
     def _list_from_string(cls, repo: "Repo", text: str) -> "Stats":
-        """Create a :class:`Stats` object from output retrieved by ``git diff``.
+        """Create a :class:`Stats` object from output retrieved by
+        :manpage:`git-diff(1)`.
 
         :return:
             :class:`git.Stats`