Improve scripts and tool configurations

.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."