-
-
Notifications
You must be signed in to change notification settings - Fork 908
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Document manual refresh path treatment #1839
Conversation
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Thanks so much!
I consider the description a huge step up from the status quo already, and whether or not it fulfils all possible needs is something I can't evaluate either.
I'd hope the users will by asking questions if they have any, which is probably the most valuable input to making more changes.
Thanks again for all your help!
[![Mend Renovate](https://app.renovatebot.com/images/banner.svg)](https://renovatebot.com) This PR contains the following updates: | Package | Change | Age | Adoption | Passing | Confidence | |---|---|---|---|---|---| | [GitPython](https://github.com/gitpython-developers/GitPython) | `==3.1.42` -> `==3.1.43` | [![age](https://developer.mend.io/api/mc/badges/age/pypi/GitPython/3.1.43?slim=true)](https://docs.renovatebot.com/merge-confidence/) | [![adoption](https://developer.mend.io/api/mc/badges/adoption/pypi/GitPython/3.1.43?slim=true)](https://docs.renovatebot.com/merge-confidence/) | [![passing](https://developer.mend.io/api/mc/badges/compatibility/pypi/GitPython/3.1.42/3.1.43?slim=true)](https://docs.renovatebot.com/merge-confidence/) | [![confidence](https://developer.mend.io/api/mc/badges/confidence/pypi/GitPython/3.1.42/3.1.43?slim=true)](https://docs.renovatebot.com/merge-confidence/) | --- ### Release Notes <details> <summary>gitpython-developers/GitPython (GitPython)</summary> ### [`v3.1.43`](https://github.com/gitpython-developers/GitPython/releases/tag/3.1.43) [Compare Source](https://github.com/gitpython-developers/GitPython/compare/3.1.42...3.1.43) #### Particularly Important Changes These are likely to affect you, please do take a careful look. - Issue and test deprecation warnings by [@​EliahKagan](https://github.com/EliahKagan) in [https://github.com/gitpython-developers/GitPython/pull/1886](https://github.com/gitpython-developers/GitPython/pull/1886) - Fix version_info cache invalidation, typing, parsing, and serialization by [@​EliahKagan](https://github.com/EliahKagan) in [https://github.com/gitpython-developers/GitPython/pull/1838](https://github.com/gitpython-developers/GitPython/pull/1838) - Document manual refresh path treatment by [@​EliahKagan](https://github.com/EliahKagan) in [https://github.com/gitpython-developers/GitPython/pull/1839](https://github.com/gitpython-developers/GitPython/pull/1839) - Improve static typing and docstrings related to git object types by [@​EliahKagan](https://github.com/EliahKagan) in [https://github.com/gitpython-developers/GitPython/pull/1859](https://github.com/gitpython-developers/GitPython/pull/1859) #### Other Changes - Test in Docker with Alpine Linux on CI by [@​EliahKagan](https://github.com/EliahKagan) in [https://github.com/gitpython-developers/GitPython/pull/1826](https://github.com/gitpython-developers/GitPython/pull/1826) - Build online docs (RTD) with -W and dependencies by [@​EliahKagan](https://github.com/EliahKagan) in [https://github.com/gitpython-developers/GitPython/pull/1843](https://github.com/gitpython-developers/GitPython/pull/1843) - Suggest full-path refresh() in failure message by [@​EliahKagan](https://github.com/EliahKagan) in [https://github.com/gitpython-developers/GitPython/pull/1844](https://github.com/gitpython-developers/GitPython/pull/1844) - `repo.blame` and `repo.blame_incremental` now accept `None` as the `rev` parameter. by [@​Gaubbe](https://github.com/Gaubbe) in [https://github.com/gitpython-developers/GitPython/pull/1846](https://github.com/gitpython-developers/GitPython/pull/1846) - Make sure diff always uses the default diff driver when `create_patch=True` by [@​can-taslicukur](https://github.com/can-taslicukur) in [https://github.com/gitpython-developers/GitPython/pull/1832](https://github.com/gitpython-developers/GitPython/pull/1832) - Revise docstrings, comments, and a few messages by [@​EliahKagan](https://github.com/EliahKagan) in [https://github.com/gitpython-developers/GitPython/pull/1850](https://github.com/gitpython-developers/GitPython/pull/1850) - Expand what is included in the API Reference by [@​EliahKagan](https://github.com/EliahKagan) in [https://github.com/gitpython-developers/GitPython/pull/1855](https://github.com/gitpython-developers/GitPython/pull/1855) - Restore building of documentation downloads by [@​EliahKagan](https://github.com/EliahKagan) in [https://github.com/gitpython-developers/GitPython/pull/1856](https://github.com/gitpython-developers/GitPython/pull/1856) - Revise type annotations slightly by [@​EliahKagan](https://github.com/EliahKagan) in [https://github.com/gitpython-developers/GitPython/pull/1860](https://github.com/gitpython-developers/GitPython/pull/1860) - Updating regex pattern to handle unicode whitespaces. by [@​jcole-crowdstrike](https://github.com/jcole-crowdstrike) in [https://github.com/gitpython-developers/GitPython/pull/1853](https://github.com/gitpython-developers/GitPython/pull/1853) - Use upgraded pip in test fixture virtual environment by [@​EliahKagan](https://github.com/EliahKagan) in [https://github.com/gitpython-developers/GitPython/pull/1864](https://github.com/gitpython-developers/GitPython/pull/1864) - lint: replace `flake8` with `ruff` check by [@​Borda](https://github.com/Borda) in [https://github.com/gitpython-developers/GitPython/pull/1862](https://github.com/gitpython-developers/GitPython/pull/1862) - lint: switch Black with `ruff-format` by [@​Borda](https://github.com/Borda) in [https://github.com/gitpython-developers/GitPython/pull/1865](https://github.com/gitpython-developers/GitPython/pull/1865) - Update readme and tox.ini for recent tooling changes by [@​EliahKagan](https://github.com/EliahKagan) in [https://github.com/gitpython-developers/GitPython/pull/1868](https://github.com/gitpython-developers/GitPython/pull/1868) - Split tox lint env into three envs, all safe by [@​EliahKagan](https://github.com/EliahKagan) in [https://github.com/gitpython-developers/GitPython/pull/1870](https://github.com/gitpython-developers/GitPython/pull/1870) - Slightly broaden Ruff, and update and clarify tool configuration by [@​EliahKagan](https://github.com/EliahKagan) in [https://github.com/gitpython-developers/GitPython/pull/1871](https://github.com/gitpython-developers/GitPython/pull/1871) - Add a "doc" extra for documentation build dependencies by [@​EliahKagan](https://github.com/EliahKagan) in [https://github.com/gitpython-developers/GitPython/pull/1872](https://github.com/gitpython-developers/GitPython/pull/1872) - Describe `Submodule.__init__` parent_commit parameter by [@​EliahKagan](https://github.com/EliahKagan) in [https://github.com/gitpython-developers/GitPython/pull/1877](https://github.com/gitpython-developers/GitPython/pull/1877) - Include TagObject in git.types.Tree_ish by [@​EliahKagan](https://github.com/EliahKagan) in [https://github.com/gitpython-developers/GitPython/pull/1878](https://github.com/gitpython-developers/GitPython/pull/1878) - Improve Sphinx role usage, including linking Git manpages by [@​EliahKagan](https://github.com/EliahKagan) in [https://github.com/gitpython-developers/GitPython/pull/1879](https://github.com/gitpython-developers/GitPython/pull/1879) - Replace all wildcard imports with explicit imports by [@​EliahKagan](https://github.com/EliahKagan) in [https://github.com/gitpython-developers/GitPython/pull/1880](https://github.com/gitpython-developers/GitPython/pull/1880) - Clarify how tag objects are usually tree-ish and commit-ish by [@​EliahKagan](https://github.com/EliahKagan) in [https://github.com/gitpython-developers/GitPython/pull/1881](https://github.com/gitpython-developers/GitPython/pull/1881) #### New Contributors - [@​Gaubbe](https://github.com/Gaubbe) made their first contribution in [https://github.com/gitpython-developers/GitPython/pull/1846](https://github.com/gitpython-developers/GitPython/pull/1846) - [@​can-taslicukur](https://github.com/can-taslicukur) made their first contribution in [https://github.com/gitpython-developers/GitPython/pull/1832](https://github.com/gitpython-developers/GitPython/pull/1832) - [@​jcole-crowdstrike](https://github.com/jcole-crowdstrike) made their first contribution in [https://github.com/gitpython-developers/GitPython/pull/1853](https://github.com/gitpython-developers/GitPython/pull/1853) - [@​Borda](https://github.com/Borda) made their first contribution in [https://github.com/gitpython-developers/GitPython/pull/1862](https://github.com/gitpython-developers/GitPython/pull/1862) **Full Changelog**: gitpython-developers/GitPython@3.1.42...3.1.43 </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 the rebase/retry checkbox. 🔕 **Ignore**: Close this PR and you won't be reminded about this update again. --- - [ ] <!-- rebase-check -->If you want to rebase/retry this PR, check this box --- This PR has been generated by [Mend Renovate](https://www.mend.io/free-developer-tools/renovate/). View repository job log [here](https://developer.mend.io/github/allenporter/flux-local). <!--renovate-debug:eyJjcmVhdGVkSW5WZXIiOiIzNy4yNjkuMiIsInVwZGF0ZWRJblZlciI6IjM3LjI2OS4yIiwidGFyZ2V0QnJhbmNoIjoibWFpbiJ9--> Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>
[![Mend Renovate](https://app.renovatebot.com/images/banner.svg)](https://renovatebot.com) This PR contains the following updates: | Package | Change | Age | Adoption | Passing | Confidence | |---|---|---|---|---|---| | [GitPython](https://github.com/gitpython-developers/GitPython) | `==3.1.42` -> `==3.1.43` | [![age](https://developer.mend.io/api/mc/badges/age/pypi/GitPython/3.1.43?slim=true)](https://docs.renovatebot.com/merge-confidence/) | [![adoption](https://developer.mend.io/api/mc/badges/adoption/pypi/GitPython/3.1.43?slim=true)](https://docs.renovatebot.com/merge-confidence/) | [![passing](https://developer.mend.io/api/mc/badges/compatibility/pypi/GitPython/3.1.42/3.1.43?slim=true)](https://docs.renovatebot.com/merge-confidence/) | [![confidence](https://developer.mend.io/api/mc/badges/confidence/pypi/GitPython/3.1.42/3.1.43?slim=true)](https://docs.renovatebot.com/merge-confidence/) | --- ### Release Notes <details> <summary>gitpython-developers/GitPython (GitPython)</summary> ### [`v3.1.43`](https://github.com/gitpython-developers/GitPython/releases/tag/3.1.43) [Compare Source](https://github.com/gitpython-developers/GitPython/compare/3.1.42...3.1.43) #### Particularly Important Changes These are likely to affect you, please do take a careful look. - Issue and test deprecation warnings by [@​EliahKagan](https://github.com/EliahKagan) in [https://github.com/gitpython-developers/GitPython/pull/1886](https://github.com/gitpython-developers/GitPython/pull/1886) - Fix version_info cache invalidation, typing, parsing, and serialization by [@​EliahKagan](https://github.com/EliahKagan) in [https://github.com/gitpython-developers/GitPython/pull/1838](https://github.com/gitpython-developers/GitPython/pull/1838) - Document manual refresh path treatment by [@​EliahKagan](https://github.com/EliahKagan) in [https://github.com/gitpython-developers/GitPython/pull/1839](https://github.com/gitpython-developers/GitPython/pull/1839) - Improve static typing and docstrings related to git object types by [@​EliahKagan](https://github.com/EliahKagan) in [https://github.com/gitpython-developers/GitPython/pull/1859](https://github.com/gitpython-developers/GitPython/pull/1859) #### Other Changes - Test in Docker with Alpine Linux on CI by [@​EliahKagan](https://github.com/EliahKagan) in [https://github.com/gitpython-developers/GitPython/pull/1826](https://github.com/gitpython-developers/GitPython/pull/1826) - Build online docs (RTD) with -W and dependencies by [@​EliahKagan](https://github.com/EliahKagan) in [https://github.com/gitpython-developers/GitPython/pull/1843](https://github.com/gitpython-developers/GitPython/pull/1843) - Suggest full-path refresh() in failure message by [@​EliahKagan](https://github.com/EliahKagan) in [https://github.com/gitpython-developers/GitPython/pull/1844](https://github.com/gitpython-developers/GitPython/pull/1844) - `repo.blame` and `repo.blame_incremental` now accept `None` as the `rev` parameter. by [@​Gaubbe](https://github.com/Gaubbe) in [https://github.com/gitpython-developers/GitPython/pull/1846](https://github.com/gitpython-developers/GitPython/pull/1846) - Make sure diff always uses the default diff driver when `create_patch=True` by [@​can-taslicukur](https://github.com/can-taslicukur) in [https://github.com/gitpython-developers/GitPython/pull/1832](https://github.com/gitpython-developers/GitPython/pull/1832) - Revise docstrings, comments, and a few messages by [@​EliahKagan](https://github.com/EliahKagan) in [https://github.com/gitpython-developers/GitPython/pull/1850](https://github.com/gitpython-developers/GitPython/pull/1850) - Expand what is included in the API Reference by [@​EliahKagan](https://github.com/EliahKagan) in [https://github.com/gitpython-developers/GitPython/pull/1855](https://github.com/gitpython-developers/GitPython/pull/1855) - Restore building of documentation downloads by [@​EliahKagan](https://github.com/EliahKagan) in [https://github.com/gitpython-developers/GitPython/pull/1856](https://github.com/gitpython-developers/GitPython/pull/1856) - Revise type annotations slightly by [@​EliahKagan](https://github.com/EliahKagan) in [https://github.com/gitpython-developers/GitPython/pull/1860](https://github.com/gitpython-developers/GitPython/pull/1860) - Updating regex pattern to handle unicode whitespaces. by [@​jcole-crowdstrike](https://github.com/jcole-crowdstrike) in [https://github.com/gitpython-developers/GitPython/pull/1853](https://github.com/gitpython-developers/GitPython/pull/1853) - Use upgraded pip in test fixture virtual environment by [@​EliahKagan](https://github.com/EliahKagan) in [https://github.com/gitpython-developers/GitPython/pull/1864](https://github.com/gitpython-developers/GitPython/pull/1864) - lint: replace `flake8` with `ruff` check by [@​Borda](https://github.com/Borda) in [https://github.com/gitpython-developers/GitPython/pull/1862](https://github.com/gitpython-developers/GitPython/pull/1862) - lint: switch Black with `ruff-format` by [@​Borda](https://github.com/Borda) in [https://github.com/gitpython-developers/GitPython/pull/1865](https://github.com/gitpython-developers/GitPython/pull/1865) - Update readme and tox.ini for recent tooling changes by [@​EliahKagan](https://github.com/EliahKagan) in [https://github.com/gitpython-developers/GitPython/pull/1868](https://github.com/gitpython-developers/GitPython/pull/1868) - Split tox lint env into three envs, all safe by [@​EliahKagan](https://github.com/EliahKagan) in [https://github.com/gitpython-developers/GitPython/pull/1870](https://github.com/gitpython-developers/GitPython/pull/1870) - Slightly broaden Ruff, and update and clarify tool configuration by [@​EliahKagan](https://github.com/EliahKagan) in [https://github.com/gitpython-developers/GitPython/pull/1871](https://github.com/gitpython-developers/GitPython/pull/1871) - Add a "doc" extra for documentation build dependencies by [@​EliahKagan](https://github.com/EliahKagan) in [https://github.com/gitpython-developers/GitPython/pull/1872](https://github.com/gitpython-developers/GitPython/pull/1872) - Describe `Submodule.__init__` parent_commit parameter by [@​EliahKagan](https://github.com/EliahKagan) in [https://github.com/gitpython-developers/GitPython/pull/1877](https://github.com/gitpython-developers/GitPython/pull/1877) - Include TagObject in git.types.Tree_ish by [@​EliahKagan](https://github.com/EliahKagan) in [https://github.com/gitpython-developers/GitPython/pull/1878](https://github.com/gitpython-developers/GitPython/pull/1878) - Improve Sphinx role usage, including linking Git manpages by [@​EliahKagan](https://github.com/EliahKagan) in [https://github.com/gitpython-developers/GitPython/pull/1879](https://github.com/gitpython-developers/GitPython/pull/1879) - Replace all wildcard imports with explicit imports by [@​EliahKagan](https://github.com/EliahKagan) in [https://github.com/gitpython-developers/GitPython/pull/1880](https://github.com/gitpython-developers/GitPython/pull/1880) - Clarify how tag objects are usually tree-ish and commit-ish by [@​EliahKagan](https://github.com/EliahKagan) in [https://github.com/gitpython-developers/GitPython/pull/1881](https://github.com/gitpython-developers/GitPython/pull/1881) #### New Contributors - [@​Gaubbe](https://github.com/Gaubbe) made their first contribution in [https://github.com/gitpython-developers/GitPython/pull/1846](https://github.com/gitpython-developers/GitPython/pull/1846) - [@​can-taslicukur](https://github.com/can-taslicukur) made their first contribution in [https://github.com/gitpython-developers/GitPython/pull/1832](https://github.com/gitpython-developers/GitPython/pull/1832) - [@​jcole-crowdstrike](https://github.com/jcole-crowdstrike) made their first contribution in [https://github.com/gitpython-developers/GitPython/pull/1853](https://github.com/gitpython-developers/GitPython/pull/1853) - [@​Borda](https://github.com/Borda) made their first contribution in [https://github.com/gitpython-developers/GitPython/pull/1862](https://github.com/gitpython-developers/GitPython/pull/1862) **Full Changelog**: gitpython-developers/GitPython@3.1.42...3.1.43 </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 you are satisfied. ♻ **Rebasing**: Whenever PR becomes conflicted, or you tick the rebase/retry checkbox. 🔕 **Ignore**: Close this PR and you won't be reminded about these updates again. --- - [ ] <!-- rebase-check -->If you want to rebase/retry this PR, check this box --- This PR has been generated by [Mend Renovate](https://www.mend.io/free-developer-tools/renovate/). View repository job log [here](https://developer.mend.io/github/lettuce-financial/github-bot-signed-commit). <!--renovate-debug:eyJjcmVhdGVkSW5WZXIiOiIzNy4yNjkuMiIsInVwZGF0ZWRJblZlciI6IjM3LjI2OS4yIiwidGFyZ2V0QnJhbmNoIjoibWFpbiJ9-->
Fixes #1831
I've proposed some expansions of the
git.refresh
andgit.cmd.Git.refresh
docstrings to explain how they set the git command to be used, including how they set paths and how this differs between the different ways they are called. A small amount of information about other aspects is also added.This may reasonable to merge, but it may alternatively need editing. I am unsure if the most important points are clear enough. I also wonder if this can be made shorter. I'd be pleased to make further changes.
Some of the information is duplicated across those two refresh functions' docstrings. I did this because, while as argued in #1831 I don't think this is fixing a security bug in GitPython, there are security implications of an application (or other library) using GitPython getting this wrong.
Because the text is already longer than I'd like, and because I think it's more important to describe the behavior than to comment on its relevance to security, I have not mentioned security (or safety, etc.) in added text in the docstrings. I am unsure if this is the best choice. It can be contrasted to the more explicitly cautionary tone taken in the
USE_SHELL
docstring.I put more information in the
git.cmd.Git.refresh
docstring. leaving thegit.refresh
docstring less detailed. This is for two reasons. First, it is about the behavior that is part ofgit.cmd.Git.refresh
specifically. Second, when I generate the documentation locally, the API reference doesn't seem to contain anything for the top-levelgit.refresh
function that is what people should actually call (if they call any refresh functions). Putting the details in thegit.cmd.Git.refresh
docstring should make it available, assuming a documentation build that is overall working for generating the API reference (see #1840).While working on this, I noticed that, in the docstring for
USE_SHELL
, I had written broken reStructuredText for the unordered list. In my locally generated documentation, the list was run on as a continuous paragraph. The second commit here fixes that.