diff --git a/git/repo/base.py b/git/repo/base.py index 7b3e514c1..4745a2411 100644 --- a/git/repo/base.py +++ b/git/repo/base.py @@ -102,9 +102,9 @@ class BlameEntry(NamedTuple): class Repo: - """Represents a git repository and allows you to query references, - gather commit information, generate diffs, create and clone repositories, and query - the log. + """Represents a git repository and allows you to query references, father + commit information, generate diffs, create and clone repositories, and query the + log. The following attributes are worth using: @@ -188,16 +188,18 @@ def __init__( repo = Repo(R"C:\Users\mtrier\Development\git-python\.git") - In *Cygwin*, `path` may be a ``cygdrive/...`` prefixed path. - - If `path` is None or an empty string, :envvar:`GIT_DIR` is used. If that - environment variable is absent or empty, the current directory is used. + - If `path` is ``None`` or an empty string, :envvar:`GIT_DIR` is used. If + that environment variable is absent or empty, the current directory is + used. :param odbt: Object DataBase type - a type which is constructed by providing the directory containing the database objects, i.e. ``.git/objects``. It will be - used to access all object data + used to access all object data. :param search_parent_directories: - If True, all parent directories will be searched for a valid repo as well. + If ``True``, all parent directories will be searched for a valid repo as + well. Please note that this was the default behaviour in older versions of GitPython, which is considered a bug though. @@ -372,7 +374,7 @@ def working_tree_dir(self) -> Optional[PathLike]: """ :return: The working tree directory of our git repository. - If this is a bare repository, None is returned. + If this is a bare repository, ``None`` is returned. """ return self._working_tree_dir @@ -387,7 +389,7 @@ def common_dir(self) -> PathLike: @property def bare(self) -> bool: - """:return: True if the repository is bare""" + """:return: ``True`` if the repository is bare""" return self._bare @property @@ -450,7 +452,7 @@ def remotes(self) -> "IterableList[Remote]": def remote(self, name: str = "origin") -> "Remote": """:return: The remote with the specified name - :raise ValueError + :raise ValueError: If no remote with such a name exists. """ r = Remote(self, name) @@ -494,10 +496,13 @@ def create_submodule(self, *args: Any, **kwargs: Any) -> Submodule: return Submodule.add(self, *args, **kwargs) def iter_submodules(self, *args: Any, **kwargs: Any) -> Iterator[Submodule]: - """An iterator yielding Submodule instances, see Traversable interface - for a description of args and kwargs. + """An iterator yielding Submodule instances. - :return: Iterator + See the `~git.objects.util.Traversable` interface for a description of `args` + and `kwargs`. + + :return: + Iterator """ return RootModule(self).traverse(*args, **kwargs) @@ -554,7 +559,8 @@ def create_head( ) -> "Head": """Create a new head within the repository. - :note: For more documentation, please see the + :note: + For more documentation, please see the :meth:`Head.create ` method. :return: @@ -648,7 +654,7 @@ def config_reader( configuration files. :param config_level: - For possible values, see the :meth:`config_writer` method. If None, all + For possible values, see the :meth:`config_writer` method. If ``None``, all applicable levels will be used. Specify a level in case you know which file you wish to read to prevent reading multiple files. @@ -744,7 +750,7 @@ def iter_commits( :param rev: Revision specifier, see ``git rev-parse`` for viable options. - If None, the active branch will be used. + 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 @@ -759,7 +765,7 @@ def iter_commits( ``"revA...revB"`` revision specifier. :return: - Iterator of :class:`~git.objects.commit.Commit` objects + Iterator of :class:`~git.objects.commit.Commit` objects """ if rev is None: rev = self.head.commit @@ -819,7 +825,7 @@ def is_ancestor(self, ancestor_rev: "Commit", rev: "Commit") -> bool: Rev to test against `ancestor_rev`. :return: - True if `ancestor_rev` is an ancestor to `rev`. + ``True`` if `ancestor_rev` is an ancestor to `rev`. """ try: self.git.merge_base(ancestor_rev, rev, is_ancestor=True) @@ -923,9 +929,9 @@ def is_dirty( ) -> bool: """ :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. + ``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. """ if self._bare: # Bare repositories with no associated working directory are @@ -1036,9 +1042,9 @@ def blame_incremental(self, rev: str | HEAD | None, file: str, **kwargs: Any) -> stream of :class:`BlameEntry` tuples. :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. + 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. :return: Lazy iterator of :class:`BlameEntry` tuples, where the commit indicates the @@ -1132,9 +1138,9 @@ def blame( """The blame information for the given file at the given revision. :param rev: - Revision specifier. If None, the blame will include all the latest + 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. + ``git rev-parse`` is a valid option. :return: list: [git.Commit, list: []] @@ -1286,9 +1292,9 @@ def init( """Initialize a git repository at the given path if specified. :param path: - The full path to the repo (traditionally ends with ``/.git``). - Or None, in which case the repository will be created in the current working - directory. + The full path to the repo (traditionally ends with ``/.git``). Or + ``None``, in which case the repository will be created in the current + working directory. :param mkdir: If specified, will create the repository directory if it doesn't already @@ -1445,7 +1451,7 @@ def clone( Allow unsafe options to be used, like ``--upload-pack``. :param kwargs: - * odbt = ObjectDatabase Type, allowing to determine the object database + * ``odbt`` = ObjectDatabase Type, allowing to determine the object database implementation used by the returned Repo instance. * All remaining keyword arguments are given to the ``git clone`` command. @@ -1547,9 +1553,9 @@ def archive( :param kwargs: Additional arguments passed to ``git archive``: - * Use the 'format' argument to define the kind of format. Use specialized + * Use the ``format`` argument to define the kind of format. Use specialized ostreams to write any format supported by Python. - * You may specify the special **path** keyword, which may either be a + * You may specify the special ``path`` keyword, which may either be a repository-relative path to a directory or file to place into the archive, or a list or tuple of multiple paths. @@ -1581,7 +1587,7 @@ def has_separate_working_tree(self) -> bool: to. :note: - Bare repositories will always return False here. + Bare repositories will always return ``False`` here. """ if self.bare: return False @@ -1601,7 +1607,7 @@ def currently_rebasing_on(self) -> Commit | None: :return: The commit which is currently being replayed while rebasing. - None if we are not currently rebasing. + ``None`` if we are not currently rebasing. """ if self.git_dir: rebase_head_file = osp.join(self.git_dir, "REBASE_HEAD") diff --git a/git/repo/fun.py b/git/repo/fun.py index 4936f1773..e9fad2c46 100644 --- a/git/repo/fun.py +++ b/git/repo/fun.py @@ -128,7 +128,7 @@ def find_submodule_git_dir(d: "PathLike") -> Optional["PathLike"]: def short_to_long(odb: "GitCmdObjectDB", hexsha: str) -> Optional[bytes]: """ :return: - Long hexadecimal sha1 from the given less than 40 byte hexsha or None if no + Long hexadecimal sha1 from the given less than 40 byte hexsha, or ``None`` if no candidate could be found. :param hexsha: @@ -150,7 +150,7 @@ def name_to_object( references are supported. :param return_ref: - If True, and name specifies a reference, we will return the reference + If ``True``, and name specifies a reference, we will return the reference instead of the object. Otherwise it will raise `~gitdb.exc.BadObject` o `~gitdb.exc.BadName`. """ @@ -202,7 +202,7 @@ def name_to_object( def deref_tag(tag: "Tag") -> "TagObject": - """Recursively dereference a tag and return the resulting object""" + """Recursively dereference a tag and return the resulting object.""" while True: try: tag = tag.object @@ -213,7 +213,7 @@ def deref_tag(tag: "Tag") -> "TagObject": def to_commit(obj: Object) -> Union["Commit", "TagObject"]: - """Convert the given object to a commit if possible and return it""" + """Convert the given object to a commit if possible and return it.""" if obj.type == "tag": obj = deref_tag(obj)