Skip to content

Commit

Permalink
Further revise docstrings within git.objects.submodule
Browse files Browse the repository at this point in the history
  • Loading branch information
@EliahKagan
EliahKagan committed Feb 28, 2024
1 parent 1b25a13 commit 08a80aa
Show file tree
Hide file tree
Showing 3 changed files with 86 additions and 72 deletions.
128 changes: 70 additions & 58 deletions git/objects/submodule/base.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -266,8 +266,8 @@ def _clear_cache(self) -> None:
def _sio_modules(cls, parent_commit: Commit_ish) -> BytesIO:
"""
:return:
Configuration file as BytesIO - we only access it through the respective
blob's data
Configuration file as :class:`~io.BytesIO` - we only access it through the
respective blob's data
"""
sio = BytesIO(parent_commit.tree[cls.k_modules_file].data_stream.read())
sio.name = cls.k_modules_file
Expand Down Expand Up @@ -354,7 +354,7 @@ def _to_relative_path(cls, parent_repo: "Repo", path: PathLike) -> PathLike:
""":return: a path guaranteed to be relative to the given parent repository
:raise ValueError:
If path is not contained in the parent repository's working tree
If path is not contained in the parent repository's working tree.
"""
path = to_native_path_linux(path)
if path.endswith("/"):
Expand All @@ -378,8 +378,8 @@ def _to_relative_path(cls, parent_repo: "Repo", path: PathLike) -> PathLike:

