Merge branch 'sh'

Author: Byron

.github/dependabot.yml

@@ -3,4 +3,4 @@ updates:
 - package-ecosystem: "github-actions"
   directory: "/"
   schedule:
-      interval: "weekly"
+    interval: "weekly"

.github/workflows/cygwin-test.yml

@@ -40,7 +40,7 @@ jobs:
 
     - name: Prepare this repo for tests
       run: |
-        TRAVIS=yes ./init-tests-after-clone.sh
+        ./init-tests-after-clone.sh
 
     - name: Set git user identity and command aliases for the tests
       run: |

.github/workflows/lint.yml

@@ -14,3 +14,7 @@ jobs:
         python-version: "3.x"
 
     - uses: pre-commit/action@v3.0.0
+      with:
+        extra_args: --all-files --hook-stage manual
+      env:
+        SKIP: black-format

.github/workflows/pythonpackage.yml

@@ -37,7 +37,7 @@ jobs:
 
     - name: Prepare this repo for tests
       run: |
-        TRAVIS=yes ./init-tests-after-clone.sh
+        ./init-tests-after-clone.sh
 
     - name: Set git user identity and command aliases for the tests
       run: |

.pre-commit-config.yaml

@@ -1,17 +1,39 @@
 repos:
-  - repo: https://github.com/PyCQA/flake8
-    rev: 6.1.0
-    hooks:
-      - id: flake8
-        additional_dependencies:
-          - flake8-bugbear==23.9.16
-          - flake8-comprehensions==3.14.0
-          - flake8-typing-imports==1.14.0
-        exclude: ^doc|^git/ext/
+- repo: https://github.com/psf/black-pre-commit-mirror
+  rev: 23.9.1
+  hooks:
+  - id: black
+    alias: black-check
+    name: black (check)
+    args: [--check, --diff]
+    exclude: ^git/ext/
+    stages: [manual]
 
-  - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.4.0
-    hooks:
-      - id: check-merge-conflict
-      - id: check-toml
-      - id: check-yaml
+  - id: black
+    alias: black-format
+    name: black (format)
+    exclude: ^git/ext/
+
+- repo: https://github.com/PyCQA/flake8
+  rev: 6.1.0
+  hooks:
+  - id: flake8
+    additional_dependencies:
+    - flake8-bugbear==23.9.16
+    - flake8-comprehensions==3.14.0
+    - flake8-typing-imports==1.14.0
+    exclude: ^doc|^git/ext/
+
+- repo: https://github.com/shellcheck-py/shellcheck-py
+  rev: v0.9.0.5
+  hooks:
+  - id: shellcheck
+    args: [--color]
+    exclude: ^git/ext/
+
+- repo: https://github.com/pre-commit/pre-commit-hooks
+  rev: v4.4.0
+  hooks:
+  - id: check-toml
+  - id: check-yaml
+  - id: check-merge-conflict

Makefile

@@ -1,7 +1,10 @@
-.PHONY: all clean release force_release
+.PHONY: all lint clean release force_release
 
 all:
-	@grep -Ee '^[a-z].*:' Makefile | cut -d: -f1 | grep -vF all
+	@awk -F: '/^[[:alpha:]].*:/ && !/^all:/ {print $$1}' Makefile
+
+lint:
+	SKIP=black-format pre-commit run --all-files --hook-stage manual
 
 clean:
 	rm -rf build/ dist/ .eggs/ .tox/

README.md

