Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Revise comments, docstrings, some messages, and a bit of code #1725

Merged
merged 36 commits into from
Oct 30, 2023
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
36 commits
Select commit Hold shift + click to select a range
7dd2095
Fix docstrings that intend '\' literally
EliahKagan Oct 10, 2023
ffcbf07
Put all regex patterns in r-strings
EliahKagan Oct 10, 2023
2c94b6a
Remove r prefix from strings that need not be raw
EliahKagan Oct 10, 2023
35fd65b
Fix _index_from_*_format docstrings (proc reading)
EliahKagan Oct 15, 2023
5af7446
Fix case in IndexObject.abspath exception message
EliahKagan Oct 16, 2023
692e59e
Remove Commit._deserialize doc for param_from_rev_list
EliahKagan Oct 16, 2023
ab46192
Add missing space in Submodule.update debug message
EliahKagan Oct 17, 2023
1114828
Remove obsolete comment in Submodule.module
EliahKagan Oct 18, 2023
f95d4fd
Clarify "master repository" in RootModule docs
EliahKagan Oct 18, 2023
9fea488
Change spelling from "commit'ish" to "commit-ish"
EliahKagan Oct 18, 2023
4536b63
Update git-source citation in Reference.set_object
EliahKagan Oct 18, 2023
59d208c
Fix message in SymbolicReference.from_path
EliahKagan Oct 18, 2023
add46d9
Use "is" to compare __class__
EliahKagan Oct 18, 2023
cd16a35
Revise docstrings and comments for clarity and formatting
EliahKagan Oct 18, 2023
e8343e2
Firm up comment about is_win in util.is_cygwin_git
EliahKagan Oct 18, 2023
f78587f
Remove explicit inheritance from object
EliahKagan Oct 18, 2023
0327f8f
Make all one-element __slots__ be tuples
EliahKagan Oct 18, 2023
d4a87c1
Revise comments in tests used to generate tutorials
EliahKagan Oct 22, 2023
11fce8a
Revise docstrings/comments in most other test modules
EliahKagan Oct 20, 2023
cf9243a
Add a module docstring to tstrunner.py
EliahKagan Oct 23, 2023
b5c3ca4
Slightly improve readability of installation-test strings
EliahKagan Oct 23, 2023
f444470
More wording improvements (in git module)
EliahKagan Oct 23, 2023
db317f1
Change :returns: to :return:
EliahKagan Oct 23, 2023
720e4bb
Fix TestBigRepoR.setUp info message
EliahKagan Oct 23, 2023
faa19ac
Remove outdated git_daemon_launched Windows info
EliahKagan Oct 24, 2023
bffc537
Revise docstrings/comments in test helpers
EliahKagan Oct 24, 2023
30f49d9
Revise docstrings/comments in performance tests
EliahKagan Oct 24, 2023
8d3efc5
Remove explicit inheritance from object in test suite
EliahKagan Oct 24, 2023
a5fc1d8
Improve consistency of "END" comments
EliahKagan Oct 24, 2023
c2eb6b5
Add missing comment revisions in git/objects/submodule/base.py
EliahKagan Oct 24, 2023
ddb4417
Improve consistency of "END" comments in test suite
EliahKagan Oct 24, 2023
1d3f275
Avoid making "END" notation more verbose
EliahKagan Oct 30, 2023
81dad7e
Add missing comment revisions in git/index/base.py
EliahKagan Oct 30, 2023
a040edb
Shorten some docstring references with tilde notation
EliahKagan Oct 30, 2023
af1b5d4
Fix commented *.py names at the top of modules
EliahKagan Oct 30, 2023
b970d42
Remove encoding declarations
EliahKagan Oct 30, 2023
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 2 additions & 4 deletions doc/source/conf.py
Original file line number Diff line number Diff line change
@@ -1,6 +1,4 @@
# -*- coding: utf-8 -*-
#
# GitPython documentation build configuration file, created by
# GitPython documentation build configuration file, originally created by
# sphinx-quickstart on Sat Jan 24 11:51:01 2009.
#
# This file is execfile()d with the current directory set to its containing dir.
Expand Down Expand Up @@ -170,7 +168,7 @@
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title, author, document class [howto/manual]).
latex_documents = [
("index", "GitPython.tex", r"GitPython Documentation", r"Michael Trier", "manual"),
("index", "GitPython.tex", "GitPython Documentation", "Michael Trier", "manual"),
]

