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

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

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 ourterms of service andprivacy statement. We’ll occasionally send you account related emails.

Already on GitHub?Sign in to your account

Merged
Byron merged 36 commits intogitpython-developers:mainfromEliahKagan:strings
Oct 30, 2023

Conversation

EliahKagan
Copy link
Member

@EliahKaganEliahKagan commentedOct 30, 2023•
edited
Loading

This revises comments and docstrings, to improve clarity, readability, stylistic consistency, in some cases accuracy, and (for docstrings) Sphinx formatting and cross-linking. It also contains a few other related changes.

Short summary of the most notable changes

In both comments and docstrings, my changes included rewording for clarity, as well as changes in capitalization, punctuation, and so forth.

For comments, which were in a variety of styles, I converted them to be sentences (or in some cases fragments formatted as sentences), except in a minority of cases when doing so seemed like it would worsen readability. I did this because, in addition to improving stylistic consistency and being encouraged by PEP-8, this tended to make their structure clearer (especially in cases of comments over multiple lines that were convertible to multiple separate sentences). This comment style was also one of the styles already represented throughout the codebase.

For docstrings, there were a number of places where the formatting looked one way when reading the raw docstring, but very different, and arguably less readable, as rendered by Sphinx. In cases where this was clearly unintended and the effect was significant, such as markup that was intended to represent an unordered list but instead represented a running paragraph with literal asterisks, I fixed the formatting. In cases where the intent was less clear, such as non-wrapping newlines conveying a break more major than that between sentences but less major than that between paragraphs, I preserved the style where possible but did not make changes to cause it to be newly reflected in rendered documentation.

Kinds of other changes

There are also some other changes, described below, including somecode changes, mainly for clarity, that I believe to be sufficiently related or where there is otherwise a reason to include them here rather than proposing them separately.

Some specific changes (not to code) are described in commit messages but not this PR description, but this is noted below. Specifically, a handful of changes to docstrings are for accuracy, and to allow them to carry specific rationales and to be reviewed individually, they each have individual commits and are not currently relisted here.

Line length in docstrings

I found that many docstrings were already written, or almost entirely written, with a hard wrap of 88 columns. It makes sense that this would be done, because it is theblack default, even thoughblack does not enforce line length in docstrings, and furthermore the maximum line length this this project has been set at the much higher 120 columns. I think that a width of 120, or even 100, in docstrings, reduces readability when reading the docstrings in the code (of course it does not affect what Sphinx renders), so this is probably another reason a smaller width was used in most cases.

Where width was consistent, as well as where making it consistent didn't seem like it would improve readability, I left it alone. Otherwise, I prioritized consistency within each docstring and with nearby docstrings, but overall (when making changes that would justify it) preferred the prevailing 88 column width. To amuch lesser extent, I preferred a width of 88 columns for comments, but only where that style was otherwise being used. I did not format code to make it narrower. We may want to reduce theblack maximum line length from 120 to 100 or even the default of 88, but I definitely would consider that beyond the scope of this PR.

Documentation generated from tests

This includes changes to comments in portions of the two test modules from which documentation is generated. This is not special, but I wanted to note it here to properly characterize what parts of the generated documentation are and are not affected.

Other documentation - only one small change

Although most of the the docstring changes affect generated documentation, and the documentation indoc/ should also be revised and updated (and in some places stands to benefit more from such changes than anything here), the purpose of this pull request is not to revise or update the separate documentation indoc/.

This does include one change to the contents ofdoc/, to avoid introducing an inconsistency when rewording a docstring for clarity whose wording was also used in the tutorial. Other that that and a change inconf.py, it does not modify any tracked files indoc/.

How the changes are divided into commits

Formatting, rewording, and style changes such as to capitalization and punctuation, as well as the repair and introduction of Sphinx cross-linking changes and code-formatting changes (such as placing every multi-paragraph docstring's closing""" on its own line) are done in a small number of commits, most pertaining to organizational sections of the code.

In contrast, accuracy improvements, even though they account for a much smaller volume of change, are each done in their own commit, so they can havecommit messages that explain their rationale and to make them easier to review.

Although I had considered describing each of those changes here, I have not thought of a way to do so that I think would clearly be more useful than the commit messages themselves. Furthermore, this description is already rather long. So I have not reproduced that information here. However, I would be pleased to expand this PR description on request, either about that or in other ways.

What is omitted

In areas where accuracy might be improved but it is unclear how, or where reviewing the changes seems like it would be easier done separately, or where the changes should be accompanied by code changes that themselves are not natural to include here, I have omitted such changes entirely from this pull request. (One such area I discovered while working on this but did not include in it was#1712, which I instead fixed in#1714.)

The changes in this PR are probably incomplete, in the sense that I most likely have missed some things.

In some areas, I have avoided making changes that I anticipate would create conflicts, or other confusion, with work I have on other feature branches that I plan to open PRs for soon. In practice, the only major omission that arises due to this is intest/test_util.py, which is mostly unrevised since I intend to propose changes there soon, for makingxfail markings more precise, that will involve reorganizing that code.

Changes to code

Finally, please note thatthis PR does contain some code changes. They are as follows:

  • A few messages, such as exception messages, are revised. I avoided doing this except when I thought it was a clear improvement and would not cause problems. When accuracy was the motivation, such a change has its own commit (as do other accuracy changes).
  • Some string literals are changed, so that the use of raw string literals is consistent (for regular expressions and for Windows paths notending in a backslash, and withr andR respectively). Commit messages contain further information about this. Conceptually, I felt this came along with fixing docstring bugs where'\' was intended to represent itself literally but instead represented'' because a non-raw docstring turned\' into'. There is also an argument to be made that strings are the core concept of this pull request (hence the branch name).
  • Explicit inheritance fromobject is removed. This is a legacy of Python 2, where it was needed to make a new-style class. This project no longer supports (and is already considerably incompatible with) Python 2, and in Python 3 all classes are new-style classes. The reason this is a clarity improvement sufficiently related to documentation that it seemed appropriate to include here is that GitPython has anObject class that could be confused withobject.
  • Expressions of the formx.__class__ == t are changed tox.__class__ is t. In#1673, I fixed the corresponding problem fortype(x) == t, butflake8 does not detect the.__class__ variant. The reason this change isconvenient here is that most of these changes were on the same or an adjacent line to something I was already changing, so making them separately would in most cases have incurred a conflict. But the reason I think it'sreasonable to include this here is that a number of GitPython's objects havetype attributes that pertain to Git and GitPython's data model rather than to the Python object model, and that hold strings that are (correctly) compared with==. Comparingx.__class__ withis, as the relatedtype(x) is compared but as the unrelatedx.type is not compared, makes the distinction easier to heed, I think.
  • Python permits__slots__ = "slot" for a single slotslot, but it is discouraged in preference for__slots__ = ("slot",), which was already being done in most cases. I fixed the few occurrences of the former to bring them in line with that.

Although readability would be further improved by replacing two-argumentsuper calls with zero-argumentsuper()--which is also something Python 3 adds that is related to new-style classes and thus arguably beckoned by those last three bullet points--I have omitted this. The reason is that this change would require special attention in review to ensure that it is only done in cases where the meaning of the code is not changed. (That is likely every occurrence ofsuper in the whole repository, but they would still have to be checked individually.)

This intended '\' literally, but it was actually '' because the \'became just ' (backslash-apostrophe becomes just aspostrophe).
This improves consistency, because most were already. For a few itallows backslashes to removed, improving readability. Even for theothers, some editors will highlight them as regular expressions nowthat they are raw string literals.
These are a couple strings that, in addition to not having anyescape sequences, don't represent regular expressions, Windowspaths, or anything else that would be clarified by raw literals.
In the git.diff.Diff class, the _index_from_patch_format and_index_from_raw_format methods' docstrings had still described themas reading from streams, even though they have instead read fromprocesses (and taken "proc", not "stream", arguments) sincegitpython-developers#519when the change was made ina5db3d3 to fix a freezing bug.This updates the docstrings to reflect that they read fromprocesses.
The message refers to the (public) working_tree_dir attribute byname, so that should be uncapitalized to reflect the case by whichit must be accessed, even when it appears at the beginning of asentence.
The git.objects.commit.Commit._deserialize method stopped acceptinga param_from_rev_list argument inae5a69f, but the documentationfor that parameter was never removed.Because that was the only part of the method's docstring, and it isa nonpublic method, and the associated _serialize method does nothave a docstring, this change simply removes the _deserializemethod's docstring without adding anything.
The local (i.e. late) import was removed in7b3ef45, but thecomment about it on (what was) the preceding line has persisteduntil now.
This changes    master repositoryto    superproject (master repository)in the RootModule class docstring and in the tutorial, to make evenclearer what this is referring to. This way, users who are lessfamiliar with submodules will be less likely to confuse this witha "master" branch (since "master" is one of the popular defaultbranch names), while users who are more familiar with submodulesand may search for the official term "superproject" will find thedocs when doing so.This retains "master repository" parenthesized rather thancompletely replacing it because although "superproject" is theofficial term for this, it is a bit obscure and unintuitive.
Since the hyphen spelling is what the official Git docs use.This change affects only docstrings.
Reference.set_object explains its handling of oldbinsha by quotinga comment from refs.c in the Git source code. However, that commentnow appears in refs/files-backend.c in that codebase. This updatesthe reference so readers can look it up and find the comment in itssurrounding context.The commit to the git project's source code that moved the codethat includes that comment is:git/git@7bd9bcf
This rarely-seen ValueError message had said SymbolicRef, and isnow changed to SymbolicReference.
Since the value of __class__ is a type, comparing it to anothertype object should use "is" rather than "==".Some of these, involving type(), were fixed inbf7af69, but flake8did not catch the .__class__ variation addressed here.
In the git module (including the modules it contains).This also makes one small change in doc/ to synchronize with achange made in a docstring.
The is_cygwin_git function returns False when we have is_win,because is_win is not True on Cygwin systems. The existing commentexplained why, but was tentative. The claims are accurate, so thisrewrites the comment to state it more definitively.
Within the git module.In Python 2, it was necessary to inherit from object to have anew-style class. In Python 3, all classes are new-style classes,and inheritance from object is implied.Usually, removing explicit inheritance from object is only a smallclarity benefit while modernizing Python codebases. However, inGitPython, the benefit is greater, because it is possible toconfuse object (the root of the Python class hierarchy) withObject (the root of the GitPython subhierarchy of classesrepresenting things in the git object model).
Most already were, but a few were strings.
Intentionally untouched test modules in this commit:- Modules where there are no such changes to be made.- Modules in test/performance/ -- will be done separately.- test/lib/ modules (these are test *helpers* and will be done  separately).- test/test_util.py, because although it has a few comments that  might be improved, it may make more sense to do that together  with some further refactoring changes.
It benefits from a docstring because it is not referenced in codeor documentation, and its purpose is/was otherwise unclear.The docstring includes a reference togitpython-developers#1188 for more information.
This modifies content of the strings themselves, but only slightly.- Make an exception message more readable.- Improve spacing of the "python -c" script string in the sys.path  test.
This futher improves some wording in docstrings and comments in ahandful of places within the git module.
:return: was used extensively, while :returns: only appeared in twodocstrings.
Changes that fix the message itself:- Add a missing space between words (two parts were concatenated,  with no space at the edge of either).- Capitalize "GitPython" since that is the repo and project name.Changes that improve how the message is produced:- Make the entire literal part of the string the format string,  instead of formatting the first part and concatenating the second  part.- Pass the format string and k_env_git_repo variable as separate  arguments to logging.info, so the logging machinery takes care of  substituting it for %s, rather than doing the substitution.
This removes the Windows-specific information in the warningmessage in git_daemon_launched.After the associated functionality was updated ingitpython-developers#1684 and thewarning message was abridged accordingly, the functionality wasupdated again ingitpython-developers#1697, causing the message to be outdated and nolonger helpeful (since having git-daemon.exe in a PATH directory isno longer necessary or useful), without any corresponding change tothe message.
In the git module (including modules it contains).This does not add any new "# end" or "# END" comments. Instead, itimproves the consistency and clarity of existing ones by convertingeach "# end" comment to "# END" (since capitalization was not usedsystematically to indicate nesting level or other semanticinformation, and capitalizing "END" makes clear the nature of thecomment), and by adding some information to a few of the comments.This also removes end comments that did not provide information orsignificant visual indication that a "section" was ending, or wherethe visual indication they provided was at least as well providedby replacing them with a blank line. However, it does *not* attemptto apply this change everywhere it might be applicable.
@Byron
Copy link
Member

Thanks! However, this was more straightforward than it might seem. Rather than operating from any kind of comprehensive knowledge of the documentation, I instead read "master repository" in the docstring and thought it might be clearer if written with the official term included, as "superproject (master repository)".

I am glad there is an alternative explanation, and one that makes you appear less like a brand-new AI that is being tested undercover ;).

I'm not sure there's any way to do that fully, because the description and comments on pull requests and issues can change at any time, including after they are merged/closed.

Depending on what the tool should be like, one can probably start with archived projects to be sure they (most probably) won't change. However, I also think that this should be more like a 'sync' that will pick up changes since the last sync. Maybe this can even allow to 'sync back' certain changes for a two-way connection. Of course, there is a lot of unknowns right now, I am merely dreaming something up 😁.

It would be useful for building public repositories representing "slices" of valuable content.

I really like that idea, and think that once frameworks exists that make certain 'sync' operations tenable it's possible to implement this for various sources without going crazy.

[..] from the email attachment history, with fairly uninformative but better-than-nothing auto-generated commit messages, with one commit per relevant email message.)