@classmethod
def _write_git_file_and_module_config(cls, working_tree_dir: PathLike, module_abspath: PathLike) -> None:
"""Write a .git file containing a (preferably) relative path to the actual git
module repository.
"""Write a ``.git`` file containing a (preferably) relative path to the actual
git module repository.
It is an error if the `module_abspath` cannot be made into a relative path,
relative to the `working_tree_dir`.
Expand Down Expand Up @@ -430,10 +430,10 @@ def add(
allow_unsafe_options: bool = False,
allow_unsafe_protocols: bool = False,
) -> "Submodule":
"""Add a new submodule to the given repository. This will alter the index
as well as the ``.gitmodules`` file, but will not create a new commit.
If the submodule already exists, no matter if the configuration differs
from the one provided, the existing submodule will be returned.
"""Add a new submodule to the given repository. This will alter the index as
well as the ``.gitmodules`` file, but will not create a new commit. If the
submodule already exists, no matter if the configuration differs from the one
provided, the existing submodule will be returned.
:param repo:
Repository instance which should receive the submodule.
Expand All @@ -448,23 +448,23 @@ 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 remote
is taken instead. This is useful if you want to make an existing repository
a submodule of another one.
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
given branch must exist in the remote repository, and will be checked out
locally as a tracking branch.
It will only be written into the configuration if it not None, which is when
the checked out branch will be the one the remote HEAD pointed to.
It will only be written into the configuration if it not ``None``, which is
when the checked out branch will be the one the remote HEAD pointed to.
The result you get in these situation is somewhat fuzzy, and it is
recommended to specify at least ``master`` here.
Examples are ``master`` or ``feature/new``.
:param no_checkout:
If True, and if the repository has to be cloned manually, no checkout will
be performed.
If ``True``, and if the repository has to be cloned manually, no checkout
will be performed.
:param depth:
Create a shallow clone with a history truncated to the specified number of
Expand All @@ -479,7 +479,8 @@ def add(
want to unset some variable, consider providing an empty string as its
value.
:param clone_multi_options: A list of Clone options. Please see
:param clone_multi_options:
A list of clone options. Please see
:meth:`Repo.clone <git.repo.base.Repo.clone>` for details.
:param allow_unsafe_protocols:
Expand Down Expand Up @@ -632,44 +633,49 @@ def update(
with the binsha of this instance.
:param recursive:
If True, we will operate recursively and update child modules as well.
If ``True``, we will operate recursively and update child modules as well.
:param init:
If True, the module repository will be cloned into place if necessary.
If ``True``, the module repository will be cloned into place if necessary.
:param to_latest_revision:
If True, the submodule's sha will be ignored during checkout. Instead, the
remote will be fetched, and the local tracking branch updated. This only
If ``True``, the submodule's sha will be ignored during checkout. Instead,
the remote will be fetched, and the local tracking branch updated. This only
works if we have a local tracking branch, which is the case if the remote
repository had a master branch, or of the 'branch' option was specified for
this submodule and the branch existed remotely.
repository had a master branch, or of the ``branch`` option was specified
for this submodule and the branch existed remotely.
:param progress:
:class:`UpdateProgress` instance, or None if no progress should be shown.
:class:`UpdateProgress` instance, or ``None`` if no progress should be
shown.
:param dry_run:
If True, the operation will only be simulated, but not performed.
If ``True``, the operation will only be simulated, but not performed.
All performed operations are read-only.
:param force:
If True, we may reset heads even if the repository in question is dirty.
If ``True``, we may reset heads even if the repository in question is dirty.
Additionally we will be allowed to set a tracking branch which is ahead of
its remote branch back into the past or the location of the remote branch.
This will essentially 'forget' commits.
If False, local tracking branches that are in the future of their respective
remote branches will simply not be moved.
If ``False``, local tracking branches that are in the future of their
respective remote branches will simply not be moved.
:param keep_going:
If True, we will ignore but log all errors, and keep going recursively.
If ``True``, we will ignore but log all errors, and keep going recursively.
Unless `dry_run` is set as well, `keep_going` could cause
subsequent/inherited errors you wouldn't see otherwise.
In conjunction with `dry_run`, it can be useful to anticipate all errors
when updating submodules.
:param env: Optional dictionary containing the desired environment variables.
:param env:
Optional dictionary containing the desired environment variables.
Note: Provided variables will be used to update the execution environment
for ``git``. If some variable is not specified in `env` and is defined in
attr:`os.environ`, value from attr:`os.environ` will be used.
If you want to unset some variable, consider providing the empty string as
its value.
Expand All @@ -688,7 +694,7 @@ def update(
Does nothing in bare repositories.
:note:
This method is definitely not atomic if `recursive` is True.
This method is definitely not atomic if `recursive` is ``True``.
:return:
self
Expand Down Expand Up @@ -950,18 +956,18 @@ def move(self, module_path: PathLike, configuration: bool = True, module: bool =
:param module_path:
The path to which to move our module in the parent repository's working
tree, given as repository - relative or absolute path. Intermediate
tree, given as repository-relative or absolute path. Intermediate
directories will be created accordingly. If the path already exists, it must
be empty. Trailing (back)slashes are removed automatically.
:param configuration:
If True, the configuration will be adjusted to let the submodule point to
the given path.
If ``True``, the configuration will be adjusted to let the submodule point
to the given path.
:param module:
If True, the repository managed by this submodule will be moved as well. If
False, we don't move the submodule's checkout, which may leave the parent
repository in an inconsistent state.
If ``True``, the repository managed by this submodule will be moved as well.
If ``False``, we don't move the submodule's checkout, which may leave the
parent repository in an inconsistent state.
:return:
self
Expand Down Expand Up @@ -1074,12 +1080,13 @@ def remove(
from the ``.gitmodules`` file and the entry in the ``.git/config`` file.
:param module:
If True, the checked out module we point to will be deleted as well. If that
module is currently on a commit outside any branch in the remote, or if it
is ahead of its tracking branch, or if there are modified or untracked files
in its working tree, then the removal will fail. In case the removal of the
repository fails for these reasons, the submodule status will not have been
altered.
If ``True``, the checked out module we point to will be deleted as well. If
that module is currently on a commit outside any branch in the remote, or if
it is ahead of its tracking branch, or if there are modified or untracked
files in its working tree, then the removal will fail. In case the removal
of the repository fails for these reasons, the submodule status will not
have been altered.
If this submodule has child modules of its own, these will be deleted prior
to touching the direct submodule.
Expand All @@ -1088,12 +1095,12 @@ def remove(
This basically enforces a brute-force file system based deletion.
:param configuration:
If True, the submodule is deleted from the configuration, otherwise it
If ``True``, the submodule is deleted from the configuration, otherwise it
isn't. Although this should be enabled most of the time, this flag enables
you to safely delete the repository of your submodule.
:param dry_run:
If True, we will not actually do anything, but throw the errors we would
If ``True``, we will not actually do anything, but throw the errors we would
usually throw.
:return:
Expand Down Expand Up @@ -1239,12 +1246,12 @@ def set_parent_commit(self, commit: Union[Commit_ish, None], check: bool = True)
contain the ``.gitmodules`` blob.
:param commit:
Commit-ish reference pointing at the root_tree, or None to always point to
the most recent commit
Commit-ish reference pointing at the root_tree, or ``None`` to always point
to the most recent commit.
:param check:
If True, relatively expensive checks will be performed to verify validity of
the submodule.
If ``True``, relatively expensive checks will be performed to verify
validity of the submodule.
:raise ValueError:
If the commit's tree didn't contain the ``.gitmodules`` blob.
Expand Down Expand Up @@ -1297,8 +1304,9 @@ def config_writer(
to this submodule into the ``.gitmodules`` file.
:param index:
If not None, an IndexFile instance which should be written.
Defaults to the index of the Submodule's parent repository.
If not ``None``, an :class:`~git.index.base.IndexFile` instance which should
be written. Defaults to the index of the :class:`Submodule`'s parent
repository.
:param write:
If True, the index will be written each time a configuration value changes.
Expand Down Expand Up @@ -1380,7 +1388,9 @@ def rename(self, new_name: str) -> "Submodule":
@unbare_repo
def module(self) -> "Repo":
"""
:return: Repo instance initialized from the repository at our submodule path
:return:
:class:`~git.repo.base.Repo` instance initialized from the repository at our
submodule path
:raise git.exc.InvalidGitRepositoryError:
If a repository was not available.
Expand All @@ -1401,7 +1411,7 @@ def module(self) -> "Repo":
def module_exists(self) -> bool:
"""
:return:
True if our module exists and is a valid git repository.
``True`` if our module exists and is a valid git repository.
See the :meth:`module` method.
"""
try:
Expand All @@ -1414,7 +1424,7 @@ def module_exists(self) -> bool:
def exists(self) -> bool:
"""
:return:
True if the submodule exists, False otherwise.
``True`` if the submodule exists, ``False`` otherwise.
Please note that a submodule may exist (in the ``.gitmodules`` file) even
though its module doesn't exist on disk.
"""
Expand Down Expand Up @@ -1480,14 +1490,15 @@ def branch_name(self) -> str:

@property
def url(self) -> str:
""":return: The url to the repository which our module - repository refers to"""
""":return: The url to the repository our submodule's repository refers to"""
return self._url

@property
def parent_commit(self) -> "Commit_ish":
"""
:return:
Commit instance with the tree containing the ``.gitmodules`` file
:class:`~git.objects.commit.Commit` instance with the tree containing the
``.gitmodules`` file
:note:
Will always point to the current head's commit if it was not set explicitly.
Expand Down Expand Up @@ -1531,8 +1542,9 @@ def config_reader(self) -> SectionConstraint[SubmoduleConfigParser]:
def children(self) -> IterableList["Submodule"]:
"""
:return:
IterableList(Submodule, ...) An iterable list of submodules instances which
are children of this submodule or 0 if the submodule is not checked out.
IterableList(Submodule, ...) An iterable list of :class:`Submodule`
instances which are children of this submodule or 0 if the submodule is not
checked out.
"""
return self._get_intermediate_items(self)

Expand Down
28 changes: 15 additions & 13 deletions git/objects/submodule/root.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -89,21 +89,21 @@ def update(
) -> "RootModule":
"""Update the submodules of this repository to the current HEAD commit.
This method behaves smartly by determining changes of the path of a submodules
This method behaves smartly by determining changes of the path of a submodule's
repository, next to changes to the to-be-checked-out commit or the branch to be
checked out. This works if the submodules ID does not change.
checked out. This works if the submodule's ID does not change.
Additionally it will detect addition and removal of submodules, which will be
handled gracefully.
:param previous_commit:
If set to a commit-ish, the commit we should use as the previous commit the
HEAD pointed to before it was set to the commit it points to now.
If None, it defaults to ``HEAD@{1}`` otherwise.
If ``None``, it defaults to ``HEAD@{1}`` otherwise.
:param recursive:
If True, the children of submodules will be updated as well using the same
technique.
If ``True``, the children of submodules will be updated as well using the
same technique.
:param force_remove:
If submodules have been deleted, they will be forcibly removed. Otherwise
Expand All @@ -116,28 +116,30 @@ def update(
If we encounter a new module which would need to be initialized, then do it.
:param to_latest_revision:
If True, instead of checking out the revision pointed to by this submodule's
sha, the checked out tracking branch will be merged with the latest remote
branch fetched from the repository's origin.
If ``True``, instead of checking out the revision pointed to by this
submodule's sha, the checked out tracking branch will be merged with the
latest remote branch fetched from the repository's origin.
Unless `force_reset` is specified, a local tracking branch will never be
reset into its past, therefore the remote branch must be in the future for
this to have an effect.
:param force_reset:
If True, submodules may checkout or reset their branch even if the
If ``True``, submodules may checkout or reset their branch even if the
repository has pending changes that would be overwritten, or if the local
tracking branch is in the future of the remote tracking branch and would be
reset into its past.
:param progress:
:class:`RootUpdateProgress` instance or None if no progress should be sent.
:class:`RootUpdateProgress` instance, or ``None`` if no progress should be
sent.
:param dry_run:
If True, operations will not actually be performed. Progress messages will
change accordingly to indicate the WOULD DO state of the operation.
If ``True``, operations will not actually be performed. Progress messages
will change accordingly to indicate the WOULD DO state of the operation.
:param keep_going:
If True, we will ignore but log all errors, and keep going recursively.
If ``True``, we will ignore but log all errors, and keep going recursively.
Unless `dry_run` is set as well, `keep_going` could cause
subsequent/inherited errors you wouldn't see otherwise.
In conjunction with `dry_run`, this can be useful to anticipate all errors
Expand Down
2 changes: 1 addition & 1 deletion git/objects/submodule/util.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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`."""
:class:`~git.exc.InvalidGitRepositoryError`."""
for remote in remotes:
try:
return remote.refs[branch_name]
Expand Down

0 comments on commit 08a80aa

Please sign in to comment.