# The name of an image file (relative to this directory) to place at the top of
Expand Down
3 changes: 1 addition & 2 deletions doc/source/tutorial.rst
Original file line number Diff line number Diff line change
Expand Up @@ -413,7 +413,7 @@ If you obtained your submodule object by traversing a tree object which is not r
you have to inform the submodule about its actual commit to retrieve the data from
by using the ``set_parent_commit(...)`` method.

The special :class:`RootModule <git.objects.submodule.root.RootModule>` type allows you to treat your master repository as root of a hierarchy of submodules, which allows very convenient submodule handling. Its ``update(...)`` method is reimplemented to provide an advanced way of updating submodules as they change their values over time. The update method will track changes and make sure your working tree and submodule checkouts stay consistent, which is very useful in case submodules get deleted or added to name just two of the handled cases.
The special :class:`RootModule <git.objects.submodule.root.RootModule>` type allows you to treat your superproject (master repository) as root of a hierarchy of submodules, which allows very convenient submodule handling. Its ``update(...)`` method is reimplemented to provide an advanced way of updating submodules as they change their values over time. The update method will track changes and make sure your working tree and submodule checkouts stay consistent, which is very useful in case submodules get deleted or added to name just two of the handled cases.

Additionally, GitPython adds functionality to track a specific branch, instead of just a commit. Supported by customized update methods, you are able to automatically update submodules to the latest revision available in the remote repository, as well as to keep track of changes and movements of these submodules. To use it, set the name of the branch you want to track to the ``submodule.$name.branch`` option of the *.gitmodules* file, and use GitPython update methods on the resulting repository with the ``to_latest_revision`` parameter turned on. In the latter case, the sha of your submodule will be ignored, instead a local tracking branch will be updated to the respective remote branch automatically, provided there are no local changes. The resulting behaviour is much like the one of svn::externals, which can be useful in times.

Expand Down Expand Up @@ -545,4 +545,3 @@ And even more ...
There is more functionality in there, like the ability to archive repositories, get stats and logs, blame, and probably a few other things that were not mentioned here.

Check the unit tests for an in-depth introduction on how each function is supposed to be used.

2 changes: 2 additions & 0 deletions git/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -3,8 +3,10 @@
#
# This module is part of GitPython and is released under
# the BSD License: https://opensource.org/license/bsd-3-clause/

# flake8: noqa
# @PydevCodeAnalysisIgnore

from git.exc import * # @NoMove @IgnorePep8
from typing import List, Optional, Sequence, Tuple, Union, TYPE_CHECKING
from git.types import PathLike
Expand Down
373 changes: 192 additions & 181 deletions git/cmd.py

Large diffs are not rendered by default.

13 changes: 7 additions & 6 deletions git/compat.py
Original file line number Diff line number Diff line change
@@ -1,10 +1,11 @@
# -*- coding: utf-8 -*-
# config.py
# compat.py
# Copyright (C) 2008, 2009 Michael Trier (mtrier@gmail.com) and contributors
#
# This module is part of GitPython and is released under
# the BSD License: https://opensource.org/license/bsd-3-clause/
"""utilities to help provide compatibility with python 3"""

"""Utilities to help provide compatibility with Python 3."""

# flake8: noqa

import locale
Expand Down Expand Up @@ -50,7 +51,7 @@ def safe_decode(s: AnyStr) -> str:


def safe_decode(s: Union[AnyStr, None]) -> Optional[str]:
"""Safely decodes a binary string to unicode"""
"""Safely decode a binary string to Unicode."""
if isinstance(s, str):
return s
elif isinstance(s, bytes):
Expand All @@ -72,7 +73,7 @@ def safe_encode(s: AnyStr) -> bytes:


def safe_encode(s: Optional[AnyStr]) -> Optional[bytes]:
"""Safely encodes a binary string to unicode"""
"""Safely encode a binary string to Unicode."""
if isinstance(s, str):
return s.encode(defenc)
elif isinstance(s, bytes):
Expand All @@ -94,7 +95,7 @@ def win_encode(s: AnyStr) -> bytes:


def win_encode(s: Optional[AnyStr]) -> Optional[bytes]:
"""Encode unicodes for process arguments on Windows."""
"""Encode Unicode strings for process arguments on Windows."""
if isinstance(s, str):
return s.encode(locale.getpreferredencoding(False))
elif isinstance(s, bytes):
Expand Down
Loading
Loading