@@ -76,17 +76,20 @@ To clone the [the GitHub repository](https://github.com/gitpython-developers/Git
 ```bash
 git clone https://github.com/gitpython-developers/GitPython
 cd GitPython
-git fetch --tags
 ./init-tests-after-clone.sh
 ```
 
+On Windows, `./init-tests-after-clone.sh` can be run in a Git Bash shell.
+
 If you are cloning [your own fork](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/about-forks), then replace the above `git clone` command with one that gives the URL of your fork. Or use this [`gh`](https://cli.github.com/) command (assuming you have `gh` and your fork is called `GitPython`):
 
 ```bash
 gh repo clone GitPython
 ```
 
-Having cloned the repo, create and activate your [virtual environment](https://docs.python.org/3/tutorial/venv.html). Then make an [editable install](https://pip.pypa.io/en/stable/topics/local-project-installs/#editable-installs):
+Having cloned the repo, create and activate your [virtual environment](https://docs.python.org/3/tutorial/venv.html).
+
+Then make an [editable install](https://pip.pypa.io/en/stable/topics/local-project-installs/#editable-installs):
 
 ```bash
 pip install -e ".[test]"
@@ -114,9 +117,9 @@ See [Issue #525](https://github.com/gitpython-developers/GitPython/issues/525).
 
 ### RUNNING TESTS
 
-_Important_: Right after cloning this repository, please be sure to have
-executed `git fetch --tags` followed by the `./init-tests-after-clone.sh`
-script in the repository root. Otherwise you will encounter test failures.
+_Important_: Right after cloning this repository, please be sure to have executed
+the `./init-tests-after-clone.sh` script in the repository root. Otherwise
+you will encounter test failures.
 
 On _Windows_, make sure you have `git-daemon` in your PATH. For MINGW-git, the `git-daemon.exe`
 exists in `Git\mingw64\libexec\git-core\`.
@@ -143,30 +146,41 @@ To test, run:
 pytest
 ```
 
-To lint, run:
+To lint, and apply automatic code formatting, run:
 
 ```bash
 pre-commit run --all-files
 ```
 
+- Linting without modifying code can be done with: `make lint`
+- Auto-formatting without other lint checks can be done with: `black .`
+
 To typecheck, run:
 
 ```bash
 mypy -p git
 ```
 
-For automatic code formatting, run:
+#### CI (and tox)
 
-```bash
-black .
-```
+The same linting, and running tests on all the different supported Python versions, will be performed:
+
+- Upon submitting a pull request.
+- On each push, *if* you have a fork with GitHub Actions enabled.
+- Locally, if you run [`tox`](https://tox.wiki/) (this skips any Python versions you don't have installed).
+
+#### Configuration files
+
+Specific tools:
 
-Configuration for flake8 is in the `./.flake8` file.
+- Configurations for `mypy`, `pytest`, `coverage.py`, and `black` are in `./pyproject.toml`.
+- Configuration for `flake8` is in the `./.flake8` file.
 
-Configurations for `mypy`, `pytest`, `coverage.py`, and `black` are in `./pyproject.toml`.
+Orchestration tools:
 
-The same linting and testing will also be performed against different supported python versions
-upon submitting a pull request (or on each push if you have a fork with a "main" branch and actions enabled).
+- Configuration for `pre-commit` is in the `./.pre-commit-config.yaml` file.
+- Configuration for `tox` is in `./tox.ini`.
+- Configuration for GitHub Actions (CI) is in files inside `./.github/workflows/`.
 
 ### Contributions
 

build-release.sh

@@ -6,21 +6,22 @@
 set -eEu
 
 function release_with() {
-    $1 -m build --sdist --wheel
+    "$1" -m build --sdist --wheel
 }
 
-if test -n "${VIRTUAL_ENV:-}"; then
+function suggest_venv() {
+    local venv_cmd='python -m venv env && source env/bin/activate'
+    printf "HELP: To avoid this error, use a virtual-env with '%s' instead.\n" "$venv_cmd"
+}
+
+if test -n "${VIRTUAL_ENV-}"; then
     deps=(build twine)  # Install twine along with build, as we need it later.
     echo "Virtual environment detected. Adding packages: ${deps[*]}"
     pip install --quiet --upgrade "${deps[@]}"
     echo 'Starting the build.'
     release_with python
 else
-    function suggest_venv() {
-        venv_cmd='python -m venv env && source env/bin/activate'
-        printf "HELP: To avoid this error, use a virtual-env with '%s' instead.\n" "$venv_cmd"
-    }
     trap suggest_venv ERR  # This keeps the original exit (error) code.
     echo 'Starting the build.'
-    release_with python3 # Outside a venv, use python3.
+    release_with python3  # Outside a venv, use python3.
 fi

check-version.sh

@@ -10,29 +10,39 @@ trap 'echo "$0: Check failed. Stopping." >&2' ERR
 readonly version_path='VERSION'
 readonly changes_path='doc/source/changes.rst'
 
+function check_status() {
+    git status -s "$@"
+    test -z "$(git status -s "$@")"
+}
+
+function get_latest_tag() {
+    local config_opts
+    printf -v config_opts ' -c versionsort.suffix=-%s' alpha beta pre rc RC
+    # shellcheck disable=SC2086  # Deliberately word-splitting the arguments.
+    git $config_opts tag -l '[0-9]*' --sort=-v:refname | head -n1
+}
+
 echo 'Checking current directory.'
 test "$(cd -- "$(dirname -- "$0")" && pwd)" = "$(pwd)"  # Ugly, but portable.
 
 echo "Checking that $version_path and $changes_path exist and have no uncommitted changes."
 test -f "$version_path"
 test -f "$changes_path"
-git status -s -- "$version_path" "$changes_path"
-test -z "$(git status -s -- "$version_path" "$changes_path")"
+check_status -- "$version_path" "$changes_path"
 
 # This section can be commented out, if absolutely necessary.
 echo 'Checking that ALL changes are committed.'
-git status -s --ignore-submodules
-test -z "$(git status -s --ignore-submodules)"
+check_status --ignore-submodules
 
-version_version="$(cat "$version_path")"
+version_version="$(<"$version_path")"
 changes_version="$(awk '/^[0-9]/ {print $0; exit}' "$changes_path")"
-config_opts="$(printf ' -c versionsort.suffix=-%s' alpha beta pre rc RC)"
-latest_tag="$(git $config_opts tag -l '[0-9]*' --sort=-v:refname | head -n1)"
+latest_tag="$(get_latest_tag)"
 head_sha="$(git rev-parse HEAD)"
 latest_tag_sha="$(git rev-parse "${latest_tag}^{commit}")"
 
 # Display a table of all the current version, tag, and HEAD commit information.
-echo $'\nThe VERSION must be the same in all locations, and so must the HEAD and tag SHA'
+echo
+echo 'The VERSION must be the same in all locations, and so must the HEAD and tag SHA'
 printf '%-14s = %s\n' 'VERSION file'   "$version_version" \
                       'changes.rst'    "$changes_version" \
                       'Latest tag'     "$latest_tag" \

doc/Makefile

@@ -2,14 +2,15 @@
 #
 
 # You can set these variables from the command line.
+BUILDDIR      = build
 SPHINXOPTS    = -W
 SPHINXBUILD   = sphinx-build
 PAPER         =
 
 # Internal variables.
 PAPEROPT_a4     = -D latex_paper_size=a4
 PAPEROPT_letter = -D latex_paper_size=letter
-ALLSPHINXOPTS   = -d build/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
+ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
 
 .PHONY: help clean html web pickle htmlhelp latex changes linkcheck
 
@@ -24,52 +25,52 @@ help:
 	@echo "  linkcheck to check all external links for integrity"
 
 clean:
-	-rm -rf build/*
+	-rm -rf $(BUILDDIR)/*
 
 html:
-	mkdir -p build/html build/doctrees
-	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) build/html
+	mkdir -p $(BUILDDIR)/html $(BUILDDIR)/doctrees
+	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
 	@echo
-	@echo "Build finished. The HTML pages are in build/html."
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
 
 pickle:
-	mkdir -p build/pickle build/doctrees
-	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) build/pickle
+	mkdir -p $(BUILDDIR)/pickle $(BUILDDIR)/doctrees
+	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
 	@echo
 	@echo "Build finished; now you can process the pickle files."
 
 web: pickle
 
 json:
-	mkdir -p build/json build/doctrees
-	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) build/json
+	mkdir -p $(BUILDDIR)/json $(BUILDDIR)/doctrees
+	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
 	@echo
 	@echo "Build finished; now you can process the JSON files."
 
 htmlhelp:
-	mkdir -p build/htmlhelp build/doctrees
-	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) build/htmlhelp
+	mkdir -p $(BUILDDIR)/htmlhelp $(BUILDDIR)/doctrees
+	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
 	@echo
 	@echo "Build finished; now you can run HTML Help Workshop with the" \
-	      ".hhp project file in build/htmlhelp."
+	      ".hhp project file in $(BUILDDIR)/htmlhelp."
 
 latex:
-	mkdir -p build/latex build/doctrees
-	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) build/latex
+	mkdir -p $(BUILDDIR)/latex $(BUILDDIR)/doctrees
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
 	@echo
-	@echo "Build finished; the LaTeX files are in build/latex."
+	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
 	@echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \
 	      "run these through (pdf)latex."
 
 changes:
-	mkdir -p build/changes build/doctrees
-	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) build/changes
+	mkdir -p $(BUILDDIR)/changes $(BUILDDIR)/doctrees
+	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
 	@echo
-	@echo "The overview file is in build/changes."
+	@echo "The overview file is in $(BUILDDIR)/changes."
 
 linkcheck:
-	mkdir -p build/linkcheck build/doctrees
-	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) build/linkcheck
+	mkdir -p $(BUILDDIR)/linkcheck $(BUILDDIR)/doctrees
+	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
 	@echo
 	@echo "Link check complete; look for any errors in the above output " \
-	      "or in build/linkcheck/output.txt."
+	      "or in $(BUILDDIR)/linkcheck/output.txt."

init-tests-after-clone.sh

@@ -1,18 +1,73 @@
-#!/usr/bin/env bash
+#!/bin/sh
 
-set -e
+set -eu
 
-if [[ -z "$TRAVIS" ]]; then
-  read -rp "This operation will destroy locally modified files. Continue ? [N/y]: " answer
-  if [[ ! $answer =~ [yY] ]]; then
-    exit 2
-  fi
+fallback_repo_for_tags='https://github.com/gitpython-developers/GitPython.git'
+
+ci() {
+    # For now, check just these, as a false positive could lead to data loss.
+    test -n "${TRAVIS-}" || test -n "${GITHUB_ACTIONS-}"
+}
+
+no_version_tags() {
+    test -z "$(git tag -l '[0-9]*' 'v[0-9]*')"
+}
+
+warn() {
+    if test -n "${GITHUB_ACTIONS-}"; then
+        printf '::warning ::%s\n' "$*" >&2  # Annotate workflow.
+    else
+        printf '%s\n' "$@" >&2
+    fi
+}
+
+if ! ci; then
+    printf 'This operation will destroy locally modified files. Continue ? [N/y]: ' >&2
+    read -r answer
+    case "$answer" in
+    [yY])
+        ;;
+    *)
+        exit 2 ;;
+    esac
 fi
 
+# Stop if we have run this. (You can delete __testing_point__ to let it rerun.)
+# This also keeps track of where we are, so we can get back here.
 git tag __testing_point__
-git checkout master || git checkout -b master
+
+# The tests need a branch called master.
+git checkout master -- || git checkout -b master
+
+# The tests need a reflog history on the master branch.
 git reset --hard HEAD~1
 git reset --hard HEAD~1
 git reset --hard HEAD~1
+
+# Point the master branch where we started, so we test the correct code.
 git reset --hard __testing_point__
-git submodule update --init --recursive
+
+# The tests need submodules. (On CI, they would already have been checked out.)
+if ! ci; then
+    git submodule update --init --recursive
+fi
+
+# The tests need some version tags. Try to get them even in forks. This fetches
+# other objects too. So, locally, we always do it, for a consistent experience.
+if ! ci || no_version_tags; then
+    git fetch --all --tags
+fi
+
+# If we still have no version tags, try to get them from the original repo.
+if no_version_tags; then
+    warn 'No local or remote version tags found. Trying fallback remote:' \
+         "$fallback_repo_for_tags"
+
+    # git fetch supports * but not [], and --no-tags means no *other* tags, so...
+    printf 'refs/tags/%d*:refs/tags/%d*\n' 0 0 1 1 2 2 3 3 4 4 5 5 6 6 7 7 8 8 9 9 |
+        xargs git fetch --no-tags "$fallback_repo_for_tags"
+
+    if no_version_tags; then
+        warn 'No version tags found anywhere. Some tests will fail.'
+    fi
+fi

test/test_git.py

@@ -43,7 +43,7 @@ def tearDown(self):
     def _assert_logged_for_popen(self, log_watcher, name, value):
         re_name = re.escape(name)
         re_value = re.escape(str(value))
-        re_line = re.compile(fr"DEBUG:git.cmd:Popen\(.*\b{re_name}={re_value}[,)]")
+        re_line = re.compile(rf"DEBUG:git.cmd:Popen\(.*\b{re_name}={re_value}[,)]")
         match_attempts = [re_line.match(message) for message in log_watcher.output]
         self.assertTrue(any(match_attempts), repr(log_watcher.output))
 

tox.ini

@@ -1,6 +1,6 @@
 [tox]
 requires = tox>=4
-env_list = py{37,38,39,310,311,312}, lint, mypy, black
+env_list = py{37,38,39,310,311,312}, lint, mypy, html
 
 [testenv]
 description = Run unit tests
@@ -11,25 +11,22 @@ commands = pytest --color=yes {posargs}
 
 [testenv:lint]
 description = Lint via pre-commit
-base_python = py39
-commands = pre-commit run --all-files
+base_python = py{39,310,311,312,38,37}
+set_env =
+    SKIP = black-format
+commands = pre-commit run --all-files --hook-stage manual
 
 [testenv:mypy]
 description = Typecheck with mypy
-base_python = py39
+base_python = py{39,310,311,312,38,37}
 commands = mypy -p git
 ignore_outcome = true
 
-[testenv:black]
-description = Check style with black
-base_python = py39
-commands = black --check --diff .
-
-# Run "tox -e html" for this. It is deliberately excluded from env_list, as
-# unlike the other environments, this one writes outside the .tox/ directory.
 [testenv:html]
 description = Build HTML documentation
-base_python = py39
+base_python = py{39,310,311,312,38,37}
 deps = -r doc/requirements.txt
 allowlist_externals = make
-commands = make -C doc html
+commands =
+    make BUILDDIR={env_tmp_dir}/doc/build -C doc clean
+    make BUILDDIR={env_tmp_dir}/doc/build -C doc html