By that time it might even be straightforward enough to run it through a local transformer for actually useful summaries, and maybe more (like intelligence extractions based on a large context window).

As a more limited move, and something that might be worthwhile here, it should be feasible to make a bot, or even a browser extension or user script, that merges a pull request on GitHub and populates the merge commit message with the entire content of the pull request description.

That would be a super interesting application of a bot or browser plugin, and I'd not even be that surprised if it already existed somewhere. Whether it's worthwhile or 'good enough', I am also uncertain about.

As for solving the full problem of making all collaboration on public Git repositories accessible as close as possible to everywhere, and fully integrated, maybe something like ActivityPub would be needed? I'm interested in your thoughts about this, but I acknowledge it might be off-topic here or even for GitPython as a whole. I think this kind of integration is something you've mentioned is, or is in some way related to, an eventual aim of gitoxide, but I don't remember where or if you said that, and I may have misunderstood. If this is an eventual aim of gitoxide, then I could open a discussion thread about it there, but I don't want to assume that.

gitoxide would only serve asgit implementation, and as such can be used to use git repositories as storage for such 'sync engines'. One could already do that today. Such a system, however, would definitely be a separate project and it's one in the far-future for me. If you would want to usegitoxide for something like it though, you are welcome to open a discussion there of course and we see where it leads.

Thanks! I'm not sure what I would do in gitoxide, which doesn't seem to need changes analogous to the ones I've been making here since it is a modern project. Also, although I will eventually be learning Rust, I don't know it currently.

I'd be happy to support you if you were to learn Rust by implementing a feature ingitoxide, no matter how small. Learning by doing, if you will.

Although people use git information from shell prompts to make assumptions that, if wrong, could lead to data loss, it seems to me that, at least afterByron/gitoxide#1049, gitoxide would be fully ready for this use.

Yes, havinggix status will open up a lot of additional uses and will allowstarship to finally stop usinggit and be much faster in doing what it does :D.
I wouldn't recommend usinggix for it though as it's a forever-unstable developer tool, which really doesn't want to begit, but simply assuresgix (the crate) would support something very close to that (i.e. a drop-in replacement). What onewould want to do though is to write a prompt-generating program in Rust that usesgix (the crate) to emit the prompt as needed. Such a program already exists: [starship`](https://starship.rs) .

I bring this up because, if that functionality is not available but would be considered useful, then I might be interested in contributing it--though if someone else did so first then I would be only happy and could still potentially contribute improvements related to it. Other than that, I haven't thought of anything I would be able to contribute to gitoxide. I think it could be done all in the shell scripting languages whose interpreters' operation it would affect, or perhaps partly or mostly in Rust. I'm unsure if this should go in the gitoxide repository itself, or elsewhere, especially if it ends up being written entirely in the shell languages it targets. Also, if this feature does exist and I just didn't find it when searching, my apologies!

There is a tool that one dayshould be stable, and that isein.ein is meant to be the opposite ofgit and completely rethink how one interacts with agit repository - the basic idea is to support agit workflow that is easy to understand, while still familiar to typicalgit users like me, but with the best possible user experience.

ein does havetools, which I already use regularly or have integrated into myzsh via the very simple

select-repo () {local root=~/devecho -n$root/        {cd$root                ein --quiet t find        }| sk -q"$1"}

so I can jump into repositories by fuzzy-searching them.

And there is more. Maybe that's where one could add a tool that you always wanted and that coincidentally other may want too.

(In addition, I was working on this for small amounts of time accumulated over many days, so having these be separate commits was useful for enabling myself to know what was going on.)

It sounds like you are working with some sort of patch queue - if so, which one? I useStacked Git.

However, since you seem to be okay with it, I'd be pleased to restate less information from commit messages into PRs, as that makes the PRs faster to write.

I think that will be a win-win-win! The third 'win' is for more of the rationale and reasoning going intogit, possibly, which keeps it for posterity (as long the 'sync engine' isn't available that is ;)).

However, if this downside is considered acceptable, then I would be willing to do this at least somewhat more often.

Please do also optimize for whatever you think is best, contributing shouldn't be a chore and I'd never want to turn it into one. I admittedly also can't perform review the way I want, as GitHub doesn't make it easy to see which commit contributed to the final result that I am looking at. I also don't review commit by commit, which means I don't usually see or read all commit messages. This is solely a tooling issue though :/, and yes, one day I want to fix that too 😁.

Obviously this runs up against scale problems--in excess, it would hamper collaboration--but even then, each of the sub-ideas of a big idea can benefit from experimentation.

On top of what was already said, it does seem like a tooling issue maybe, or maybe I just misunderstand this entirely. But again, ideally making contributions is fun and I want to do my part to help with that.

Should this be done in gitdb and smmap as well?

I'd consider that a chore as both ideally go away at some point - if there is a breaking change I'd consider, this would be one of them. The other one would have to do withgitoxide integration, but that's me dreaming again.

With that said, I did notice some opportunities for further PRs, which I hope to open. :)

😁❤️🙏

@EliahKagan
Copy link
MemberAuthor

I'd be happy to support you if you were to learn Rust by implementing a feature ingitoxide, no matter how small. Learning by doing, if you will.

Thanks! There is a substantial chance I will want to do that.

