Movatterモバイル変換

[0]ホーム
URL:

Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

 Sign up
Appearance settings

Commitd8ab99c

Browse files
committed
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-parseor ``git rev-parse``or URLs that link directly to a documentation page equivalent to amanpage or that link to the first section where preceding materialis 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 phrasingand the use of hyphens in a small number of cases.Together withc5a29a9, which made such references linkify to the'official online documentation for Git, this makes it so that whengit subcommands are mentioned in docstrings, the Sphinx autodocgenerated documentation in the API Reference page now renders themas links to the relevant documentation page.Links to specific sections where it matters or potentially mattersthat it goes to that section are not replaced. In particular, linksto specific entries in gitglossary(7) are not replaced. To do thisproperly would involve adding a new Sphinx role for it, which wouldwork well in the rendered documentation but could be unclear whenthe documentation is read in docstrings appearing in the code.
1 parente883293 commitd8ab99c

19 files changed

+109
-99
lines changed

‎git/cmd.py

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -901,7 +901,8 @@ def working_dir(self) -> Union[None, PathLike]:
901901
defversion_info(self)->Tuple[int, ...]:
902902
"""
903903
:return: Tuple with integers representing the major, minor and additional
904-
version numbers as parsed from ``git version``. Up to four fields are used.
904+
version numbers as parsed from :manpage:`git-version(1)`. Up to four fields
905+
are used.
905906
906907
This value is generated on demand and is cached.
907908
"""
@@ -1038,9 +1039,9 @@ def execute(
10381039
3. Deeper descendants do not receive signals, though they may sometimes
10391040
terminate as a consequence of their parent processes being killed.
10401041
4. `kill_after_timeout` uses ``SIGKILL``, which can have negative side
1041-
effects on a repository. For example, stale locks in case of ``git gc``
1042-
could render the repository incapable of accepting changes until the lock
1043-
is manually removed.
1042+
effects on a repository. For example, stale locks in case of
1043+
:manpage:`git-gc(1)`could render the repository incapable of accepting
1044+
changes until the lockis manually removed.
10441045
10451046
:param with_stdout:
10461047
If ``True``, default ``True``, we open stdout on the created process.

‎git/config.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -270,7 +270,7 @@ def get_config_path(config_level: Lit_config_levels) -> str:
270270
classGitConfigParser(cp.RawConfigParser,metaclass=MetaParserBuilder):
271271
"""Implements specifics required to read git style configuration files.
272272
273-
This variation behaves much like the``gitconfig`` command, such that the
273+
This variation behaves much like the:manpage:`git-config(1)` command, such that the
274274
configuration will be read on demand based on the filepath given during
275275
initialization.
276276

‎git/diff.py

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -222,8 +222,8 @@ def diff(
222222
to be read and diffed.
223223
224224
:param kwargs:
225-
Additional arguments passed to``gitdiff``, such as ``R=True`` to swap both
226-
sides of the diff.
225+
Additional arguments passed to:manpage:`git-diff(1)`, such as ``R=True`` to
226+
swap bothsides of the diff.
227227
228228
:return:
229229
A :class:`DiffIndex` representing the computed diff.
@@ -590,7 +590,7 @@ def _index_from_patch_format(cls, repo: "Repo", proc: Union["Popen", "Git.AutoIn
590590
The repository we are operating on.
591591
592592
:param proc:
593-
``gitdiff`` process to read from
593+
:manpage:`git-diff(1)` process to read from
594594
(supports :class:`Git.AutoInterrupt <git.cmd.Git.AutoInterrupt>` wrapper).
595595
596596
:return:

‎git/index/base.py

Lines changed: 28 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -225,11 +225,11 @@ def write(
225225
226226
:param ignore_extension_data:
227227
If ``True``, the TREE type extension data read in the index will not be
228-
written to disk. NOTE that no extension data is actually written.
229-
Use thisif you have altered the index and would like to use
230-
``gitwrite-tree`` afterwards to create a tree representing your written
231-
changes. If this data is present in the written index, ``git write-tree``
232-
will instead write the stored/cached tree.
228+
written to disk. NOTE that no extension data is actually written. Use this
229+
if you have altered the index and would like to use
230+
:manpage:`git-write-tree(1)` afterwards to create a tree representing your
231+
writtenchanges. If this data is present in the written index,
232+
:manpage:`git-write-tree(1)`will instead write the stored/cached tree.
233233
Alternatively, use :meth:`write_tree` to handle this case automatically.
234234
"""
235235
# 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
343343
tree, tree 3 is the 'other' one.
344344
345345
:param kwargs:
346-
Additional arguments passed to``gitread-tree``.
346+
Additional arguments passed to:manpage:`git-read-tree(1)`.
347347
348348
:return:
349349
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
355355
automatically resolve more cases in a commonly correct manner. Specify
356356
``trivial=True`` as a keyword argument to override that.
357357
358-
As the underlying``gitread-tree`` command takes into account the current
359-
index, it will be temporarily moved out of the way to prevent any unexpected
360-
interference.
358+
As the underlying:manpage:`git-read-tree(1)` command takes into account the
359+
currentindex, it will be temporarily moved out of the way to prevent any
360+
unexpectedinterference.
361361
"""
362362
iflen(treeish)==0orlen(treeish)>3:
363363
raiseValueError("Please specify between 1 and 3 treeish, got %i"%len(treeish))
@@ -470,10 +470,10 @@ def _write_path_to_stdin(
470470
In that case, it will return ``None``.
471471
472472
:note:
473-
There is a bug in git-update-index that prevents it from sending reports
474-
just in time. This is why we have a version that tries to read stdout and
475-
one which doesn't. In fact, the stdout is not important as the piped-in
476-
files are processed anyway and just in time.
473+
There is a bug in:manpage:`git-update-index(1)` that prevents it from
474+
sending reportsjust in time. This is why we have a version that tries to
475+
read stdout andone which doesn't. In fact, the stdout is not important as
476+
the piped-infiles are processed anyway and just in time.
477477
478478
:note:
479479
Newlines are essential here, git's behaviour is somewhat inconsistent on
@@ -782,11 +782,12 @@ def add(
782782
directories like ``lib``, which will add all the files within the
783783
directory and subdirectories.
784784
785-
This equals a straight``gitadd``.
785+
This equals a straight:manpage:`git-add(1)`.
786786
787787
They are added at stage 0.
788788
789-
- :class:~`git.objects.blob.Blob` or :class:`~git.objects.submodule.base.Submodule` object
789+
- :class:~`git.objects.blob.Blob` or
790+
:class:`~git.objects.submodule.base.Submodule` object
790791
791792
Blobs are added as they are assuming a valid mode is set.
792793
@@ -818,8 +819,8 @@ def add(
818819
:param force:
819820
**CURRENTLY INEFFECTIVE**
820821
If ``True``, otherwise ignored or excluded files will be added anyway. As
821-
opposed to the``gitadd`` command, we enable this flag by default as the
822-
API user usually wants the item to be added even though they might be
822+
opposed to the:manpage:`git-add(1)` command, we enable this flag by default
823+
as theAPI user usually wants the item to be added even though they might be
823824
excluded.
824825
825826
:param fprogress:
@@ -850,8 +851,8 @@ def add(
850851
:param write_extension_data:
851852
If ``True``, extension data will be written back to the index. This can lead
852853
to issues in case it is containing the 'TREE' extension, which will cause
853-
the``gitcommit`` command to write an old tree, instead of a new one
854-
representing the now changed index.
854+
the:manpage:`git-commit(1)` command to write an old tree, instead of a new
855+
onerepresenting the now changed index.
855856
856857
This doesn't matter if you use :meth:`IndexFile.commit`, which ignores the
857858
'TREE' extension altogether. You should set it to ``True`` if you intend to
@@ -1008,8 +1009,8 @@ def remove(
10081009
uncommitted changes in it.
10091010
10101011
:param kwargs:
1011-
Additional keyword arguments to be passed to``git rm``, such as ``r`` to
1012-
allow recursive removal.
1012+
Additional keyword arguments to be passed to:manpage:`git-rm(1)`, such as
1013+
``r`` toallow recursive removal.
10131014
10141015
:return:
10151016
List(path_string, ...) list of repository relative paths that have been
@@ -1058,7 +1059,7 @@ def move(
10581059
skipped.
10591060
10601061
:param kwargs:
1061-
Additional arguments you would like to pass to``git mv``, such as
1062+
Additional arguments you would like to pass to:manpage:`git-mv(1)`, such as
10621063
``dry_run`` or ``force``.
10631064
10641065
:return:
@@ -1224,7 +1225,7 @@ def checkout(
12241225
prior and after a file has been checked out.
12251226
12261227
:param kwargs:
1227-
Additional arguments to be passed to``gitcheckout-index``.
1228+
Additional arguments to be passed to:manpage:`git-checkout-index(1)`.
12281229
12291230
:return:
12301231
Iterable yielding paths to files which have been checked out and are
@@ -1243,8 +1244,8 @@ def checkout(
12431244
The checkout is limited to checking out the files in the index. Files which
12441245
are not in the index anymore and exist in the working tree will not be
12451246
deleted. This behaviour is fundamentally different to ``head.checkout``,
1246-
i.e. if you want``gitcheckout``like behaviour, use ``head.checkout``
1247-
instead of ``index.checkout``.
1247+
i.e. if you want:manpage:`git-checkout(1)`-like behaviour, use
1248+
``head.checkout``instead of ``index.checkout``.
12481249
"""
12491250
args= ["--index"]
12501251
ifforce:
@@ -1416,14 +1417,14 @@ def reset(
14161417
raised.
14171418
14181419
:param kwargs:
1419-
Additional keyword arguments passed to``gitreset``.
1420+
Additional keyword arguments passed to:manpage:`git-reset(1)`.
14201421
14211422
:note:
14221423
:meth:`IndexFile.reset`, as opposed to
14231424
:meth:`HEAD.reset <git.refs.head.HEAD.reset>`, will not delete any files in
14241425
order to maintain a consistent working tree. Instead, it will just check out
14251426
the files according to their state in the index.
1426-
If you want``gitreset``-like behaviour, use
1427+
If you want:manpage:`git-reset(1)`-like behaviour, use
14271428
:meth:`HEAD.reset <git.refs.head.HEAD.reset>` instead.
14281429
14291430
:return:

‎git/index/typ.py

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -130,8 +130,7 @@ def stage(self) -> int:
130130
* 3 = stage of entries from the 'right' side of the merge
131131
132132
:note:
133-
For more information, see:
134-
http://www.kernel.org/pub/software/scm/git/docs/git-read-tree.html
133+
For more information, see :manpage:`git-read-tree(1)`.
135134
"""
136135
return (self.flags&CE_STAGEMASK)>>CE_STAGESHIFT
137136

‎git/objects/base.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -45,7 +45,7 @@ class Object(LazyMixin):
4545
* :class:`Commit <git.objects.commit.Commit>`
4646
* :class:`TagObject <git.objects.tag.TagObject>`
4747
48-
See gitglossary(7) on:
48+
See:manpage:`gitglossary(7)` on:
4949
5050
* "object": https://git-scm.com/docs/gitglossary#def_object
5151
* "object type": https://git-scm.com/docs/gitglossary#def_object_type

‎git/objects/blob.py

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,8 @@
1919
classBlob(base.IndexObject):
2020
"""A Blob encapsulates a git blob object.
2121
22-
See gitglossary(7) on "blob": https://git-scm.com/docs/gitglossary#def_blob_object
22+
See :manpage:`gitglossary(7)` on "blob":
23+
https://git-scm.com/docs/gitglossary#def_blob_object
2324
"""
2425

2526
DEFAULT_MIME_TYPE="text/plain"

‎git/objects/commit.py

Lines changed: 12 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -65,7 +65,7 @@
6565
classCommit(base.Object,TraversableIterableObj,Diffable,Serializable):
6666
"""Wraps a git commit object.
6767
68-
See gitglossary(7) on "commit object":
68+
See:manpage:`gitglossary(7)` on "commit object":
6969
https://git-scm.com/docs/gitglossary#def_commit_object
7070
7171
:note:
@@ -269,8 +269,9 @@ def count(self, paths: Union[PathLike, Sequence[PathLike]] = "", **kwargs: Any)
269269
actually containing the paths.
270270
271271
:param kwargs:
272-
Additional options to be passed to ``git rev-list``. They must not alter the
273-
output style of the command, or parsing will yield incorrect results.
272+
Additional options to be passed to :manpage:`git-rev-list(1)`. They must not
273+
alter the output style of the command, or parsing will yield incorrect
274+
results.
274275
275276
:return:
276277
An int defining the number of reachable commits
@@ -307,14 +308,14 @@ def iter_items(
307308
The :class:`~git.repo.base.Repo`.
308309
309310
:param rev:
310-
Revision specifier. See git-rev-parse for viable options.
311+
Revision specifier. See:manpage:`git-rev-parse(1)` for viable options.
311312
312313
:param paths:
313314
An optional path or list of paths. If set only :class:`Commit`\s that
314315
include the path or paths will be considered.
315316
316317
:param kwargs:
317-
Optional keyword arguments to``gitrev-list`` where:
318+
Optional keyword arguments to:manpage:`git-rev-list(1)` where:
318319
319320
* ``max_count`` is the maximum number of commits to fetch.
320321
* ``skip`` is the number of commits to skip.
@@ -353,7 +354,7 @@ def iter_parents(self, paths: Union[PathLike, Sequence[PathLike]] = "", **kwargs
353354
contain at least one of the paths.
354355
355356
:param kwargs:
356-
All arguments allowed by``gitrev-list``.
357+
All arguments allowed by:manpage:`git-rev-list(1)`.
357358
358359
:return:
359360
Iterator yielding :class:`Commit` objects which are parents of ``self``
@@ -404,7 +405,7 @@ def trailers_list(self) -> List[Tuple[str, str]]:
404405
"""Get the trailers of the message as a list.
405406
406407
Git messages can contain trailer information that are similar to RFC 822 e-mail
407-
headers (see: https://git-scm.com/docs/git-interpret-trailers).
408+
headers. See :manpage:`git-interpret-trailers(1)`.
408409
409410
This function calls ``git interpret-trailers --parse`` onto the message to
410411
extract the trailer information, returns the raw trailer data as a list.
@@ -456,7 +457,7 @@ def trailers_dict(self) -> Dict[str, List[str]]:
456457
"""Get the trailers of the message as a dictionary.
457458
458459
Git messages can contain trailer information that are similar to RFC 822 e-mail
459-
headers (see: https://git-scm.com/docs/git-interpret-trailers).
460+
headers. See :manpage:`git-interpret-trailers(1)`.
460461
461462
This function calls ``git interpret-trailers --parse`` onto the message to
462463
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,
499500
from our lighting fast object database.
500501
501502
:param proc:
502-
``gitrev-list`` process instance - one sha per line.
503+
:manpage:`git-rev-list(1)` process instance - one sha per line.
503504
504505
:return:
505506
Iterator supplying :class:`Commit` objects
@@ -596,8 +597,8 @@ def create_from_tree(
596597
597598
:note:
598599
Additional information about the committer and author are taken from the
599-
environment or from the git configuration. See git-commit-tree for more
600-
information.
600+
environment or from the git configuration. See:manpage:`git-commit-tree(1)`
601+
for moreinformation.
601602
"""
602603
ifparent_commitsisNone:
603604
try:

‎git/objects/submodule/base.py

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -342,7 +342,7 @@ def _clone_repo(
342342
Allow unsafe options to be used, like ``--upload-pack``.
343343
344344
:param kwargs:
345-
Additional arguments given to``gitclone``.
345+
Additional arguments given to:manpage:`git-clone(1)`.
346346
"""
347347
module_abspath=cls._module_abspath(repo,path,name)
348348
module_checkout_path=module_abspath
@@ -463,10 +463,10 @@ def add(
463463
It will be created as required during the repository initialization.
464464
465465
:param url:
466-
git-clone compatible URL, seegit-clone referencefor more information.
467-
If ``None``, the repository is assumed to exist, and theurl of the first
468-
remote is taken instead. This is useful if you want to make an existing
469-
repository a submodule of another one.
466+
``gitclone...``-compatible URL. See :manpage:`git-clone(1)`for more
467+
information.If ``None``, the repository is assumed to exist, and theURL of
468+
the firstremote is taken instead. This is useful if you want to make an
469+
existingrepository a submodule of another one.
470470
471471
:param branch:
472472
Name of branch at which the submodule should (later) be checked out. The
@@ -696,7 +696,7 @@ def update(
696696
its value.
697697
698698
:param clone_multi_options:
699-
List of``gitclone`` options.
699+
List of:manpage:`git-clone(1)` options.
700700
Please see :meth:`Repo.clone <git.repo.base.Repo.clone>` for details.
701701
They only take effect with the `init` option.
702702

‎git/objects/tag.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -37,7 +37,7 @@ class TagObject(base.Object):
3737
"""Annotated (i.e. non-lightweight) tag carrying additional information about an
3838
object we are pointing to.
3939
40-
See gitglossary(7) on "tag object":
40+
See:manpage:`gitglossary(7)` on "tag object":
4141
https://git-scm.com/docs/gitglossary#def_tag_object
4242
"""
4343

‎git/objects/tree.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -168,7 +168,7 @@ class Tree(IndexObject, git_diff.Diffable, util.Traversable, util.Serializable):
168168
R"""Tree objects represent an ordered list of :class:`~git.objects.blob.Blob`\s and
169169
other :class:`Tree`\s.
170170
171-
See gitglossary(7) on "tree object":
171+
See:manpage:`gitglossary(7)` on "tree object":
172172
https://git-scm.com/docs/gitglossary#def_tree_object
173173
174174
Subscripting is supported, as with a list or dict:

‎git/refs/head.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -89,7 +89,7 @@ def reset(
8989
that are to be reset. This allows to partially reset individual files.
9090
9191
:param kwargs:
92-
Additional arguments passed to``gitreset``.
92+
Additional arguments passed to:manpage:`git-reset(1)`.
9393
9494
:return:
9595
self

‎git/refs/symbolic.py

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -173,8 +173,7 @@ def dereference_recursive(cls, repo: "Repo", ref_path: Union[PathLike, None]) ->
173173
def_check_ref_name_valid(ref_path:PathLike)->None:
174174
"""Check a ref name for validity.
175175
176-
This is based on the rules described in:
177-
https://git-scm.com/docs/git-check-ref-format/#_description
176+
This is based on the rules described in :manpage:`git-check-ref-format(1)`.
178177
"""
179178
previous:Union[str,None]=None
180179
one_before_previous:Union[str,None]=None

‎git/refs/tag.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -124,7 +124,7 @@ def create(
124124
If ``True``, force creation of a tag even though that tag already exists.
125125
126126
:param kwargs:
127-
Additional keyword arguments to be passed to``gittag``.
127+
Additional keyword arguments to be passed to:manpage:`git-tag(1)`.
128128
129129
:return:
130130
A new :class:`TagReference`.

0 commit comments

Comments
 (0)
[8]ページ先頭
©2009-2025 Movatter.jp