From 0969db92133e7562038275086ae560bda5b9d6e4 Mon Sep 17 00:00:00 2001 From: Eliah Kagan Date: Fri, 15 Mar 2024 12:30:22 -0400 Subject: [PATCH 01/10] Put Sphinx conf.py in the same style as other code This is mostly a change to comments. --- doc/source/conf.py | 87 ++++++++++++++++++++++------------------------ 1 file changed, 42 insertions(+), 45 deletions(-) diff --git a/doc/source/conf.py b/doc/source/conf.py index 9c22ca06a..e25c1e5dc 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -3,29 +3,28 @@ # # This file is execfile()d with the current directory set to its containing dir. # -# The contents of this file are pickled, so don't put values in the namespace -# that aren't pickleable (module imports are okay, they're removed automatically). +# The contents of this file are pickled, so don't put values in the namespace that +# aren't pickleable (module imports are okay, they're removed automatically). # -# Note that not all possible configuration values are present in this -# autogenerated file. +# Note that not all possible configuration values are present in this autogenerated +# file. # -# All configuration values have a default; values that are commented out -# serve to show the default. +# All configuration values have a default; values that are commented out serve to show +# the default. -import sys import os +import sys -# If your extensions are in another directory, add it here. If the directory -# is relative to the documentation root, use os.path.abspath to make it -# absolute, like shown here. +# If your extensions are in another directory, add it here. If the directory is relative +# to the documentation root, use os.path.abspath to make it absolute, like shown here. # sys.path.append(os.path.abspath('.')) sys.path.insert(0, os.path.abspath("../..")) # General configuration # --------------------- -# Add any Sphinx extension module names here, as strings. They can be extensions -# coming with Sphinx (named 'sphinx.ext.*') or your custom ones. +# Add any Sphinx extension module names here, as strings. They can be extensions coming +# with Sphinx (named 'sphinx.ext.*') or your custom ones. extensions = ["sphinx.ext.autodoc", "sphinx.ext.doctest"] # Add any paths that contain templates here, relative to this directory. @@ -44,9 +43,8 @@ project = "GitPython" copyright = "Copyright (C) 2008, 2009 Michael Trier and contributors, 2010-2015 Sebastian Thiel" -# The version info for the project you're documenting, acts as replacement for -# |version| and |release|, also used in various other places throughout the -# built documents. +# The version info for the project you're documenting, acts as replacement for |version| +# and |release|, also used in various other places throughout the built documents. # # The short X.Y version. with open(os.path.join(os.path.dirname(__file__), "..", "..", "VERSION")) as fd: @@ -55,8 +53,8 @@ # The full version, including alpha/beta/rc tags. release = VERSION -# The language for content autogenerated by Sphinx. Refer to documentation -# for a list of supported languages. +# The language for content autogenerated by Sphinx. Refer to documentation for a list of +# supported languages. # language = None # There are two options for replacing |today|: either, you set today to some @@ -68,8 +66,8 @@ # List of documents that shouldn't be included in the build. # unused_docs = [] -# List of directories, relative to source directory, that shouldn't be searched -# for source files. +# List of directories, relative to source directory, that shouldn't be searched for +# source files. exclude_trees = ["build"] # The reST default role (used for this markup: `text`) to use for all documents. @@ -78,12 +76,12 @@ # If true, '()' will be appended to :func: etc. cross-reference text. # add_function_parentheses = True -# If true, the current module name will be prepended to all description -# unit titles (such as .. function::). +# If true, the current module name will be prepended to all description unit titles +# (such as .. function::). # add_module_names = True -# If true, sectionauthor and moduleauthor directives will be shown in the -# output. They are ignored by default. +# If true, sectionauthor and moduleauthor directives will be shown in the output. +# They are ignored by default. # show_authors = False # The name of the Pygments (syntax highlighting) style to use. @@ -96,40 +94,39 @@ html_theme = "sphinx_rtd_theme" html_theme_options = {} -# The name for this set of Sphinx documents. If None, it defaults to -# " v documentation". +# The name for this set of Sphinx documents. +# If None, it defaults to " v documentation". # html_title = None -# A shorter title for the navigation bar. Default is the same as html_title. +# A shorter title for the navigation bar. Default is the same as html_title. # html_short_title = None -# The name of an image file (relative to this directory) to place at the top -# of the sidebar. +# The name of an image file (relative to this directory) to place at the top of the +# sidebar. # html_logo = None -# The name of an image file (within the static path) to use as favicon of the -# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 -# pixels large. +# The name of an image file (within the static path) to use as favicon of the docs. +# This file should be a Windows icon file (.ico) being 16x16 or 32x32 pixels large. # html_favicon = None -# Add any paths that contain custom static files (such as style sheets) here, -# relative to this directory. They are copied after the builtin static files, -# so a file named "default.css" will overwrite the builtin "default.css". +# Add any paths that contain custom static files (such as style sheets) here, relative +# to this directory. They are copied after the builtin static files, so a file named +# "default.css" will overwrite the builtin "default.css". html_static_path = [] -# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, -# using the given strftime format. +# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, using the +# given strftime format. # html_last_updated_fmt = '%b %d, %Y' -# If true, SmartyPants will be used to convert quotes and dashes to -# typographically correct entities. +# If true, SmartyPants will be used to convert quotes and dashes to typographically +# correct entities. # html_use_smartypants = True # Custom sidebar templates, maps document names to template names. # html_sidebars = {} -# Additional templates that should be rendered to pages, maps page names to -# template names. +# Additional templates that should be rendered to pages, maps page names to template +# names. # html_additional_pages = {} # If false, no module index is generated. @@ -144,9 +141,9 @@ # If true, the reST sources are included in the HTML build as _sources/. # html_copy_source = True -# If true, an OpenSearch description file will be output, and all pages will -# contain a tag referring to it. The value of this option must be the -# base URL from which the finished HTML is served. +# If true, an OpenSearch description file will be output, and all pages will contain a +# tag referring to it. The value of this option must be the base URL from which +# the finished HTML is served. # html_use_opensearch = '' # If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml"). @@ -171,8 +168,8 @@ ("index", "GitPython.tex", "GitPython Documentation", "Michael Trier", "manual"), ] -# The name of an image file (relative to this directory) to place at the top of -# the title page. +# The name of an image file (relative to this directory) to place at the top of the +# title page. # latex_logo = None # For "manual" documents, if this is true, then toplevel headings are parts, From c5a29a97e9305f86723f7fceb3a2cd5eb1dadfa6 Mon Sep 17 00:00:00 2001 From: Eliah Kagan Date: Fri, 15 Mar 2024 12:35:49 -0400 Subject: [PATCH 02/10] Link Sphinx manpage references to online Git docs (This is grouped as a general option since it is technically classified as such, even though it currently only affects HTML output.) --- doc/source/conf.py | 2 ++ 1 file changed, 2 insertions(+) diff --git a/doc/source/conf.py b/doc/source/conf.py index e25c1e5dc..809762483 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -87,6 +87,8 @@ # The name of the Pygments (syntax highlighting) style to use. pygments_style = "sphinx" +manpages_url = "https://git-scm.com/docs/{page}" + # Options for HTML output # ----------------------- From 7f1675d2f190c5471186af67d4e18107a4efb745 Mon Sep 17 00:00:00 2001 From: Eliah Kagan Date: Fri, 15 Mar 2024 14:34:29 -0400 Subject: [PATCH 03/10] Remove a spurious extra backtick from a docstring --- git/objects/submodule/base.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/git/objects/submodule/base.py b/git/objects/submodule/base.py index 0e51ae711..a5d1a6ad1 100644 --- a/git/objects/submodule/base.py +++ b/git/objects/submodule/base.py @@ -464,7 +464,7 @@ def add( :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 + 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. From e883293fd8e18ce2e1d2723aa395f3ff35e20213 Mon Sep 17 00:00:00 2001 From: Eliah Kagan Date: Fri, 15 Mar 2024 14:43:35 -0400 Subject: [PATCH 04/10] Add a missing Sphinx reference to a class --- git/repo/base.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/git/repo/base.py b/git/repo/base.py index fe01a9279..1238f0e17 100644 --- a/git/repo/base.py +++ b/git/repo/base.py @@ -1452,7 +1452,7 @@ def clone( :param kwargs: * ``odbt`` = ObjectDatabase Type, allowing to determine the object database - implementation used by the returned Repo instance. + implementation used by the returned :class:`Repo` instance. * All remaining keyword arguments are given to the ``git clone`` command. :return: From d8ab99c26ea0d60b8def5d0fd1e11b0750c47c37 Mon Sep 17 00:00:00 2001 From: Eliah Kagan Date: Fri, 15 Mar 2024 16:02:20 -0400 Subject: [PATCH 05/10] 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. --- git/cmd.py | 9 +++--- git/config.py | 2 +- git/diff.py | 6 ++-- git/index/base.py | 55 ++++++++++++++++++----------------- git/index/typ.py | 3 +- git/objects/base.py | 2 +- git/objects/blob.py | 3 +- git/objects/commit.py | 23 ++++++++------- git/objects/submodule/base.py | 12 ++++---- git/objects/tag.py | 2 +- git/objects/tree.py | 2 +- git/refs/head.py | 2 +- git/refs/symbolic.py | 3 +- git/refs/tag.py | 2 +- git/remote.py | 20 ++++++------- git/repo/base.py | 31 +++++++++++--------- git/repo/fun.py | 6 ++-- git/types.py | 14 +++++---- git/util.py | 11 +++---- 19 files changed, 109 insertions(+), 99 deletions(-) diff --git a/git/cmd.py b/git/cmd.py index ab2688a25..2862b1600 100644 --- a/git/cmd.py +++ b/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 --git a/git/config.py b/git/config.py index 4441c2187..f74d290cc 100644 --- a/git/config.py +++ b/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 --git a/git/diff.py b/git/diff.py index 06935f87e..a6322ff57 100644 --- a/git/diff.py +++ b/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 ` wrapper). :return: diff --git a/git/index/base.py b/git/index/base.py index 59b019f0f..cb67d2c29 100644 --- a/git/index/base.py +++ b/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 `, 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 ` instead. :return: diff --git a/git/index/typ.py b/git/index/typ.py index c247fab99..ffd76dc46 100644 --- a/git/index/typ.py +++ b/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 --git a/git/objects/base.py b/git/objects/base.py index f568a4bc5..22d939aa6 100644 --- a/git/objects/base.py +++ b/git/objects/base.py @@ -45,7 +45,7 @@ class Object(LazyMixin): * :class:`Commit ` * :class:`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 --git a/git/objects/blob.py b/git/objects/blob.py index b49930edf..122d5f731 100644 --- a/git/objects/blob.py +++ b/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 --git a/git/objects/commit.py b/git/objects/commit.py index 473eae8cc..3c5d8fba3 100644 --- a/git/objects/commit.py +++ b/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 --git a/git/objects/submodule/base.py b/git/objects/submodule/base.py index a5d1a6ad1..d01aa448f 100644 --- a/git/objects/submodule/base.py +++ b/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 ` for details. They only take effect with the `init` option. diff --git a/git/objects/tag.py b/git/objects/tag.py index e7ecfa62b..52d79751f 100644 --- a/git/objects/tag.py +++ b/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 --git a/git/objects/tree.py b/git/objects/tree.py index 308dd47a0..ad67f8e47 100644 --- a/git/objects/tree.py +++ b/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 --git a/git/refs/head.py b/git/refs/head.py index aae5767d4..b65189621 100644 --- a/git/refs/head.py +++ b/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 --git a/git/refs/symbolic.py b/git/refs/symbolic.py index 754e90089..dea047d83 100644 --- a/git/refs/symbolic.py +++ b/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 --git a/git/refs/tag.py b/git/refs/tag.py index a1d0b470f..f653d4e7d 100644 --- a/git/refs/tag.py +++ b/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`. diff --git a/git/remote.py b/git/remote.py index 1723216a4..ac58a4f18 100644 --- a/git/remote.py +++ b/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 diff --git a/git/repo/base.py b/git/repo/base.py index 1238f0e17..d6a161305 100644 --- a/git/repo/base.py +++ b/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,7 +749,7 @@ 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: @@ -757,7 +757,7 @@ def iter_commits( 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: []] @@ -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 `. :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. diff --git a/git/repo/fun.py b/git/repo/fun.py index 0ac481206..13c85ea22 100644 --- a/git/repo/fun.py +++ b/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 ` :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. diff --git a/git/types.py b/git/types.py index 64f7629dc..a30179a25 100644 --- a/git/types.py +++ b/git/types.py @@ -57,7 +57,8 @@ * :class:`Commit ` * :class:`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"] diff --git a/git/util.py b/git/util.py index 2a9dd10a9..bef828dbf 100644 --- a/git/util.py +++ b/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` From d271a84a67ab1cbb9c5922244fd5e17517520593 Mon Sep 17 00:00:00 2001 From: Eliah Kagan Date: Fri, 15 Mar 2024 16:14:28 -0400 Subject: [PATCH 06/10] Use more official link to index-format documentation This could also be written automatically by labeling it with the :manpage: role, but it doesn't seem to be an actual manpage, so I have not done that. --- git/index/base.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/git/index/base.py b/git/index/base.py index cb67d2c29..dfb687260 100644 --- a/git/index/base.py +++ b/git/index/base.py @@ -862,7 +862,7 @@ def add( handled manually at all. All current built-in extensions are listed here: - http://opensource.apple.com/source/Git/Git-26/src/git-htmldocs/technical/index-format.txt + https://git-scm.com/docs/index-format :return: List of :class:`~git.index.typ.BaseIndexEntry`\s representing the entries From ca95c420ce5ed45fe33381b25dd1a1c65e150d40 Mon Sep 17 00:00:00 2001 From: Eliah Kagan Date: Fri, 15 Mar 2024 16:18:21 -0400 Subject: [PATCH 07/10] Use current main official link to git-clone URLS doc I am still not using the :manpage: role for this because it points to a specific section, which that role does not support, and it is important that it go to that specific section. (See d8ab99c for details.) --- git/repo/base.py | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/git/repo/base.py b/git/repo/base.py index d6a161305..ce164274e 100644 --- a/git/repo/base.py +++ b/git/repo/base.py @@ -1488,8 +1488,7 @@ def clone_from( """Create a clone from the given URL. :param url: - Valid git url, see: - http://www.kernel.org/pub/software/scm/git/docs/git-clone.html#URLS + Valid git url, see: https://git-scm.com/docs/git-clone#URLS :param to_path: Path to which the repository should be cloned to. From 85434571090a24ac84d1ce81f3fa74909e3d5c5f Mon Sep 17 00:00:00 2001 From: Eliah Kagan Date: Fri, 15 Mar 2024 16:24:57 -0400 Subject: [PATCH 08/10] Use :const: for constants that had the :attr: role Note that this intentionally does *not* include some all-caps class attributes that are not really constants: - Git.GIT_PYTHON_GIT_EXECUTABLE is set by refresh functions, including on subsequent calls, which is an important and documented part of what those functions do. (Also, it is set automatically from an enviroment variable, which is not constant across runs; that it could not even in principle be replaced by a specific literal value is a further reason it is not a constant.) - The Git.USE_SHELL attribute is a more ambiguous case. It is given a literal value (False) which it preferably remains. But setting it has been documented as something users can do (in the changelog, and later in regard to setting it being a deprecated operation). The first of these is decisively not a constant even under a loose definition, while the second is less clear. I've kept both with the :attr: role. --- git/remote.py | 2 +- git/util.py | 16 ++++++++-------- 2 files changed, 9 insertions(+), 9 deletions(-) diff --git a/git/remote.py b/git/remote.py index ac58a4f18..2c452022e 100644 --- a/git/remote.py +++ b/git/remote.py @@ -1177,7 +1177,7 @@ def push( individual head which had been updated on the remote side. If the push contains rejected heads, these will have the - :attr:`PushInfo.ERROR` bit set in their flags. + :const:`PushInfo.ERROR` bit set in their flags. If the operation fails completely, the length of the returned :class:`PushInfoList` will be 0. diff --git a/git/util.py b/git/util.py index bef828dbf..0de724ceb 100644 --- a/git/util.py +++ b/git/util.py @@ -713,14 +713,14 @@ def update( :param op_code: Integer allowing to be compared against Operation IDs and stage IDs. - Stage IDs are :attr:`BEGIN` and :attr:`END`. :attr:`BEGIN` will only be set - once for each Operation ID as well as :attr:`END`. It may be that - :attr:`BEGIN` and :attr:`END` are set at once in case only one progress - message was emitted due to the speed of the operation. Between :attr:`BEGIN` - and :attr:`END`, none of these flags will be set. + Stage IDs are :const:`BEGIN` and :const:`END`. :const:`BEGIN` will only be + set once for each Operation ID as well as :const:`END`. It may be that + :const:`BEGIN` and :const:`END` are set at once in case only one progress + message was emitted due to the speed of the operation. Between + :const:`BEGIN` and :const:`END`, none of these flags will be set. - Operation IDs are all held within the :attr:`OP_MASK`. Only one Operation ID - will be active per call. + Operation IDs are all held within the :const:`OP_MASK`. Only one Operation + ID will be active per call. :param cur_count: Current absolute count of items. @@ -730,7 +730,7 @@ def update( maximum number of items or if it is (yet) unknown. :param message: - In case of the :attr:`WRITING` operation, it contains the amount of bytes + In case of the :const:`WRITING` operation, it contains the amount of bytes transferred. It may possibly be used for other purposes as well. :note: From 6626117259b93d0a3085dd17ed71ef1acd08c7a5 Mon Sep 17 00:00:00 2001 From: Eliah Kagan Date: Sat, 16 Mar 2024 01:58:30 -0400 Subject: [PATCH 09/10] Fix parse_date docstring spacing; use RFC role There are only a three cases where a specific RFC is mentioned. Only one is in parse_date and the others are elsewhere. --- git/objects/commit.py | 8 ++++---- git/objects/util.py | 5 ++--- 2 files changed, 6 insertions(+), 7 deletions(-) diff --git a/git/objects/commit.py b/git/objects/commit.py index 3c5d8fba3..6a60c30bd 100644 --- a/git/objects/commit.py +++ b/git/objects/commit.py @@ -404,8 +404,8 @@ def trailers(self) -> Dict[str, str]: 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 :manpage:`git-interpret-trailers(1)`. + Git messages can contain trailer information that are similar to :rfc:`822` + e-mail 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,8 +456,8 @@ def trailers_list(self) -> List[Tuple[str, str]]: 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 :manpage:`git-interpret-trailers(1)`. + Git messages can contain trailer information that are similar to :rfc:`822` + e-mail 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 diff --git a/git/objects/util.py b/git/objects/util.py index 7cca05134..297b33b70 100644 --- a/git/objects/util.py +++ b/git/objects/util.py @@ -223,9 +223,8 @@ def parse_date(string_date: Union[str, datetime]) -> Tuple[int, int]: * Aware datetime instance * Git internal format: timestamp offset - * RFC 2822: ``Thu, 07 Apr 2005 22:13:13 +0200`` - * ISO 8601: ``2005-04-07T22:13:13`` - The T can be a space as well. + * :rfc:`2822`: ``Thu, 07 Apr 2005 22:13:13 +0200`` + * ISO 8601: ``2005-04-07T22:13:13`` - The ``T`` can be a space as well. :return: Tuple(int(timestamp_UTC), int(offset)), both in seconds since epoch From a957ae7a94ebede485e94d03da0258a0d2ad79e0 Mon Sep 17 00:00:00 2001 From: Eliah Kagan Date: Sat, 16 Mar 2024 02:19:39 -0400 Subject: [PATCH 10/10] Use the :exc: role for exceptions Rather than the more general :class: role that was used for them. --- git/db.py | 2 +- git/index/base.py | 10 +++++----- git/objects/submodule/util.py | 2 +- git/objects/tree.py | 4 ++-- git/refs/head.py | 2 +- git/refs/reference.py | 2 +- git/refs/remote.py | 2 +- git/refs/symbolic.py | 2 +- git/repo/fun.py | 4 ++-- git/types.py | 2 +- git/util.py | 8 ++++---- 11 files changed, 20 insertions(+), 20 deletions(-) diff --git a/git/db.py b/git/db.py index 15e791e6c..5b2ca4de2 100644 --- a/git/db.py +++ b/git/db.py @@ -59,7 +59,7 @@ def partial_to_complete_sha_hex(self, partial_hexsha: str) -> bytes: :raise gitdb.exc.BadObject: :note: - Currently we only raise :class:`~gitdb.exc.BadObject` as git does not + Currently we only raise :exc:`~gitdb.exc.BadObject` as git does not communicate ambiguous objects separately. """ try: diff --git a/git/index/base.py b/git/index/base.py index dfb687260..fb91e092c 100644 --- a/git/index/base.py +++ b/git/index/base.py @@ -550,8 +550,8 @@ def resolve_blobs(self, iter_blobs: Iterator[Blob]) -> "IndexFile": This will effectively remove the index entries of the respective path at all non-null stages and add the given blob as new stage null blob. - For each path there may only be one blob, otherwise a :class:`ValueError` will - be raised claiming the path is already at stage 0. + For each path there may only be one blob, otherwise a :exc:`ValueError` will be + raised claiming the path is already at stage 0. :raise ValueError: If one of the blobs already existed at stage 0. @@ -644,8 +644,8 @@ def _process_diff_args( def _to_relative_path(self, path: PathLike) -> PathLike: """ :return: - Version of path relative to our git directory or raise :class:`ValueError` - if it is not within our git directory. + Version of path relative to our git directory or raise :exc:`ValueError` if + it is not within our git directory. :raise ValueError: """ @@ -1215,7 +1215,7 @@ def checkout( :param force: If ``True``, existing files will be overwritten even if they contain local modifications. - If ``False``, these will trigger a :class:`~git.exc.CheckoutError`. + If ``False``, these will trigger a :exc:`~git.exc.CheckoutError`. :param fprogress: See :meth:`IndexFile.add` for signature and explanation. diff --git a/git/objects/submodule/util.py b/git/objects/submodule/util.py index e5af5eb31..10b994e9b 100644 --- a/git/objects/submodule/util.py +++ b/git/objects/submodule/util.py @@ -52,7 +52,7 @@ def mkhead(repo: "Repo", path: PathLike) -> "Head": def find_first_remote_branch(remotes: Sequence["Remote"], branch_name: str) -> "RemoteReference": """Find the remote branch matching the name of the given branch or raise - :class:`~git.exc.InvalidGitRepositoryError`.""" + :exc:`~git.exc.InvalidGitRepositoryError`.""" for remote in remotes: try: return remote.refs[branch_name] diff --git a/git/objects/tree.py b/git/objects/tree.py index ad67f8e47..c74df58a9 100644 --- a/git/objects/tree.py +++ b/git/objects/tree.py @@ -100,8 +100,8 @@ def add(self, sha: bytes, mode: int, name: str, force: bool = False) -> "TreeMod """Add the given item to the tree. If an item with the given name already exists, nothing will be done, but a - :class:`ValueError` will be raised if the sha and mode of the existing item do - not match the one you add, unless `force` is ``True``. + :exc:`ValueError` will be raised if the sha and mode of the existing item do not + match the one you add, unless `force` is ``True``. :param sha: The 20 or 40 byte sha of the item to add. diff --git a/git/refs/head.py b/git/refs/head.py index b65189621..86321d9ea 100644 --- a/git/refs/head.py +++ b/git/refs/head.py @@ -247,7 +247,7 @@ def checkout(self, force: bool = False, **kwargs: Any) -> Union["HEAD", "Head"]: :param force: If ``True``, changes to the index and the working tree will be discarded. - If ``False``, :class:`~git.exc.GitCommandError` will be raised in that + If ``False``, :exc:`~git.exc.GitCommandError` will be raised in that situation. :param kwargs: diff --git a/git/refs/reference.py b/git/refs/reference.py index cf418aa5d..62fb58420 100644 --- a/git/refs/reference.py +++ b/git/refs/reference.py @@ -21,7 +21,7 @@ def require_remote_ref_path(func: Callable[..., _T]) -> Callable[..., _T]: - """A decorator raising :class:`ValueError` if we are not a valid remote, based on the + """A decorator raising :exc:`ValueError` if we are not a valid remote, based on the path.""" def wrapper(self: T_References, *args: Any) -> _T: diff --git a/git/refs/remote.py b/git/refs/remote.py index 5cbd1b81b..3f9c6c6be 100644 --- a/git/refs/remote.py +++ b/git/refs/remote.py @@ -76,5 +76,5 @@ def delete(cls, repo: "Repo", *refs: "RemoteReference", **kwargs: Any) -> None: @classmethod def create(cls, *args: Any, **kwargs: Any) -> NoReturn: - """Raise :class:`TypeError`. Defined so the ``create`` method is disabled.""" + """Raise :exc:`TypeError`. Defined so the ``create`` method is disabled.""" raise TypeError("Cannot explicitly create remote references") diff --git a/git/refs/symbolic.py b/git/refs/symbolic.py index dea047d83..2701f9f2b 100644 --- a/git/refs/symbolic.py +++ b/git/refs/symbolic.py @@ -738,7 +738,7 @@ def create( :param force: If ``True``, force creation even if a symbolic reference with that name - already exists. Raise :class:`OSError` otherwise. + already exists. Raise :exc:`OSError` otherwise. :param logmsg: If not ``None``, the message to append to the reflog. diff --git a/git/repo/fun.py b/git/repo/fun.py index 13c85ea22..738e5816d 100644 --- a/git/repo/fun.py +++ b/git/repo/fun.py @@ -153,8 +153,8 @@ def name_to_object(repo: "Repo", name: str, return_ref: bool = False) -> Union[A :param return_ref: If ``True``, and name specifies a reference, we will return the reference - instead of the object. Otherwise it will raise :class:`~gitdb.exc.BadObject` or - :class:`~gitdb.exc.BadName`. + instead of the object. Otherwise it will raise :exc:`~gitdb.exc.BadObject` or + :exc:`~gitdb.exc.BadName`. """ hexsha: Union[None, str, bytes] = None diff --git a/git/types.py b/git/types.py index a30179a25..e3ae9e3d5 100644 --- a/git/types.py +++ b/git/types.py @@ -190,7 +190,7 @@ def assert_never(inp: NoReturn, raise_error: bool = True, exc: Union[Exception, mismatch and cause a mypy error. :param raise_error: - If ``True``, will also raise :class:`ValueError` with a general "unhandled + If ``True``, will also raise :exc:`ValueError` with a general "unhandled literal" message, or the exception object passed as `exc`. :param exc: diff --git a/git/util.py b/git/util.py index 0de724ceb..37986edaa 100644 --- a/git/util.py +++ b/git/util.py @@ -158,8 +158,8 @@ def _read_win_env_flag(name: str, default: bool) -> bool: def unbare_repo(func: Callable[..., T]) -> Callable[..., T]: - """Methods with this decorator raise - :class:`~git.exc.InvalidGitRepositoryError` if they encounter a bare repository.""" + """Methods with this decorator raise :exc:`~git.exc.InvalidGitRepositoryError` if + they encounter a bare repository.""" from .exc import InvalidGitRepositoryError @@ -1094,8 +1094,8 @@ def __init__( self._max_block_time = max_block_time_s def _obtain_lock(self) -> None: - """This method blocks until it obtained the lock, or raises :class:`IOError` if - it ran out of time or if the parent directory was not available anymore. + """This method blocks until it obtained the lock, or raises :exc:`IOError` if it + ran out of time or if the parent directory was not available anymore. If this method returns, you are guaranteed to own the lock. """