What onewould want to do though is to write a prompt-generating program in Rust that usesgix (the crate) to emit the prompt as needed. Such a program already exists: [starship`](https://starship.rs) .

Yes, I believe that is what I'm looking for!

It sounds like you are working with some sort of patch queue - if so, which one? I useStacked Git.

Actually, I am unfamiliar with patch queues. I work on multiple features on multiple branches, and I use stashes, often amend my most recent commit on a feature branch, sometimes rebase, and occasionally cherry-pick. I use various tools to examine repositories, but for performing mutations I just use the availablegit commands, in nearly all cases.

On top of what was already said, it does seem like a tooling issue maybe, or maybe I just misunderstand this entirely.

Perhaps so. In particular, if interactive rebases were extremely fast and easy, I might use them to disseminate insights into commit messages more often. The main feature I might want for this, especially if most information were in commit messages rather than pull requests but really there are many reasons I want this, is automatic rewriting of commit hashes, at least for references to ancestors. If X is on a feature branch, and Y is a descendant of it on the same feature branch, and Y's message refers to X by hash, and I rebase that feature branch onto some ancestor of X (changing X's hash), it would be nice to have an easy way for the reference in Y's commit message to be updated to the new X. Of course there are various edge cases, since there is not always exactly one commit that corresponds to the old X after a rebase.

Should this be done in gitdb and smmap as well?

I'd consider that a chore as both ideally go away at some point - if there is a breaking change I'd consider, this would be one of them. The other one would have to do withgitoxide integration, but that's me dreaming again.

I don't follow. What I mean to ask here is merely if uses of two-argumentsuper ingitdb andsmmap should also be changed to use zero-argumentsuper(). If so, it might make sense to also do things like remove explicit inheritance from theobject builtin, but I'm not talking about any breaking changes, only changes that keep semantics the same.

Byron reacted with heart emoji

@Byron
Copy link
Member

Perhaps so. In particular, if interactive rebases were extremely fast and easy, I might use them to disseminate insights into commit messages more often. The main feature I might want for this, especially if most information were in commit messages rather than pull requests but really there are many reasons I want this, is automatic rewriting of commit hashes, at least for references to ancestors. If X is on a feature branch, and Y is a descendant of it on the same feature branch, and Y's message refers to X by hash, and I rebase that feature branch onto some ancestor of X (changing X's hash), it would be nice to have an easy way for the reference in Y's commit message to be updated to the new X. Of course there are various edge cases, since there is not always exactly one commit that corresponds to the old X after a rebase.

I truly think you should giveStacked Git a try then, even though it's not the only tool that can help. I am using it myself for nearly a year now and it transformed my workflow from 'one commit per change, record a history of all changes' to 'craft commits by topic or category, and keep updating them, going back and forth in the stack'. It's probably what you do with a rebase-amend workflow already, butStacked Git is more convenient.

As for the commit-rewrite feature, I am sure you could propose it there or contribute it yourself at some point, it seems very doable.

I don't follow. What I mean to ask here is merely if uses of two-argumentsuper ingitdb andsmmap should also be changed to use zero-argumentsuper(). If so, it might make sense to also do things like remove explicit inheritance from theobject builtin, but I'm not talking about any breaking changes, only changes that keep semantics the same.

Apologies for causing confusion. I ttried to say that since I'd rather want to removegitdb andsmmap entirely it's probably not worth putting anymore time in it than is needed to keep it from falling apart. From my experience, these are very stable as well, so that should be fine.

EliahKagan reacted with thumbs up emoji

EliahKagan added a commit to EliahKagan/GitPython that referenced this pull requestNov 3, 2023
This removes a comment noting that a try-finally block had beenpresent (or had been intended), but was removed because someversion of Python had imposed a limitation on yield appearing intry-finally.That comment was obsolete as of58c5b99 (gitpython-developers#326), which wrapped therelevant code in a with-statement, because:1. Since then, the cleanup is done in a manner equivaent to   try-finally.2. It turned out, as noted in that PR, that cleanup had not   always been done automatically. (This was contrary to the   prediction given in the comment.)3. At some point before that, the limitation that had prevented   the use of try-finally no longer affected any supported version   of Python.   Specifically, it appears the only limitation that this could be   was the limitation lifted in Python 2.5, where along with the   addition of the close() method which causes try-finally to be   called (and is itself called when a generator object is   finalized), yield in a try-block with an associated   finally-block became permitted, since the call to close() was   sufficient to run the finally-block (by raising GeneratorExit).   For details, see:https://docs.python.org/3/whatsnew/2.5.html#pep-342-new-generator-features(This obsolete comment was one of the things I discovered whileworking ongitpython-developers#1725, but I didn't include this change there, havingnot yet looked into the history of the code enough to be sure.)
EliahKagan added a commit to EliahKagan/GitPython that referenced this pull requestNov 3, 2023
This removes a comment noting that a try-finally block had beenpresent (or had been intended), but was removed because someversion of Python had imposed a limitation on yield appearing intry-finally.That comment was obsolete as of58c5b99 (gitpython-developers#326), which wrapped therelevant code in a with-statement, because:1. Since then, the cleanup is done in a manner equivaent to   try-finally.2. It turned out, as noted in that PR, that cleanup had not   always been done automatically. (This was contrary to the   prediction given in the comment.)3. At some point before that, the limitation that had prevented   the use of try-finally no longer affected any supported version   of Python.   Specifically, it appears the only limitation that this could be   was the limitation lifted in Python 2.5, where along with the   introduction of close(), which is automatically called when a   generator object is finalized, it became permitted for yield to   appear in a try-block with an associated finally-block, on the   grounds that calling close() runs the finally-block (by raising   GeneratorExit).   For details, see:https://docs.python.org/3/whatsnew/2.5.html#pep-342-new-generator-features(This obsolete comment was one of the things I discovered whileworking ongitpython-developers#1725, but I didn't include this change there, havingnot yet looked into the history of the code enough to be sure.)
EliahKagan added a commit to EliahKagan/GitPython that referenced this pull requestDec 22, 2023
EliahKagan added a commit to EliahKagan/GitPython that referenced this pull requestDec 22, 2023
EliahKagan added a commit to EliahKagan/GitPython that referenced this pull requestDec 22, 2023
These are "non-reified docstrings" as described ingitpython-developers#1734. They arenot made part of the data model, but most editors will displaythem, including on symbols present in code of other projects thatuse the GitPython library. A number of these have already beenadded, but this adds what will probably be most of the remainingones.For the most part, this doesn't create documentation where therewasn't any, but instead converts existing comments to "docstrings."In a handful of cases, they are expanded, reworded, or a docstringadded.This also fixes some small style inconsistencies that were missedingitpython-developers#1725, and moves a comment that had become inadvertentlydisplaced due to autoformatting to the item it was meant for.The major omission here is HIDE_WINDOWS_KNOWN_ERRORS andHIDE_WINDOWS_FREEZE_ERRORS. This doesn't convert the comments abovethem to "docstrings," for a few reasons. They are not specific toeither of the symbols, they are oriented toward considerations thatare not really relevant except when developing GitPython itself,and they are out of date. Also, because HIDE_WINDOWS_KNOWN_ERRORSis listed in __all__, increasing the level of documentation for itmight be taken as a committment to preserve some aspect of itscurrent behavior, which could interfere with progress ongitpython-developers#790. SoI've kept those comments as comments, and unchanged, for now.
lettuce-botbot referenced this pull request in lettuce-financial/github-bot-signed-commitJan 10, 2024
[![MendRenovate](https://app.renovatebot.com/images/banner.svg)](https://renovatebot.com)This PR contains the following updates:| Package | Change | Age | Adoption | Passing | Confidence ||---|---|---|---|---|---|| [GitPython](https://togithub.com/gitpython-developers/GitPython) |`==3.1.40` -> `==3.1.41` |[![age](https://developer.mend.io/api/mc/badges/age/pypi/GitPython/3.1.41?slim=true)](https://docs.renovatebot.com/merge-confidence/)|[![adoption](https://developer.mend.io/api/mc/badges/adoption/pypi/GitPython/3.1.41?slim=true)](https://docs.renovatebot.com/merge-confidence/)|[![passing](https://developer.mend.io/api/mc/badges/compatibility/pypi/GitPython/3.1.40/3.1.41?slim=true)](https://docs.renovatebot.com/merge-confidence/)|[![confidence](https://developer.mend.io/api/mc/badges/confidence/pypi/GitPython/3.1.40/3.1.41?slim=true)](https://docs.renovatebot.com/merge-confidence/)|---### Release Notes<details><summary>gitpython-developers/GitPython (GitPython)</summary>###[`v3.1.41`](https://togithub.com/gitpython-developers/GitPython/releases/tag/3.1.41):- fix Windows security issue[CompareSource](https://togithub.com/gitpython-developers/GitPython/compare/3.1.40...3.1.41)The details about the Windows security issue [can be found in thisadvisory](https://togithub.com/gitpython-developers/GitPython/security/advisories/GHSA-2mqj-m65w-jghx).Special thanks go to[@&#8203;EliahKagan](https://togithub.com/EliahKagan) who reported theissue and fixed it in a single stroke, while being responsible for anincredible amount of improvements that he contributed over the lastcouple of months ❤️.#### What's Changed- Add `__all__` in git.exc by[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in[https://github.com/gitpython-developers/GitPython/pull/1719](https://togithub.com/gitpython-developers/GitPython/pull/1719)- Set submodule update cadence to weekly by[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in[https://github.com/gitpython-developers/GitPython/pull/1721](https://togithub.com/gitpython-developers/GitPython/pull/1721)- Never modify sys.path by[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in[https://github.com/gitpython-developers/GitPython/pull/1720](https://togithub.com/gitpython-developers/GitPython/pull/1720)- Bump git/ext/gitdb from `8ec2390` to `ec58b7e` by[@&#8203;dependabot](https://togithub.com/dependabot) in[https://github.com/gitpython-developers/GitPython/pull/1722](https://togithub.com/gitpython-developers/GitPython/pull/1722)- Revise comments, docstrings, some messages, and a bit of code by[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in[https://github.com/gitpython-developers/GitPython/pull/1725](https://togithub.com/gitpython-developers/GitPython/pull/1725)- Use zero-argument super() by[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in[https://github.com/gitpython-developers/GitPython/pull/1726](https://togithub.com/gitpython-developers/GitPython/pull/1726)- Remove obsolete note in \_iter_packed_refs by[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in[https://github.com/gitpython-developers/GitPython/pull/1727](https://togithub.com/gitpython-developers/GitPython/pull/1727)- Reorganize test_util and make xfail marks precise by[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in[https://github.com/gitpython-developers/GitPython/pull/1729](https://togithub.com/gitpython-developers/GitPython/pull/1729)- Clarify license and make module top comments more consistent by[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in[https://github.com/gitpython-developers/GitPython/pull/1730](https://togithub.com/gitpython-developers/GitPython/pull/1730)- Deprecate compat.is\_<platform>, rewriting all uses by[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in[https://github.com/gitpython-developers/GitPython/pull/1732](https://togithub.com/gitpython-developers/GitPython/pull/1732)- Revise and restore some module docstrings by[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in[https://github.com/gitpython-developers/GitPython/pull/1735](https://togithub.com/gitpython-developers/GitPython/pull/1735)- Make the rmtree callback Windows-only by[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in[https://github.com/gitpython-developers/GitPython/pull/1739](https://togithub.com/gitpython-developers/GitPython/pull/1739)- List all non-passing tests in test summaries by[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in[https://github.com/gitpython-developers/GitPython/pull/1740](https://togithub.com/gitpython-developers/GitPython/pull/1740)- Document some minor subtleties in test_util.py by[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in[https://github.com/gitpython-developers/GitPython/pull/1749](https://togithub.com/gitpython-developers/GitPython/pull/1749)- Always read metadata files as UTF-8 in setup.py by[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in[https://github.com/gitpython-developers/GitPython/pull/1748](https://togithub.com/gitpython-developers/GitPython/pull/1748)- Test native Windows on CI by[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in[https://github.com/gitpython-developers/GitPython/pull/1745](https://togithub.com/gitpython-developers/GitPython/pull/1745)- Test macOS on CI by[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in[https://github.com/gitpython-developers/GitPython/pull/1752](https://togithub.com/gitpython-developers/GitPython/pull/1752)- Let close_fds be True on all platforms by[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in[https://github.com/gitpython-developers/GitPython/pull/1753](https://togithub.com/gitpython-developers/GitPython/pull/1753)- Fix IndexFile.from_tree on Windows by[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in[https://github.com/gitpython-developers/GitPython/pull/1751](https://togithub.com/gitpython-developers/GitPython/pull/1751)- Remove unused TASKKILL fallback in AutoInterrupt by[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in[https://github.com/gitpython-developers/GitPython/pull/1754](https://togithub.com/gitpython-developers/GitPython/pull/1754)- Don't return with operand when conceptually void by[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in[https://github.com/gitpython-developers/GitPython/pull/1755](https://togithub.com/gitpython-developers/GitPython/pull/1755)- Group .gitignore entries by purpose by[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in[https://github.com/gitpython-developers/GitPython/pull/1758](https://togithub.com/gitpython-developers/GitPython/pull/1758)- Adding dubious ownership handling by[@&#8203;marioaag](https://togithub.com/marioaag) in[https://github.com/gitpython-developers/GitPython/pull/1746](https://togithub.com/gitpython-developers/GitPython/pull/1746)- Avoid brittle assumptions about preexisting temporary files in testsby [@&#8203;EliahKagan](https://togithub.com/EliahKagan) in[https://github.com/gitpython-developers/GitPython/pull/1759](https://togithub.com/gitpython-developers/GitPython/pull/1759)- Overhaul noqa directives by[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in[https://github.com/gitpython-developers/GitPython/pull/1760](https://togithub.com/gitpython-developers/GitPython/pull/1760)- Clarify some Git.execute kill_after_timeout limitations by[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in[https://github.com/gitpython-developers/GitPython/pull/1761](https://togithub.com/gitpython-developers/GitPython/pull/1761)- Bump actions/setup-python from 4 to 5 by[@&#8203;dependabot](https://togithub.com/dependabot) in[https://github.com/gitpython-developers/GitPython/pull/1763](https://togithub.com/gitpython-developers/GitPython/pull/1763)- Don't install black on Cygwin by[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in[https://github.com/gitpython-developers/GitPython/pull/1766](https://togithub.com/gitpython-developers/GitPython/pull/1766)- Extract all "import gc" to module level by[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in[https://github.com/gitpython-developers/GitPython/pull/1765](https://togithub.com/gitpython-developers/GitPython/pull/1765)- Extract remaining local "import gc" to module level by[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in[https://github.com/gitpython-developers/GitPython/pull/1768](https://togithub.com/gitpython-developers/GitPython/pull/1768)- Replace xfail with gc.collect in TestSubmodule.test_rename by[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in[https://github.com/gitpython-developers/GitPython/pull/1767](https://togithub.com/gitpython-developers/GitPython/pull/1767)- Enable CodeQL by [@&#8203;EliahKagan](https://togithub.com/EliahKagan)in[https://github.com/gitpython-developers/GitPython/pull/1769](https://togithub.com/gitpython-developers/GitPython/pull/1769)- Replace some uses of the deprecated mktemp function by[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in[https://github.com/gitpython-developers/GitPython/pull/1770](https://togithub.com/gitpython-developers/GitPython/pull/1770)- Bump github/codeql-action from 2 to 3 by[@&#8203;dependabot](https://togithub.com/dependabot) in[https://github.com/gitpython-developers/GitPython/pull/1773](https://togithub.com/gitpython-developers/GitPython/pull/1773)- Run some Windows environment variable tests only on Windows by[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in[https://github.com/gitpython-developers/GitPython/pull/1774](https://togithub.com/gitpython-developers/GitPython/pull/1774)- Fix TemporaryFileSwap regression where file_path could not be Path by[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in[https://github.com/gitpython-developers/GitPython/pull/1776](https://togithub.com/gitpython-developers/GitPython/pull/1776)- Improve hooks tests by[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in[https://github.com/gitpython-developers/GitPython/pull/1777](https://togithub.com/gitpython-developers/GitPython/pull/1777)- Fix if items of Index is of type PathLike by[@&#8203;stegm](https://togithub.com/stegm) in[https://github.com/gitpython-developers/GitPython/pull/1778](https://togithub.com/gitpython-developers/GitPython/pull/1778)- Better document IterableObj.iter_items and improve some subclasses by[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in[https://github.com/gitpython-developers/GitPython/pull/1780](https://togithub.com/gitpython-developers/GitPython/pull/1780)- Revert "Don't install black on Cygwin" by[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in[https://github.com/gitpython-developers/GitPython/pull/1783](https://togithub.com/gitpython-developers/GitPython/pull/1783)- Add missing pip in $PATH on Cygwin CI by[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in[https://github.com/gitpython-developers/GitPython/pull/1784](https://togithub.com/gitpython-developers/GitPython/pull/1784)- Shorten Iterable docstrings and put IterableObj first by[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in[https://github.com/gitpython-developers/GitPython/pull/1785](https://togithub.com/gitpython-developers/GitPython/pull/1785)- Fix incompletely revised Iterable/IterableObj docstrings by[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in[https://github.com/gitpython-developers/GitPython/pull/1786](https://togithub.com/gitpython-developers/GitPython/pull/1786)- Pre-deprecate setting Git.USE_SHELL by[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in[https://github.com/gitpython-developers/GitPython/pull/1782](https://togithub.com/gitpython-developers/GitPython/pull/1782)- Deprecate Git.USE_SHELL by[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in[https://github.com/gitpython-developers/GitPython/pull/1787](https://togithub.com/gitpython-developers/GitPython/pull/1787)- In handle_process_output don't forward finalizer result by[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in[https://github.com/gitpython-developers/GitPython/pull/1788](https://togithub.com/gitpython-developers/GitPython/pull/1788)- Fix mypy warning "Missing return statement" by[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in[https://github.com/gitpython-developers/GitPython/pull/1789](https://togithub.com/gitpython-developers/GitPython/pull/1789)- Fix two remaining Windows untrusted search path cases by[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in[https://github.com/gitpython-developers/GitPython/pull/1792](https://togithub.com/gitpython-developers/GitPython/pull/1792)#### New Contributors- [@&#8203;marioaag](https://togithub.com/marioaag) made their firstcontribution in[https://github.com/gitpython-developers/GitPython/pull/1746](https://togithub.com/gitpython-developers/GitPython/pull/1746)- [@&#8203;stegm](https://togithub.com/stegm) made their firstcontribution in[https://github.com/gitpython-developers/GitPython/pull/1778](https://togithub.com/gitpython-developers/GitPython/pull/1778)**Full Changelog**:gitpython-developers/GitPython@3.1.40...3.1.41</details>---### Configuration📅 **Schedule**: Branch creation - At any time (no schedule defined),Automerge - At any time (no schedule defined).🚦 **Automerge**: Disabled by config. Please merge this manually once youare satisfied.♻ **Rebasing**: Whenever PR becomes conflicted, or you tick therebase/retry checkbox.🔕 **Ignore**: Close this PR and you won't be reminded about theseupdates again.---- [ ] <!-- rebase-check -->If you want to rebase/retry this PR, checkthis box---This PR has been generated by [MendRenovate](https://www.mend.io/free-developer-tools/renovate/). Viewrepository job log[here](https://developer.mend.io/github/lettuce-financial/github-bot-signed-commit).<!--renovate-debug:eyJjcmVhdGVkSW5WZXIiOiIzNy4xMjcuMCIsInVwZGF0ZWRJblZlciI6IjM3LjEyNy4wIiwidGFyZ2V0QnJhbmNoIjoibWFpbiJ9-->
renovatebot referenced this pull request in allenporter/flux-localJan 11, 2024
[![MendRenovate](https://app.renovatebot.com/images/banner.svg)](https://renovatebot.com)This PR contains the following updates:| Package | Change | Age | Adoption | Passing | Confidence ||---|---|---|---|---|---|| [GitPython](https://togithub.com/gitpython-developers/GitPython) |`==3.1.40` -> `==3.1.41` |[![age](https://developer.mend.io/api/mc/badges/age/pypi/GitPython/3.1.41?slim=true)](https://docs.renovatebot.com/merge-confidence/)|[![adoption](https://developer.mend.io/api/mc/badges/adoption/pypi/GitPython/3.1.41?slim=true)](https://docs.renovatebot.com/merge-confidence/)|[![passing](https://developer.mend.io/api/mc/badges/compatibility/pypi/GitPython/3.1.40/3.1.41?slim=true)](https://docs.renovatebot.com/merge-confidence/)|[![confidence](https://developer.mend.io/api/mc/badges/confidence/pypi/GitPython/3.1.40/3.1.41?slim=true)](https://docs.renovatebot.com/merge-confidence/)|---### Release Notes<details><summary>gitpython-developers/GitPython (GitPython)</summary>###[`v3.1.41`](https://togithub.com/gitpython-developers/GitPython/releases/tag/3.1.41):- fix Windows security issue[CompareSource](https://togithub.com/gitpython-developers/GitPython/compare/3.1.40...3.1.41)The details about the Windows security issue [can be found in thisadvisory](https://togithub.com/gitpython-developers/GitPython/security/advisories/GHSA-2mqj-m65w-jghx).Special thanks go to[@&#8203;EliahKagan](https://togithub.com/EliahKagan) who reported theissue and fixed it in a single stroke, while being responsible for anincredible amount of improvements that he contributed over the lastcouple of months ❤️.#### What's Changed- Add `__all__` in git.exc by[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in[https://github.com/gitpython-developers/GitPython/pull/1719](https://togithub.com/gitpython-developers/GitPython/pull/1719)- Set submodule update cadence to weekly by[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in[https://github.com/gitpython-developers/GitPython/pull/1721](https://togithub.com/gitpython-developers/GitPython/pull/1721)- Never modify sys.path by[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in[https://github.com/gitpython-developers/GitPython/pull/1720](https://togithub.com/gitpython-developers/GitPython/pull/1720)- Bump git/ext/gitdb from `8ec2390` to `ec58b7e` by[@&#8203;dependabot](https://togithub.com/dependabot) in[https://github.com/gitpython-developers/GitPython/pull/1722](https://togithub.com/gitpython-developers/GitPython/pull/1722)- Revise comments, docstrings, some messages, and a bit of code by[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in[https://github.com/gitpython-developers/GitPython/pull/1725](https://togithub.com/gitpython-developers/GitPython/pull/1725)- Use zero-argument super() by[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in[https://github.com/gitpython-developers/GitPython/pull/1726](https://togithub.com/gitpython-developers/GitPython/pull/1726)- Remove obsolete note in \_iter_packed_refs by[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in[https://github.com/gitpython-developers/GitPython/pull/1727](https://togithub.com/gitpython-developers/GitPython/pull/1727)- Reorganize test_util and make xfail marks precise by[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in[https://github.com/gitpython-developers/GitPython/pull/1729](https://togithub.com/gitpython-developers/GitPython/pull/1729)- Clarify license and make module top comments more consistent by[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in[https://github.com/gitpython-developers/GitPython/pull/1730](https://togithub.com/gitpython-developers/GitPython/pull/1730)- Deprecate compat.is\_<platform>, rewriting all uses by[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in[https://github.com/gitpython-developers/GitPython/pull/1732](https://togithub.com/gitpython-developers/GitPython/pull/1732)- Revise and restore some module docstrings by[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in[https://github.com/gitpython-developers/GitPython/pull/1735](https://togithub.com/gitpython-developers/GitPython/pull/1735)- Make the rmtree callback Windows-only by[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in[https://github.com/gitpython-developers/GitPython/pull/1739](https://togithub.com/gitpython-developers/GitPython/pull/1739)- List all non-passing tests in test summaries by[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in[https://github.com/gitpython-developers/GitPython/pull/1740](https://togithub.com/gitpython-developers/GitPython/pull/1740)- Document some minor subtleties in test_util.py by[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in[https://github.com/gitpython-developers/GitPython/pull/1749](https://togithub.com/gitpython-developers/GitPython/pull/1749)- Always read metadata files as UTF-8 in setup.py by[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in[https://github.com/gitpython-developers/GitPython/pull/1748](https://togithub.com/gitpython-developers/GitPython/pull/1748)- Test native Windows on CI by[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in[https://github.com/gitpython-developers/GitPython/pull/1745](https://togithub.com/gitpython-developers/GitPython/pull/1745)- Test macOS on CI by[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in[https://github.com/gitpython-developers/GitPython/pull/1752](https://togithub.com/gitpython-developers/GitPython/pull/1752)- Let close_fds be True on all platforms by[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in[https://github.com/gitpython-developers/GitPython/pull/1753](https://togithub.com/gitpython-developers/GitPython/pull/1753)- Fix IndexFile.from_tree on Windows by[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in[https://github.com/gitpython-developers/GitPython/pull/1751](https://togithub.com/gitpython-developers/GitPython/pull/1751)- Remove unused TASKKILL fallback in AutoInterrupt by[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in[https://github.com/gitpython-developers/GitPython/pull/1754](https://togithub.com/gitpython-developers/GitPython/pull/1754)- Don't return with operand when conceptually void by[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in[https://github.com/gitpython-developers/GitPython/pull/1755](https://togithub.com/gitpython-developers/GitPython/pull/1755)- Group .gitignore entries by purpose by[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in[https://github.com/gitpython-developers/GitPython/pull/1758](https://togithub.com/gitpython-developers/GitPython/pull/1758)- Adding dubious ownership handling by[@&#8203;marioaag](https://togithub.com/marioaag) in[https://github.com/gitpython-developers/GitPython/pull/1746](https://togithub.com/gitpython-developers/GitPython/pull/1746)- Avoid brittle assumptions about preexisting temporary files in testsby [@&#8203;EliahKagan](https://togithub.com/EliahKagan) in[https://github.com/gitpython-developers/GitPython/pull/1759](https://togithub.com/gitpython-developers/GitPython/pull/1759)- Overhaul noqa directives by[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in[https://github.com/gitpython-developers/GitPython/pull/1760](https://togithub.com/gitpython-developers/GitPython/pull/1760)- Clarify some Git.execute kill_after_timeout limitations by[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in[https://github.com/gitpython-developers/GitPython/pull/1761](https://togithub.com/gitpython-developers/GitPython/pull/1761)- Bump actions/setup-python from 4 to 5 by[@&#8203;dependabot](https://togithub.com/dependabot) in[https://github.com/gitpython-developers/GitPython/pull/1763](https://togithub.com/gitpython-developers/GitPython/pull/1763)- Don't install black on Cygwin by[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in[https://github.com/gitpython-developers/GitPython/pull/1766](https://togithub.com/gitpython-developers/GitPython/pull/1766)- Extract all "import gc" to module level by[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in[https://github.com/gitpython-developers/GitPython/pull/1765](https://togithub.com/gitpython-developers/GitPython/pull/1765)- Extract remaining local "import gc" to module level by[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in[https://github.com/gitpython-developers/GitPython/pull/1768](https://togithub.com/gitpython-developers/GitPython/pull/1768)- Replace xfail with gc.collect in TestSubmodule.test_rename by[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in[https://github.com/gitpython-developers/GitPython/pull/1767](https://togithub.com/gitpython-developers/GitPython/pull/1767)- Enable CodeQL by [@&#8203;EliahKagan](https://togithub.com/EliahKagan)in[https://github.com/gitpython-developers/GitPython/pull/1769](https://togithub.com/gitpython-developers/GitPython/pull/1769)- Replace some uses of the deprecated mktemp function by[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in[https://github.com/gitpython-developers/GitPython/pull/1770](https://togithub.com/gitpython-developers/GitPython/pull/1770)- Bump github/codeql-action from 2 to 3 by[@&#8203;dependabot](https://togithub.com/dependabot) in[https://github.com/gitpython-developers/GitPython/pull/1773](https://togithub.com/gitpython-developers/GitPython/pull/1773)- Run some Windows environment variable tests only on Windows by[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in[https://github.com/gitpython-developers/GitPython/pull/1774](https://togithub.com/gitpython-developers/GitPython/pull/1774)- Fix TemporaryFileSwap regression where file_path could not be Path by[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in[https://github.com/gitpython-developers/GitPython/pull/1776](https://togithub.com/gitpython-developers/GitPython/pull/1776)- Improve hooks tests by[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in[https://github.com/gitpython-developers/GitPython/pull/1777](https://togithub.com/gitpython-developers/GitPython/pull/1777)- Fix if items of Index is of type PathLike by[@&#8203;stegm](https://togithub.com/stegm) in[https://github.com/gitpython-developers/GitPython/pull/1778](https://togithub.com/gitpython-developers/GitPython/pull/1778)- Better document IterableObj.iter_items and improve some subclasses by[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in[https://github.com/gitpython-developers/GitPython/pull/1780](https://togithub.com/gitpython-developers/GitPython/pull/1780)- Revert "Don't install black on Cygwin" by[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in[https://github.com/gitpython-developers/GitPython/pull/1783](https://togithub.com/gitpython-developers/GitPython/pull/1783)- Add missing pip in $PATH on Cygwin CI by[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in[https://github.com/gitpython-developers/GitPython/pull/1784](https://togithub.com/gitpython-developers/GitPython/pull/1784)- Shorten Iterable docstrings and put IterableObj first by[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in[https://github.com/gitpython-developers/GitPython/pull/1785](https://togithub.com/gitpython-developers/GitPython/pull/1785)- Fix incompletely revised Iterable/IterableObj docstrings by[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in[https://github.com/gitpython-developers/GitPython/pull/1786](https://togithub.com/gitpython-developers/GitPython/pull/1786)- Pre-deprecate setting Git.USE_SHELL by[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in[https://github.com/gitpython-developers/GitPython/pull/1782](https://togithub.com/gitpython-developers/GitPython/pull/1782)- Deprecate Git.USE_SHELL by[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in[https://github.com/gitpython-developers/GitPython/pull/1787](https://togithub.com/gitpython-developers/GitPython/pull/1787)- In handle_process_output don't forward finalizer result by[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in[https://github.com/gitpython-developers/GitPython/pull/1788](https://togithub.com/gitpython-developers/GitPython/pull/1788)- Fix mypy warning "Missing return statement" by[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in[https://github.com/gitpython-developers/GitPython/pull/1789](https://togithub.com/gitpython-developers/GitPython/pull/1789)- Fix two remaining Windows untrusted search path cases by[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in[https://github.com/gitpython-developers/GitPython/pull/1792](https://togithub.com/gitpython-developers/GitPython/pull/1792)#### New Contributors- [@&#8203;marioaag](https://togithub.com/marioaag) made their firstcontribution in[https://github.com/gitpython-developers/GitPython/pull/1746](https://togithub.com/gitpython-developers/GitPython/pull/1746)- [@&#8203;stegm](https://togithub.com/stegm) made their firstcontribution in[https://github.com/gitpython-developers/GitPython/pull/1778](https://togithub.com/gitpython-developers/GitPython/pull/1778)**Full Changelog**:gitpython-developers/GitPython@3.1.40...3.1.41</details>---### Configuration📅 **Schedule**: Branch creation - At any time (no schedule defined),Automerge - At any time (no schedule defined).🚦 **Automerge**: Enabled.♻ **Rebasing**: Whenever PR becomes conflicted, or you tick therebase/retry checkbox.🔕 **Ignore**: Close this PR and you won't be reminded about this updateagain.---- [ ] <!-- rebase-check -->If you want to rebase/retry this PR, checkthis box---This PR has been generated by [MendRenovate](https://www.mend.io/free-developer-tools/renovate/). Viewrepository job log[here](https://developer.mend.io/github/allenporter/flux-local).<!--renovate-debug:eyJjcmVhdGVkSW5WZXIiOiIzNy4xMjcuMCIsInVwZGF0ZWRJblZlciI6IjM3LjEyNy4wIiwidGFyZ2V0QnJhbmNoIjoibWFpbiJ9-->Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>
EliahKagan added a commit to EliahKagan/GitPython that referenced this pull requestFeb 25, 2024
Except for:- git.cmd, where docstrings were revised ina374b8c.- git.types, where docstring changes may best be made together with  changes to how imports are organized and documented, which seems  not to be in the same scope as the changes in this commit.This change, as well as those ina374b8c, are largely along thelinesgitpython-developers#1725, with most revisions here being to docstrings and a fewbeing to comments.The major differences between the kinds of docstring changes hereand those indgitpython-developers#1725 are that the changes here push somewhat harderfor consistency and apply some kinds of changes I was reluctant toapply widely ingitpython-developers#1725:- Wrap all docstrings and comments to 88 columns, except for parts  that are decisively clearer when not wrapped. Note that semi-  paragraph changes represented as single newlines are still kept  where meaningful, which is one reason this is not always the same  effect as automatic wrapping would produce.- Avoid code formatting (double backticks) for headings that  precede sections and code blocks. This was done enough that it  seems to have been intentional, but it doesn't really have the  right semantics, and the documentation is currently rendering in  such a way (including on readthedocs.org) where removing that  formatting seems clearly better.- References (single backticks with a role prefix) and code spans  (double backticks) everywhere applicable, even in the first lines  of docstrings.- Single-backticks around parameter names, with no role prefix.  These were mostly either formatted that way or emphasized (with  asterisks). This is one of the rare cases that I have used single  backticks without a role prefix, which ordinarily should be  avoided, but to get a role for references to a function's  parameters within that function, a plugin would be needed. In the  rare case that one function's docstring refers to another  function's parameters by names those are double-backticked as  code spans (and where applicable the name of the referred-to  function is single-backticked with the :func: or :meth: role).- All sections, such as :param blah:, :note:, and :return:, now  have a newline before any text in them. This was already often  but far from always done, and the style was overall inconsistent.  Of consistent approaches that are clear and easy to write, this  is the simplest. It also seems to substantially improve  readability, when taken together with...- Sections are always separated by a blank line, even if they are  very short.- Essentially unlimited use of `~a.b.c`, where applicable, to refer  and link to the documentation for a.b.c while showing the text  "a" and revealing "a.b.c" on hover. I had previously somewhat  limited my use of this tilde notation in case readers of the  source code itself (where it is not rendered) weren't familiar  with it, but at the cost of less consistency in when an entity  was referred to. There remain a couple places in git.util where  I do not do this because the explicit form `a <a.b.c>`, which is  equivalent, lined things up better and was thus easier to read.Those are the major differences between the approach taken hereand ingitpython-developers#1725, but not necessarily most of the changes done here(many of which are the same kinds of revisions as done there).Note that this commit only modifies some git/*.py files, and thereare more git/**/*.py files that remain to be revised accordingly.
EliahKagan added a commit to EliahKagan/GitPython that referenced this pull requestFeb 25, 2024
Except for:- git.cmd, where docstrings were revised ina374b8c.- git.types, where docstring changes may best be made together with  changes to how imports are organized and documented, which seems  not to be in the same scope as the changes in this commit.This change, as well as those ina374b8c, are largely along thelines ofgitpython-developers#1725, with most revisions here being to docstrings and afew being to comments.The major differences between the kinds of docstring changes hereand those indgitpython-developers#1725 are that the changes here push somewhat harderfor consistency and apply some kinds of changes I was reluctant toapply widely ingitpython-developers#1725:- Wrap all docstrings and comments to 88 columns, except for parts  that are decisively clearer when not wrapped. Note that semi-  paragraph changes represented as single newlines are still kept  where meaningful, which is one reason this is not always the same  effect as automatic wrapping would produce.- Avoid code formatting (double backticks) for headings that  precede sections and code blocks. This was done enough that it  seems to have been intentional, but it doesn't really have the  right semantics, and the documentation is currently rendering in  such a way (including on readthedocs.org) where removing that  formatting seems clearly better.- References (single backticks with a role prefix) and code spans  (double backticks) everywhere applicable, even in the first lines  of docstrings.- Single-backticks around parameter names, with no role prefix.  These were mostly either formatted that way or emphasized (with  asterisks). This is one of the rare cases that I have used single  backticks without a role prefix, which ordinarily should be  avoided, but to get a role for references to a function's  parameters within that function, a plugin would be needed. In the  rare case that one function's docstring refers to another  function's parameters by names those are double-backticked as  code spans (and where applicable the name of the referred-to  function is single-backticked with the :func: or :meth: role).- All sections, such as :param blah:, :note:, and :return:, now  have a newline before any text in them. This was already often  but far from always done, and the style was overall inconsistent.  Of consistent approaches that are clear and easy to write, this  is the simplest. It also seems to substantially improve  readability, when taken together with...- Sections are always separated by a blank line, even if they are  very short.- Essentially unlimited use of `~a.b.c`, where applicable, to refer  and link to the documentation for a.b.c while showing the text  "a" and revealing "a.b.c" on hover. I had previously somewhat  limited my use of this tilde notation in case readers of the  source code itself (where it is not rendered) weren't familiar  with it, but at the cost of less consistency in when an entity  was referred to. There remain a couple places in git.util where  I do not do this because the explicit form `a <a.b.c>`, which is  equivalent, lined things up better and was thus easier to read.Those are the major differences between the approach taken hereand ingitpython-developers#1725, but not necessarily most of the changes done here(many of which are the same kinds of revisions as done there).Note that this commit only modifies some git/*.py files, and thereare more git/**/*.py files that remain to be revised accordingly.
EliahKagan added a commit to EliahKagan/GitPython that referenced this pull requestFeb 26, 2024
Except for:- git.cmd, where docstrings were revised ine08066c.- git.types, where docstring changes may best be made together with  changes to how imports are organized and documented, which seems  not to be in the same scope as the changes in this commit.This change, as well as those ine08066c, are largely along thelines ofgitpython-developers#1725, with most revisions here being to docstrings and afew being to comments.The major differences between the kinds of docstring changes hereand those indgitpython-developers#1725 are that the changes here push somewhat harderfor consistency and apply some kinds of changes I was reluctant toapply widely ingitpython-developers#1725:- Wrap all docstrings and comments to 88 columns, except for parts  that are decisively clearer when not wrapped. Note that semi-  paragraph changes represented as single newlines are still kept  where meaningful, which is one reason this is not always the same  effect as automatic wrapping would produce.- Avoid code formatting (double backticks) for headings that  precede sections and code blocks. This was done enough that it  seems to have been intentional, but it doesn't really have the  right semantics, and the documentation is currently rendering in  such a way (including on readthedocs.org) where removing that  formatting seems clearly better.- References (single backticks with a role prefix) and code spans  (double backticks) everywhere applicable, even in the first lines  of docstrings.- Single-backticks around parameter names, with no role prefix.  These were mostly either formatted that way or emphasized (with  asterisks). This is one of the rare cases that I have used single  backticks without a role prefix, which ordinarily should be  avoided, but to get a role for references to a function's  parameters within that function, a plugin would be needed. In the  rare case that one function's docstring refers to another  function's parameters by names those are double-backticked as  code spans (and where applicable the name of the referred-to  function is single-backticked with the :func: or :meth: role).- All sections, such as :param blah:, :note:, and :return:, now  have a newline before any text in them. This was already often  but far from always done, and the style was overall inconsistent.  Of consistent approaches that are clear and easy to write, this  is the simplest. It also seems to substantially improve  readability, when taken together with...- Sections are always separated by a blank line, even if they are  very short.- Essentially unlimited use of `~a.b.c`, where applicable, to refer  and link to the documentation for a.b.c while showing the text  "a" and revealing "a.b.c" on hover. I had previously somewhat  limited my use of this tilde notation in case readers of the  source code itself (where it is not rendered) weren't familiar  with it, but at the cost of less consistency in when an entity  was referred to. There remain a couple places in git.util where  I do not do this because the explicit form `a <a.b.c>`, which is  equivalent, lined things up better and was thus easier to read.Those are the major differences between the approach taken hereand ingitpython-developers#1725, but not necessarily most of the changes done here(many of which are the same kinds of revisions as done there).Note that this commit only modifies some git/*.py files, and thereare more git/**/*.py files that remain to be revised accordingly.
EliahKagan added a commit to EliahKagan/GitPython that referenced this pull requestFeb 27, 2024
The original problem where the backslash wasn't included in thedocstring at all was fixed in7dd2095 (gitpython-developers#1725), but the backslashstill did not appear in rendered Sphinx documentation, because itwas also treated as a reStructuredText metacharacter.Although that can be addressed by adding a further backslash toescape it, the effect is ambiguous when the docstring is read inthe code. So this just encloses it in a double-backticked codespan instead, which is a somewhat clearer way to show it anyway.
EliahKagan added a commit to EliahKagan/GitPython that referenced this pull requestFeb 28, 2024
DateTime is not a class here, and the parameter is expected as int.This fixes a documentation bug I introduced incd16a35 (gitpython-developers#1725).
EliahKagan added a commit to EliahKagan/GitPython that referenced this pull requestMar 4, 2024
otc-zuulbot pushed a commit to opentelekomcloud-infra/eyes_on_docs that referenced this pull requestMar 6, 2024
Bump gitpython from 3.1.37 to 3.1.41Bumps gitpython from 3.1.37 to 3.1.41.Release notesSourced from gitpython's releases.3.1.41 - fix Windows security issueThe details about the Windows security issue can be found in this advisory.Special thanks go to @​EliahKagan who reported the issue and fixed it in a single stroke, while being responsible for an incredible amount of improvements that he contributed over the last couple of months ❤️.What's ChangedAdd __all__ in git.exc by @​EliahKagan ingitpython-developers/GitPython#1719Set submodule update cadence to weekly by @​EliahKagan ingitpython-developers/GitPython#1721Never modify sys.path by @​EliahKagan ingitpython-developers/GitPython#1720Bump git/ext/gitdb from 8ec2390 to ec58b7e by @​dependabot ingitpython-developers/GitPython#1722Revise comments, docstrings, some messages, and a bit of code by @​EliahKagan ingitpython-developers/GitPython#1725Use zero-argument super() by @​EliahKagan ingitpython-developers/GitPython#1726Remove obsolete note in _iter_packed_refs by @​EliahKagan ingitpython-developers/GitPython#1727Reorganize test_util and make xfail marks precise by @​EliahKagan ingitpython-developers/GitPython#1729Clarify license and make module top comments more consistent by @​EliahKagan ingitpython-developers/GitPython#1730Deprecate compat.is_, rewriting all uses by @​EliahKagan ingitpython-developers/GitPython#1732Revise and restore some module docstrings by @​EliahKagan ingitpython-developers/GitPython#1735Make the rmtree callback Windows-only by @​EliahKagan ingitpython-developers/GitPython#1739List all non-passing tests in test summaries by @​EliahKagan ingitpython-developers/GitPython#1740Document some minor subtleties in test_util.py by @​EliahKagan ingitpython-developers/GitPython#1749Always read metadata files as UTF-8 in setup.py by @​EliahKagan ingitpython-developers/GitPython#1748Test native Windows on CI by @​EliahKagan ingitpython-developers/GitPython#1745Test macOS on CI by @​EliahKagan ingitpython-developers/GitPython#1752Let close_fds be True on all platforms by @​EliahKagan ingitpython-developers/GitPython#1753Fix IndexFile.from_tree on Windows by @​EliahKagan ingitpython-developers/GitPython#1751Remove unused TASKKILL fallback in AutoInterrupt by @​EliahKagan ingitpython-developers/GitPython#1754Don't return with operand when conceptually void by @​EliahKagan ingitpython-developers/GitPython#1755Group .gitignore entries by purpose by @​EliahKagan ingitpython-developers/GitPython#1758Adding dubious ownership handling by @​marioaag ingitpython-developers/GitPython#1746Avoid brittle assumptions about preexisting temporary files in tests by @​EliahKagan ingitpython-developers/GitPython#1759Overhaul noqa directives by @​EliahKagan ingitpython-developers/GitPython#1760Clarify some Git.execute kill_after_timeout limitations by @​EliahKagan ingitpython-developers/GitPython#1761Bump actions/setup-python from 4 to 5 by @​dependabot ingitpython-developers/GitPython#1763Don't install black on Cygwin by @​EliahKagan ingitpython-developers/GitPython#1766Extract all "import gc" to module level by @​EliahKagan ingitpython-developers/GitPython#1765Extract remaining local "import gc" to module level by @​EliahKagan ingitpython-developers/GitPython#1768Replace xfail with gc.collect in TestSubmodule.test_rename by @​EliahKagan ingitpython-developers/GitPython#1767Enable CodeQL by @​EliahKagan ingitpython-developers/GitPython#1769Replace some uses of the deprecated mktemp function by @​EliahKagan ingitpython-developers/GitPython#1770Bump github/codeql-action from 2 to 3 by @​dependabot ingitpython-developers/GitPython#1773Run some Windows environment variable tests only on Windows by @​EliahKagan ingitpython-developers/GitPython#1774Fix TemporaryFileSwap regression where file_path could not be Path by @​EliahKagan ingitpython-developers/GitPython#1776Improve hooks tests by @​EliahKagan ingitpython-developers/GitPython#1777Fix if items of Index is of type PathLike by @​stegm ingitpython-developers/GitPython#1778Better document IterableObj.iter_items and improve some subclasses by @​EliahKagan ingitpython-developers/GitPython#1780Revert "Don't install black on Cygwin" by @​EliahKagan ingitpython-developers/GitPython#1783Add missing pip in $PATH on Cygwin CI by @​EliahKagan ingitpython-developers/GitPython#1784Shorten Iterable docstrings and put IterableObj first by @​EliahKagan ingitpython-developers/GitPython#1785Fix incompletely revised Iterable/IterableObj docstrings by @​EliahKagan ingitpython-developers/GitPython#1786Pre-deprecate setting Git.USE_SHELL by @​EliahKagan ingitpython-developers/GitPython#1782... (truncated)Commitsf288738 bump patch levelef3192c Merge pull request #1792 from EliahKagan/popen1f3caa3 Further clarify comment in test_hook_uses_shell_not_from_cwd3eb7c2a Move safer_popen from git.util to git.cmdc551e91 Extract shared logic for using Popen safely on Windows15ebb25 Clarify comment in test_hook_uses_shell_not_from_cwdf44524a Avoid spurious "location may have moved" on Windowsa42ea0a Cover absent/no-distro bash.exe in hooks "not from cwd" test7751436 Extract venv management from test_installation66ff4c1 Omit CWD in search for bash.exe to run hooks on WindowsAdditional commits viewable in compare viewYou can trigger a rebase of this PR by commenting@dependabot rebase.Dependabot commands and optionsYou can trigger Dependabot actions by commenting on this PR:@dependabot rebase will rebase this PR@dependabot recreate will recreate this PR, overwriting any edits that have been made to it@dependabot merge will merge this PR after your CI passes on it@dependabot squash and merge will squash and merge this PR after your CI passes on it@dependabot cancel merge will cancel a previously requested merge and block automerging@dependabot reopen will reopen this PR if it is closed@dependabot close will close this PR and stop Dependabot recreating it. You can achieve the same result by closing it manually@dependabot show <dependency name> ignore conditions will show all of the ignore conditions of the specified dependency@dependabot ignore this major version will close this PR and stop Dependabot creating any more for this major version (unless you reopen the PR or upgrade to it yourself)@dependabot ignore this minor version will close this PR and stop Dependabot creating any more for this minor version (unless you reopen the PR or upgrade to it yourself)@dependabot ignore this dependency will close this PR and stop Dependabot creating any more for this dependency (unless you reopen the PR or upgrade to it yourself)You can disable automated security fix PRs for this repo from the Security Alerts page.NoteAutomatic rebases have been disabled on this pull request as it has been open for over 30 days.Reviewed-by: Vladimir Vshivkov
EliahKagan added a commit to EliahKagan/GitPython that referenced this pull requestMar 8, 2024
In6126997 (gitpython-developers#1725), I had meant to have the git.objects.tag moduledocstring say that the module defined the TagObject class, to helpensure no one would confuse this with the TagReference class. But Iinstead had it wrongly say it defined the TagReference class! Thisfixes that.
EliahKagan added a commit to EliahKagan/GitPython that referenced this pull requestMar 8, 2024
Incd16a35 (gitpython-developers#1725), I had taken "Treeish" to mean the type of thatexact name, git.index.base.Treeish. But that type is only usedwithin the git.index package (actually only in git.index.baseitself). It is also nonpublic: git.index.base.__all__ exists anddoes not list it.So most likely this was not intended in the git.diff.Diffable.diffdocstring. Even if intended, it does not appear accurate, since thegit.index.base.Treeish union includes bytes, and the logic inDiffable.diff and its helpers does not appear to accommodate bytes.A closer type is the public git.types.Tree_ish union, which isnarrower than git.index.base.Treeish, including neither str norbytes. However, it does not include str, and Diffable.diff doesaccept str to specify a tree-ish for diff-ing. It may be that"Treeish" in the pre-gitpython-developers#1725 docstring was capitalized for somereason other than to identify a type defined in GitPython's code.For now, I've changed it to refer to git.types.Tree_ish, but alsoexplicitly documented that a string can be used to specify atree-ish -- which is independently valuable, since previously theeffect of passing a str instance to the diff method was not statedanywhere in the method docstring. To clarify further, I included alink to tree-ish in gitglossary(7) as well.In addition, the original wording beforecd16a35 had included"(type)", which I had erroneously assumed was just meant to statethat it is a type (i.e. a class), so I had wrongly removed itwithout replacing it with anything when making it into a referenceto a type. But it was really an attempt to clarify thatDiffable.Index should be used directly, rather than an instance ofit. That is in effect the opposite of merely pointing out that itis a class; it is to express that it should be used in a way thatdoes not depend in any way on it being a class. This commit has thedocstring explicitly state that.
EliahKagan added a commit to EliahKagan/GitPython that referenced this pull requestMar 8, 2024
Incd16a35 (gitpython-developers#1725), I had taken "Treeish" to mean the type of thatexact name, git.index.base.Treeish. But that type is only usedwithin the git.index package (actually only in git.index.baseitself). It is also nonpublic: git.index.base.__all__ exists anddoes not list it.So most likely this was not intended in the git.diff.Diffable.diffdocstring. Even if intended, it does not appear accurate, since thegit.index.base.Treeish union includes bytes, and the logic inDiffable.diff and its helpers does not appear to accommodate bytes.A closer type is the public git.types.Tree_ish union, which isnarrower than git.index.base.Treeish, including neither str norbytes. However, it does not include str, and Diffable.diff doesaccept str to specify a tree-ish for diff-ing. It may be that"Treeish" in the pre-gitpython-developers#1725 docstring was capitalized for somereason other than to identify a type defined in GitPython's code.For now, I've changed it to refer to git.types.Tree_ish, but alsoexplicitly documented that a string can be used to specify atree-ish -- which is independently valuable, since previously theeffect of passing a str instance to the diff method was not statedanywhere in the method docstring. To clarify further, I included alink to tree-ish in gitglossary(7) as well.In addition, the original wording beforecd16a35 had included"(type)", which I had erroneously assumed was just meant to statethat it is a type (i.e. a class), so I had wrongly removed itwithout replacing it with anything when making it into a referenceto a type. But it was really an attempt to clarify thatDiffable.Index should be used directly, rather than an instance ofit. That is in effect the opposite of merely pointing out that itis a class; it is to express that it should be used in a way thatdoes not depend in any way on it being a class. This commit has thedocstring explicitly state that.
JoeWang1127 referenced this pull request in googleapis/sdk-platform-javaApr 6, 2024
[![MendRenovate](https://app.renovatebot.com/images/banner.svg)](https://renovatebot.com)This PR contains the following updates:| Package | Change | Age | Adoption | Passing | Confidence ||---|---|---|---|---|---|| [GitPython](https://togithub.com/gitpython-developers/GitPython) |`==3.1.40` -> `==3.1.41` |[![age](https://developer.mend.io/api/mc/badges/age/pypi/GitPython/3.1.41?slim=true)](https://docs.renovatebot.com/merge-confidence/)|[![adoption](https://developer.mend.io/api/mc/badges/adoption/pypi/GitPython/3.1.41?slim=true)](https://docs.renovatebot.com/merge-confidence/)|[![passing](https://developer.mend.io/api/mc/badges/compatibility/pypi/GitPython/3.1.40/3.1.41?slim=true)](https://docs.renovatebot.com/merge-confidence/)|[![confidence](https://developer.mend.io/api/mc/badges/confidence/pypi/GitPython/3.1.40/3.1.41?slim=true)](https://docs.renovatebot.com/merge-confidence/)|---> [!WARNING]> Some dependencies could not be looked up. Check the DependencyDashboard for more information.### GitHub Vulnerability Alerts####[CVE-2024-22190](https://togithub.com/gitpython-developers/GitPython/security/advisories/GHSA-2mqj-m65w-jghx)### SummaryThis issue exists because of an incomplete fix forCVE-2023-40590. OnWindows, GitPython uses an untrusted search path if it uses a shell torun `git`, as well as when it runs `bash.exe` to interpret hooks. Ifeither of those features are used on Windows, a malicious `git.exe` or`bash.exe` may be run from an untrusted repository.### DetailsAlthough GitPython often avoids executing programs found in an untrustedsearch path since 3.1.33, two situations remain where this still occurs.Either can allow arbitrary code execution under some circumstances.#### When a shell is usedGitPython can be told to run `git` commands through a shell rather thanas direct subprocesses, by passing `shell=True` to any method thataccepts it, or by both setting `Git.USE_SHELL = True` and not passing`shell=False`. Then the Windows `cmd.exe` shell process performs thepath search, and GitPython does not prevent that shell from finding andrunning `git` in the current directory.When GitPython runs `git` directly rather than through a shell, theGitPython process performs the path search, and currently omits thecurrent directory by setting `NoDefaultCurrentDirectoryInExePath` in itsown environment during the `Popen` call. Although the `cmd.exe` shellwill honor this environment variable when present, GitPython does notcurrently pass it into the shell subprocess's environment.Furthermore, because GitPython sets the subprocess CWD to the root of arepository's working tree, using a shell will run a malicious `git.exe`in an untrusted repository even if GitPython itself is run from atrusted location.This also applies if `Git.execute` is called directly with `shell=True`(or after `Git.USE_SHELL = True`) to run any command.#### When hook scripts are runOn Windows, GitPython uses `bash.exe` to run hooks that appear to bescripts. However, unlike when running `git`, no steps are taken to avoidfinding and running `bash.exe` in the current directory.This allows the author of an untrusted fork or branch to cause amalicious `bash.exe` to be run in some otherwise safe workflows. Anexample of such a scenario is if the user installs a trusted hook whileon a trusted branch, then switches to an untrusted feature branch(possibly from a fork) to review proposed changes. If the untrustedfeature branch contains a malicious `bash.exe` and the user's currentworking directory is the working tree, and the user performs an actionthat runs the hook, then although the hook itself is uncorrupted, itruns with the malicious `bash.exe`.Note that, while `bash.exe` is a shell, this is a separate scenario fromwhen `git` is run using the unrelated Windows `cmd.exe` shell.### PoCOn Windows, create a `git.exe` file in a repository. Then create a`Repo` object, and call any method through it (directly or indirectly)that supports the `shell` keyword argument with `shell=True`:```powershellmkdir testrepogit init testrepocp ... testrepo git.exe # Replace "..." with any executable of choice.python -c "import git; print(git.Repo('testrepo').git.version(shell=True))"```The `git.exe` executable in the repository directory will be run.Or use no `Repo` object, but do it from the location with the `git.exe`:```powershellcd testrepopython -c "import git; print(git.Git().version(shell=True))"```The `git.exe` executable in the current directory will be run.For the scenario with hooks, install a hook in a repository, create a`bash.exe` file in the current directory, and perform an operation thatcauses GitPython to attempt to run the hook:```powershellmkdir testrepocd testrepogit initmv .git/hooks/pre-commit.sample .git/hooks/pre-commitcp ... bash.exe # Replace "..." with any executable of choice.echo "Some text" >file.txtgit add file.txtpython -c "import git; git.Repo().index.commit('Some message')"```The `bash.exe` executable in the current directory will be run.### ImpactThe greatest impact is probably in applications that set `Git.USE_SHELL= True` for historical reasons. (Undesired console windows had, in thepast, been created in some kinds of applications, when it was not used.)Such an application may be vulnerable to arbitrary code execution from amalicious repository, even with no other exacerbating conditions. Thisis to say that, if a shell is used to run `git`, the full effect ofCVE-2023-40590 is still present. Furthermore, as noted above, runningthe application itself from a trusted directory is not a sufficientmitigation.An application that does not direct GitPython to use a shell to run`git` subprocesses thus avoids most of the risk. However, there is nosuch straightforward way to prevent GitPython from running `bash.exe` tointerpret hooks. So while the conditions needed for that to be exploitedare more involved, it may be harder to mitigate decisively prior topatching.### Possible solutionsA straightforward approach would be to address each bug directly:- When a shell is used, pass `NoDefaultCurrentDirectoryInExePath` intothe subprocess environment, because in that scenario the subprocess isthe `cmd.exe` shell that itself performs the path search.- Set `NoDefaultCurrentDirectoryInExePath` in the GitPython processenvironment during the `Popen` call made to run hooks with a `bash.exe`subprocess.These need only be done on Windows.---### Release Notes<details><summary>gitpython-developers/GitPython (GitPython)</summary>###[`v3.1.41`](https://togithub.com/gitpython-developers/GitPython/releases/tag/3.1.41):- fix Windows security issue[CompareSource](https://togithub.com/gitpython-developers/GitPython/compare/3.1.40...3.1.41)The details about the Windows security issue [can be found in thisadvisory](https://togithub.com/gitpython-developers/GitPython/security/advisories/GHSA-2mqj-m65w-jghx).Special thanks go to[@&#8203;EliahKagan](https://togithub.com/EliahKagan) who reported theissue and fixed it in a single stroke, while being responsible for anincredible amount of improvements that he contributed over the lastcouple of months ❤️.#### What's Changed- Add `__all__` in git.exc by[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in[https://github.com/gitpython-developers/GitPython/pull/1719](https://togithub.com/gitpython-developers/GitPython/pull/1719)- Set submodule update cadence to weekly by[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in[https://github.com/gitpython-developers/GitPython/pull/1721](https://togithub.com/gitpython-developers/GitPython/pull/1721)- Never modify sys.path by[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in[https://github.com/gitpython-developers/GitPython/pull/1720](https://togithub.com/gitpython-developers/GitPython/pull/1720)- Bump git/ext/gitdb from `8ec2390` to `ec58b7e` by[@&#8203;dependabot](https://togithub.com/dependabot) in[https://github.com/gitpython-developers/GitPython/pull/1722](https://togithub.com/gitpython-developers/GitPython/pull/1722)- Revise comments, docstrings, some messages, and a bit of code by[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in[https://github.com/gitpython-developers/GitPython/pull/1725](https://togithub.com/gitpython-developers/GitPython/pull/1725)- Use zero-argument super() by[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in[https://github.com/gitpython-developers/GitPython/pull/1726](https://togithub.com/gitpython-developers/GitPython/pull/1726)- Remove obsolete note in \_iter_packed_refs by[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in[https://github.com/gitpython-developers/GitPython/pull/1727](https://togithub.com/gitpython-developers/GitPython/pull/1727)- Reorganize test_util and make xfail marks precise by[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in[https://github.com/gitpython-developers/GitPython/pull/1729](https://togithub.com/gitpython-developers/GitPython/pull/1729)- Clarify license and make module top comments more consistent by[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in[https://github.com/gitpython-developers/GitPython/pull/1730](https://togithub.com/gitpython-developers/GitPython/pull/1730)- Deprecate compat.is\_<platform>, rewriting all uses by[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in[https://github.com/gitpython-developers/GitPython/pull/1732](https://togithub.com/gitpython-developers/GitPython/pull/1732)- Revise and restore some module docstrings by[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in[https://github.com/gitpython-developers/GitPython/pull/1735](https://togithub.com/gitpython-developers/GitPython/pull/1735)- Make the rmtree callback Windows-only by[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in[https://github.com/gitpython-developers/GitPython/pull/1739](https://togithub.com/gitpython-developers/GitPython/pull/1739)- List all non-passing tests in test summaries by[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in[https://github.com/gitpython-developers/GitPython/pull/1740](https://togithub.com/gitpython-developers/GitPython/pull/1740)- Document some minor subtleties in test_util.py by[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in[https://github.com/gitpython-developers/GitPython/pull/1749](https://togithub.com/gitpython-developers/GitPython/pull/1749)- Always read metadata files as UTF-8 in setup.py by[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in[https://github.com/gitpython-developers/GitPython/pull/1748](https://togithub.com/gitpython-developers/GitPython/pull/1748)- Test native Windows on CI by[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in[https://github.com/gitpython-developers/GitPython/pull/1745](https://togithub.com/gitpython-developers/GitPython/pull/1745)- Test macOS on CI by[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in[https://github.com/gitpython-developers/GitPython/pull/1752](https://togithub.com/gitpython-developers/GitPython/pull/1752)- Let close_fds be True on all platforms by[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in[https://github.com/gitpython-developers/GitPython/pull/1753](https://togithub.com/gitpython-developers/GitPython/pull/1753)- Fix IndexFile.from_tree on Windows by[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in[https://github.com/gitpython-developers/GitPython/pull/1751](https://togithub.com/gitpython-developers/GitPython/pull/1751)- Remove unused TASKKILL fallback in AutoInterrupt by[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in[https://github.com/gitpython-developers/GitPython/pull/1754](https://togithub.com/gitpython-developers/GitPython/pull/1754)- Don't return with operand when conceptually void by[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in[https://github.com/gitpython-developers/GitPython/pull/1755](https://togithub.com/gitpython-developers/GitPython/pull/1755)- Group .gitignore entries by purpose by[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in[https://github.com/gitpython-developers/GitPython/pull/1758](https://togithub.com/gitpython-developers/GitPython/pull/1758)- Adding dubious ownership handling by[@&#8203;marioaag](https://togithub.com/marioaag) in[https://github.com/gitpython-developers/GitPython/pull/1746](https://togithub.com/gitpython-developers/GitPython/pull/1746)- Avoid brittle assumptions about preexisting temporary files in testsby [@&#8203;EliahKagan](https://togithub.com/EliahKagan) in[https://github.com/gitpython-developers/GitPython/pull/1759](https://togithub.com/gitpython-developers/GitPython/pull/1759)- Overhaul noqa directives by[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in[https://github.com/gitpython-developers/GitPython/pull/1760](https://togithub.com/gitpython-developers/GitPython/pull/1760)- Clarify some Git.execute kill_after_timeout limitations by[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in[https://github.com/gitpython-developers/GitPython/pull/1761](https://togithub.com/gitpython-developers/GitPython/pull/1761)- Bump actions/setup-python from 4 to 5 by[@&#8203;dependabot](https://togithub.com/dependabot) in[https://github.com/gitpython-developers/GitPython/pull/1763](https://togithub.com/gitpython-developers/GitPython/pull/1763)- Don't install black on Cygwin by[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in[https://github.com/gitpython-developers/GitPython/pull/1766](https://togithub.com/gitpython-developers/GitPython/pull/1766)- Extract all "import gc" to module level by[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in[https://github.com/gitpython-developers/GitPython/pull/1765](https://togithub.com/gitpython-developers/GitPython/pull/1765)- Extract remaining local "import gc" to module level by[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in[https://github.com/gitpython-developers/GitPython/pull/1768](https://togithub.com/gitpython-developers/GitPython/pull/1768)- Replace xfail with gc.collect in TestSubmodule.test_rename by[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in[https://github.com/gitpython-developers/GitPython/pull/1767](https://togithub.com/gitpython-developers/GitPython/pull/1767)- Enable CodeQL by [@&#8203;EliahKagan](https://togithub.com/EliahKagan)in[https://github.com/gitpython-developers/GitPython/pull/1769](https://togithub.com/gitpython-developers/GitPython/pull/1769)- Replace some uses of the deprecated mktemp function by[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in[https://github.com/gitpython-developers/GitPython/pull/1770](https://togithub.com/gitpython-developers/GitPython/pull/1770)- Bump github/codeql-action from 2 to 3 by[@&#8203;dependabot](https://togithub.com/dependabot) in[https://github.com/gitpython-developers/GitPython/pull/1773](https://togithub.com/gitpython-developers/GitPython/pull/1773)- Run some Windows environment variable tests only on Windows by[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in[https://github.com/gitpython-developers/GitPython/pull/1774](https://togithub.com/gitpython-developers/GitPython/pull/1774)- Fix TemporaryFileSwap regression where file_path could not be Path by[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in[https://github.com/gitpython-developers/GitPython/pull/1776](https://togithub.com/gitpython-developers/GitPython/pull/1776)- Improve hooks tests by[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in[https://github.com/gitpython-developers/GitPython/pull/1777](https://togithub.com/gitpython-developers/GitPython/pull/1777)- Fix if items of Index is of type PathLike by[@&#8203;stegm](https://togithub.com/stegm) in[https://github.com/gitpython-developers/GitPython/pull/1778](https://togithub.com/gitpython-developers/GitPython/pull/1778)- Better document IterableObj.iter_items and improve some subclasses by[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in[https://github.com/gitpython-developers/GitPython/pull/1780](https://togithub.com/gitpython-developers/GitPython/pull/1780)- Revert "Don't install black on Cygwin" by[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in[https://github.com/gitpython-developers/GitPython/pull/1783](https://togithub.com/gitpython-developers/GitPython/pull/1783)- Add missing pip in $PATH on Cygwin CI by[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in[https://github.com/gitpython-developers/GitPython/pull/1784](https://togithub.com/gitpython-developers/GitPython/pull/1784)- Shorten Iterable docstrings and put IterableObj first by[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in[https://github.com/gitpython-developers/GitPython/pull/1785](https://togithub.com/gitpython-developers/GitPython/pull/1785)- Fix incompletely revised Iterable/IterableObj docstrings by[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in[https://github.com/gitpython-developers/GitPython/pull/1786](https://togithub.com/gitpython-developers/GitPython/pull/1786)- Pre-deprecate setting Git.USE_SHELL by[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in[https://github.com/gitpython-developers/GitPython/pull/1782](https://togithub.com/gitpython-developers/GitPython/pull/1782)- Deprecate Git.USE_SHELL by[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in[https://github.com/gitpython-developers/GitPython/pull/1787](https://togithub.com/gitpython-developers/GitPython/pull/1787)- In handle_process_output don't forward finalizer result by[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in[https://github.com/gitpython-developers/GitPython/pull/1788](https://togithub.com/gitpython-developers/GitPython/pull/1788)- Fix mypy warning "Missing return statement" by[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in[https://github.com/gitpython-developers/GitPython/pull/1789](https://togithub.com/gitpython-developers/GitPython/pull/1789)- Fix two remaining Windows untrusted search path cases by[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in[https://github.com/gitpython-developers/GitPython/pull/1792](https://togithub.com/gitpython-developers/GitPython/pull/1792)#### New Contributors- [@&#8203;marioaag](https://togithub.com/marioaag) made their firstcontribution in[https://github.com/gitpython-developers/GitPython/pull/1746](https://togithub.com/gitpython-developers/GitPython/pull/1746)- [@&#8203;stegm](https://togithub.com/stegm) made their firstcontribution in[https://github.com/gitpython-developers/GitPython/pull/1778](https://togithub.com/gitpython-developers/GitPython/pull/1778)**Full Changelog**:gitpython-developers/GitPython@3.1.40...3.1.41</details>---### Configuration📅 **Schedule**: Branch creation - "" (UTC), Automerge - At any time (noschedule defined).🚦 **Automerge**: Disabled by config. Please merge this manually once youare satisfied.♻ **Rebasing**: Whenever PR becomes conflicted, or you tick therebase/retry checkbox.🔕 **Ignore**: Close this PR and you won't be reminded about this updateagain.---- [ ] <!-- rebase-check -->If you want to rebase/retry this PR, checkthis box---This PR has been generated by [MendRenovate](https://www.mend.io/free-developer-tools/renovate/). Viewrepository job log[here](https://developer.mend.io/github/googleapis/sdk-platform-java).<!--renovate-debug:eyJjcmVhdGVkSW5WZXIiOiIzNy4yNjkuMiIsInVwZGF0ZWRJblZlciI6IjM3LjI2OS4yIiwidGFyZ2V0QnJhbmNoIjoibWFpbiJ9-->
Sign up for freeto join this conversation on GitHub. Already have an account?Sign in to comment
Reviewers

@ByronByronByron approved these changes

Assignees
No one assigned
Labels
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.

2 participants
@EliahKagan@Byron
[8]ページ先頭
©2009-2025 Movatter.jp