git-nested 1.1.0__tar.gz → 1.1.1__tar.gz

{git_nested-1.1.0 → git_nested-1.1.1}/.fish.rc

@@ -11,7 +11,8 @@
 #------------------------------------------------------------------------------
 
 set GIT_NESTED_ROOT (dirname (realpath (status --current-filename)))
-set PATH $GIT_NESTED_ROOT/lib $PATH
+set PATH $GIT_NESTED_ROOT/bin $PATH
 
-# Load git-nested completions
-source $GIT_NESTED_ROOT/share/git-nested.fish
+# Tab completion. The script is generated by git-nested itself, from the
+# same tables the argument parser is built from, so it can never drift.
+git-nested completion fish | source

git_nested-1.1.1/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,23 @@
+---
+name: Bug report
+about: Something git-nested does that it should not
+labels: bug
+---
+
+## What happened
+
+<!-- Paste the command and its output. `-v` or `-d` output helps a lot. -->
+
+## What you expected instead
+
+## How to reproduce
+
+<!-- The shortest sequence of commands that shows it, starting from an empty
+     repository if you can. -->
+
+## Versions
+
+- git-nested: <!-- git nested --version -->
+- git: <!-- git --version -->
+- OS:
+- Installed via: <!-- pip / standalone binary / source .rc -->

git_nested-1.1.1/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Question or idea
+    url: https://github.com/thorsten-klein/git-nested/discussions
+    about: For anything that is not a bug report or a concrete feature request.
+  - name: Security vulnerability
+    url: https://github.com/thorsten-klein/git-nested/security/advisories/new
+    about: Report privately here, not as a public issue.

git_nested-1.1.1/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,15 @@
+---
+name: Feature request
+about: Something git-nested cannot do yet
+labels: enhancement
+---
+
+## What you are trying to do
+
+<!-- The workflow, not the feature. It often turns out there is already a way. -->
+
+## What you would like git-nested to do
+
+<!-- If you have a command line in mind, write it out. -->
+
+## What you do instead today

git_nested-1.1.1/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,17 @@
+## What this changes
+
+<!-- One or two sentences. What is different after this is merged? -->
+
+## Why
+
+<!-- The problem it solves. Link the issue if there is one: Fixes #123 -->
+
+## Checklist
+
+- [ ] `uv run poe all` passes (ruff, mypy, pyright, bandit, complexipy, and the
+      tests at 100% coverage)
+- [ ] New behaviour has a test
+- [ ] README / `--help` / the man page updated, if the change is visible to users
+- [ ] The PR title reads as a [Conventional Commit](https://www.conventionalcommits.org)
+      (`feat:`, `fix:`, `docs:`, …) — it becomes the squash-merge commit message
+      and the changelog line

git_nested-1.1.1/.github/dependabot.yml

@@ -0,0 +1,23 @@
+# Dependabot keeps the two things this repository pins up to date: the actions
+# every workflow runs, and the Python dependencies uv.lock records.
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+    groups:
+      # One pull request for the lot. Action bumps are almost always routine,
+      # and reviewing them together is quicker than reviewing them one by one.
+      actions:
+        patterns: ['*']
+
+  - package-ecosystem: uv
+    directory: /
+    schedule:
+      interval: weekly
+    groups:
+      # Dev tooling moves often and breaks nothing users see, so it travels
+      # together; a runtime dependency gets its own pull request.
+      dev:
+        dependency-type: development

git_nested-1.1.1/.github/release.yml

@@ -0,0 +1,22 @@
+# Categories for the notes GitHub generates from merged pull requests. The
+# repository squash-merges with Conventional Commit titles, so the labels
+# below are what sorts a PR into a section -- keep them on the PR, not on the
+# commit.
+changelog:
+  exclude:
+    labels: [skip-changelog]
+  categories:
+    - title: Breaking changes
+      labels: [breaking]
+    - title: Features
+      labels: [enhancement, feature]
+    - title: Fixes
+      labels: [bug, fix]
+    - title: Documentation
+      labels: [documentation]
+    - title: Build, CI and tooling
+      labels: [build, ci, tooling]
+    - title: Dependencies
+      labels: [dependencies]
+    - title: Other changes
+      labels: ['*']

git_nested-1.1.1/.github/workflows/build-binary.yml

@@ -0,0 +1,137 @@
+name: Build binary
+
+# Builds the standalone 'git-nested' executable for one target and uploads it
+# as an artifact. Called by test.yml (so every push/PR proves the recipe still
+# builds) and by release-binary.yml (which attaches it to the release) -- so
+# what CI exercises is built by exactly the recipe that ships, rather than a
+# lookalike that can drift away from it.
+#
+# One call builds one target: PyInstaller freezes for the machine it runs on
+# and nothing else, so Linux, macOS and Windows binaries come from three calls
+# with different 'runs-on'/'container', not from one job.
+on:
+  workflow_call:
+    inputs:
+      ref:
+        description: 'Commit/tag/branch to build. Empty: whatever triggered the caller.'
+        type: string
+        required: false
+        default: ''
+      artifact:
+        description: 'Name of the uploaded artifact'
+        type: string
+        required: false
+        default: git-nested-binary
+      runs-on:
+        description: 'Runner to build on -- ubuntu-latest, macos-latest, windows-latest'
+        type: string
+        required: false
+        default: ubuntu-latest
+      container:
+        description: 'Container to build inside (Linux only). Empty: build on the runner itself.'
+        type: string
+        required: false
+        default: almalinux:8
+      python-version:
+        description: 'Python to freeze, e.g. 3.12'
+        type: string
+        required: false
+        default: '3.12'
+    outputs:
+      archive:
+        description: 'File name of the built archive, e.g. git-nested-1.2.3-x64-linux.tar.xz. Only meaningful for a single (non-matrix) call.'
+        value: ${{ jobs.build.outputs.archive }}
+      version:
+        description: 'Version of the built git-nested, e.g. 1.2.3'
+        value: ${{ jobs.build.outputs.version }}
+
+jobs:
+  build:
+    runs-on: ${{ inputs.runs-on }}
+    # An empty string here means "no container", which is what the macOS and
+    # Windows callers pass -- containers are a Linux-runner feature.
+    #
+    # For Linux the default is almalinux:8, and that is a portability
+    # decision, not a convenience one: a PyInstaller binary links the glibc of
+    # the machine that built it, and glibc is only backward compatible, so
+    # built on ubuntu-latest it would refuse to start on anything older than
+    # that runner. AlmaLinux 8 has glibc 2.28, the oldest that still runs the
+    # node20 the actions below need, which covers every distro from Ubuntu
+    # 20.04 / Debian 10 / Fedora 29 / RHEL 8 onwards. glibc-based distros only
+    # -- musl ones (Alpine) can never run this binary.
+    container: ${{ inputs.container }}
+    # bash everywhere, including Windows, where the default is pwsh --
+    # create-python-exe.sh is one script for all three targets.
+    defaults:
+      run:
+        shell: bash
+    outputs:
+      archive: ${{ steps.build.outputs.archive }}
+      version: ${{ steps.build.outputs.version }}
+    steps:
+      # Before the checkout -- without git, actions/checkout silently falls
+      # back to downloading a tarball, and a checkout with no .git has no
+      # tags for setuptools-scm to derive the version from. Only the container
+      # needs this; a hosted runner ships all of it.
+      - name: Install build prerequisites
+        if: inputs.container != ''
+        run: dnf -y install "python${{ inputs.python-version }}" "python${{ inputs.python-version }}-pip" git tar xz
+
+      # ... and the runners get their python from here instead.
+      - uses: actions/setup-python@v7
+        if: inputs.container == ''
+        with:
+          python-version: ${{ inputs.python-version }}
+
+      - uses: actions/checkout@v7
+        with:
+          ref: ${{ inputs.ref }}
+          # the version frozen into the binary comes from the tags, and the
+          # default shallow checkout fetches none of them.
+          fetch-depth: 0
+
+      # the checkout is owned by a different user than this container's root,
+      # which git refuses to read from until told it is not a security issue.
+      - name: Trust the checkout
+        run: git config --global --add safe.directory "$GITHUB_WORKSPACE"
+
+      - name: Build the executable
+        id: build
+        run: |
+          # In the container python is installed under its versioned name; on
+          # a runner setup-python puts a plain 'python' on PATH.
+          if [ -n "${{ inputs.container }}" ]; then
+              PY="python${{ inputs.python-version }}"
+          else
+              PY=python
+          fi
+          scripts/create-python-exe.sh --output dist --python "$PY"
+          # The archive name carries the version and the target
+          # (git-nested-<version>-<arch>-<os>.tar.xz, .zip on Windows), so it
+          # cannot be spelled out ahead of time -- it is published as an
+          # output for callers that need the exact name.
+          #
+          # nullglob: only one of the two patterns ever matches (a build
+          # produces .tar.xz or .zip, never both) -- without it the unmatched
+          # pattern is passed to ls literally, ls exits non-zero trying to
+          # read it, and pipefail+errexit abort the step right here with no
+          # visible error (ls's message went to /dev/null).
+          shopt -s nullglob
+          ARCHIVE="$(ls dist/*.tar.xz dist/*.zip 2>/dev/null | head -1)"
+          test -n "$ARCHIVE" || { echo "no archive produced" >&2; exit 1; }
+          echo "archive=$(basename "$ARCHIVE")" >> "$GITHUB_OUTPUT"
+          # 'git-nested Version: X.Y.Z' -> X.Y.Z
+          EXE=dist/git-nested
+          [ -f "$EXE" ] || EXE=dist/git-nested.exe
+          echo "version=$("$EXE" --version | head -1 | cut -d' ' -f3)" >> "$GITHUB_OUTPUT"
+
+      # the archive rather than the bare executable. It is what a release
+      # actually ships, and on the two platforms where it is a .tar.xz it
+      # keeps the exec bit as well, so consumers just untar and run it.
+      - uses: actions/upload-artifact@v7
+        with:
+          name: ${{ inputs.artifact }}
+          path: |
+            dist/*.tar.xz
+            dist/*.zip
+          if-no-files-found: error

{git_nested-1.1.0 → git_nested-1.1.1}/.github/workflows/publish.yml

@@ -9,7 +9,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v7
         with:
           fetch-depth: 0
       - name: Install uv
@@ -22,7 +22,7 @@ jobs:
       - name: Build package
         run: uv run poe build
       - name: Upload dist
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v7
         with:
           name: dist
           path: dist/
@@ -37,7 +37,7 @@ jobs:
       id-token: write
     steps:
       - name: Download dist
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@v8
         with:
           name: dist
           path: dist/

{git_nested-1.1.0 → git_nested-1.1.1}/.github/workflows/release-binary.yml

@@ -1,9 +1,9 @@
 name: Release binary
 
-# Builds the single-file 'git-nested' executable (see
-# scripts/create-python-exe.sh) and attaches
-# git-nested-<version>-x64-linux.tar.xz to the release, so git-nested can be
-# used on a machine that has no python -- and no pip, no uv -- at all.
+# Builds the single-file 'git-nested' executable for Linux, macOS and Windows
+# (see scripts/create-python-exe.sh) and attaches each archive to the release,
+# so git-nested can be used on a machine that has no python -- and no pip, no
+# uv -- at all.
 #
 # Separate from publish.yml on purpose. That one is triggered by the tag push
 # and uploads to PyPI, while attaching an asset needs the GitHub *release* to
@@ -40,10 +40,27 @@ jobs:
   # test.yml so both exercise the same executable. 'env.REF' is not available
   # to a reusable workflow's inputs, so the ref is spelled out again.
   build:
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          # Intel macOS is deliberately absent: those runners are gone, and
+          # the arm64 binary is what a current Mac needs.
+          - target: linux
+            runs-on: ubuntu-latest
+            container: almalinux:8
+          - target: macos
+            runs-on: macos-latest
+            container: ''
+          - target: windows
+            runs-on: windows-latest
+            container: ''
     uses: ./.github/workflows/build-binary.yml
     with:
       ref: ${{ github.event.release.tag_name || inputs.tag || github.ref }}
-      artifact: git-nested-binary
+      artifact: git-nested-binary-${{ matrix.target }}
+      runs-on: ${{ matrix.runs-on }}
+      container: ${{ matrix.container }}
 
   # The whole pytest suite, driven through the binary that is about to be
   # attached -- the check that it is functionally complete, not just startable.
@@ -52,7 +69,7 @@ jobs:
     uses: ./.github/workflows/test-binary.yml
     with:
       ref: ${{ github.event.release.tag_name || inputs.tag || github.ref }}
-      artifact: git-nested-binary
+      artifact: git-nested-binary-linux
 
   # Proves the "runs on any x86_64 Linux" claim rather than assuming it. The
   # binary is dropped into stock distro images that have no python installed,
@@ -81,14 +98,14 @@ jobs:
           - image: archlinux:latest
             install: pacman -Sy --noconfirm git
     steps:
-      - uses: actions/download-artifact@v4
+      - uses: actions/download-artifact@v8
         with:
-          name: git-nested-binary
+          name: git-nested-binary-linux
 
-      # Named git-nested-<version>-x64-linux.tar.xz -- resolved by glob since
-      # the version isn't known here.
+      # Named git-nested-<version>-<arch>-linux.tar.xz -- resolved by glob
+      # since the version isn't known here.
       - name: Unpack
-        run: tar -xf git-nested-*-x64-linux.tar.xz
+        run: tar -xf git-nested-*-linux.tar.xz
 
       # git is the one thing that does have to be installed -- git-nested
       # drives it and refuses to start without it. Python deliberately is not:
@@ -150,17 +167,22 @@ jobs:
     permissions:
       contents: write
     steps:
-      - uses: actions/download-artifact@v4
+      # every target's artifact, unpacked side by side. 'build' is a matrix,
+      # and a matrix job's outputs are last-one-wins, so the exact file names
+      # are read off disk here rather than composed from an output.
+      - uses: actions/download-artifact@v8
         with:
-          name: git-nested-binary
+          pattern: git-nested-binary-*
+          merge-multiple: true
 
       # --clobber so re-running against an already-attached release replaces
-      # the asset instead of failing halfway. The filename is composed from
-      # 'build's version output -- this is the point that actually names the
-      # release asset, so it uses the real version rather than a glob.
-      - name: Attach git-nested-${{ needs.build.outputs.version }}-x64-linux.tar.xz to ${{ env.REF }}
+      # the assets instead of failing halfway.
+      - name: Attach the binaries to ${{ env.REF }}
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           GH_REPO: ${{ github.repository }}
-          ARCHIVE: git-nested-${{ needs.build.outputs.version }}-x64-linux.tar.xz
-        run: gh release upload "$REF" "$ARCHIVE" --clobber
+        run: |
+          mapfile -t assets < <(ls git-nested-*.tar.xz git-nested-*.zip 2>/dev/null)
+          test "${#assets[@]}" -gt 0 || { echo "no archives downloaded" >&2; exit 1; }
+          printf '%s\n' "${assets[@]}"
+          gh release upload "$REF" "${assets[@]}" --clobber

{git_nested-1.1.0 → git_nested-1.1.1}/.github/workflows/test-binary.yml

@@ -1,7 +1,7 @@
 name: Test binary
 
-# Runs the *whole* pytest suite against the standalone executable instead of
-# against the git_nested module in the checkout: conftest's GIT_NESTED_EXE
+# Runs the *whole* pytest suite against the standalone Linux executable rather
+# than against the git_nested module in the checkout: conftest's GIT_NESTED_EXE
 # routes every cmd_git_nested() call through `git nested ...` on PATH, so the
 # ~130 tests drive the frozen binary as a user would. That is what catches the
 # failures unique to freezing -- a module PyInstaller did not collect, package
@@ -30,7 +30,7 @@ jobs:
   test:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
         with:
           ref: ${{ inputs.ref }}
           # no fetch-depth: 0 needed -- the version under test is read out of
@@ -56,19 +56,19 @@ jobs:
           git config --global --add safe.directory "$PWD";
           git config --global --add safe.directory "$PWD.git";
 
-      - uses: actions/download-artifact@v4
+      - uses: actions/download-artifact@v8
         with:
           name: ${{ inputs.artifact }}
 
       # into its own directory: the env fixture puts the binary's directory on
       # PATH, and the repo root is not a good thing to put there. Named
-      # git-nested-<version>-x64-linux.tar.xz, so matched by glob. 'git-nested'
+      # git-nested-<version>-<arch>-linux.tar.xz, so matched by glob. 'git-nested'
       # inside is a symlink to the versioned binary, so both land in bin/
       # together.
       - name: Unpack the binary
         run: |
           mkdir -p bin
-          tar -C bin -xf git-nested-*-x64-linux.tar.xz
+          tar -C bin -xf git-nested-*-linux.tar.xz
           bin/git-nested --version
 
       # no coverage flags: the code being executed lives in another process

{git_nested-1.1.0 → git_nested-1.1.1}/.github/workflows/test.yml

@@ -4,26 +4,55 @@ on:
   push:
     branches: [main]
   pull_request:
-    branches: ['*']
+    branches: ['**']
+
+# One run per branch/PR at a time -- a new commit cancels whatever this
+# workflow is still running for the same ref. Not on main: every push there
+# is a merge, and each one should run to completion rather than being
+# canceled by the next.
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.ref }}
+  cancel-in-progress: ${{ github.ref != 'refs/heads/main' }}
 
 jobs:
   # Builds the standalone executable with the very script the release uses
   # (scripts/create-python-exe.sh), so a change that breaks the freeze -- a new
-  # import, a moved data file -- fails here rather than on release day. The
-  # script smoke-tests the binary it produces; release-binary.yml additionally
-  # runs it across distros before attaching it to a release.
+  # import, a moved data file -- fails here rather than on release day. All
+  # three targets, because a break is usually a break on one of them only. The
+  # script smoke-tests each binary it produces; release-binary.yml additionally
+  # runs the Linux one across distros before attaching it to a release.
   binary:
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          # Intel macOS is deliberately absent: those runners are gone, and
+          # the arm64 binary is what a current Mac needs.
+          - target: linux
+            runs-on: ubuntu-latest
+            container: almalinux:8
+          - target: macos
+            runs-on: macos-latest
+            container: ''
+          - target: windows
+            runs-on: windows-latest
+            container: ''
     uses: ./.github/workflows/build-binary.yml
     with:
-      artifact: git-nested-binary-ci
+      artifact: git-nested-binary-ci-${{ matrix.target }}
+      runs-on: ${{ matrix.runs-on }}
+      container: ${{ matrix.container }}
 
-  # ... and then runs the full pytest suite through that executable, so a
-  # binary that builds but does not work still fails the PR.
+  # ... and then runs the full pytest suite through the Linux executable, so a
+  # binary that builds but does not work still fails the PR. Linux only: the
+  # suite is the same suite either way, and what it is checking here is that
+  # freezing did not drop anything -- a per-platform answer the smoke test in
+  # create-python-exe.sh already gives for the other two.
   binary-test:
     needs: binary
     uses: ./.github/workflows/test-binary.yml
     with:
-      artifact: git-nested-binary-ci
+      artifact: git-nested-binary-ci-linux
 
   test:
     runs-on: ${{ matrix.os }}
@@ -34,7 +63,7 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v7
         with:
           # SonarCloud's blame-based analysis (new-code detection, issue
           # authorship) needs real history, not the default shallow, tagless
@@ -58,7 +87,7 @@ jobs:
         run: uv run poe all
       - name: Upload coverage reports to Codecov
         if: matrix.os == 'ubuntu-latest' && matrix.python-version == '3.14'
-        uses: codecov/codecov-action@v5
+        uses: codecov/codecov-action@v7
         with:
           token: ${{ secrets.CODECOV_TOKEN }}
       - name: Upload test results to Codecov
@@ -68,6 +97,6 @@ jobs:
           token: ${{ secrets.CODECOV_TOKEN }}
       - name: SonarCloud Scan
         if: matrix.os == 'ubuntu-latest' && matrix.python-version == '3.14'
-        uses: SonarSource/sonarqube-scan-action@v4
+        uses: SonarSource/sonarqube-scan-action@v8
         env:
           SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}

{git_nested-1.1.0 → git_nested-1.1.1}/.gitignore

@@ -1,4 +1,4 @@
-/test/tmp/
+/tests/tmp/
 __pycache__
 .venv/
 *.pyc

{git_nested-1.1.0 → git_nested-1.1.1}/.pre-commit-config.yaml

@@ -33,14 +33,15 @@ repos:
       - id: debug-statements
       - id: name-tests-test
         args: ['--pytest-test-first']
+        # tests/unit/fakes.py holds the shared test doubles. It cannot be a
+        # conftest.py -- pytest registers every conftest under the bare name
+        # 'conftest', so a second one would collide in sys.modules with
+        # tests/conftest.py, which the whole e2e suite imports by that name.
+        exclude: ^tests/unit/fakes\.py$
 
       # --- scripts --------------------------------------------------------
       - id: check-executables-have-shebangs
       - id: check-shebang-scripts-are-executable
-        # share/*.bash and share/*.sh are meant to be *sourced* into a user's
-        # shell (see share/enable-completion.sh), never executed directly --
-        # their shebang is there only so editors pick the right syntax mode.
-        exclude: ^share/
 
       # --- repo integrity -------------------------------------------------
       - id: detect-private-key

{git_nested-1.1.0 → git_nested-1.1.1}/.rc

@@ -13,7 +13,13 @@ GIT_NESTED_ROOT=$(
 ) || return
 
 export GIT_NESTED_ROOT
-export PATH=$GIT_NESTED_ROOT/lib:$PATH
+export PATH=$GIT_NESTED_ROOT/bin:$PATH
 export MANPATH=$GIT_NESTED_ROOT/man:$MANPATH
 
-source "$GIT_NESTED_ROOT/share/enable-completion.sh"
+# Tab completion. The script is generated by git-nested itself, from the
+# same tables the argument parser is built from, so it can never drift.
+if [[ -n ${ZSH_VERSION-} ]]; then
+  eval "$(git-nested completion zsh)"
+else
+  eval "$(git-nested completion bash)"
+fi

git_nested-1.1.1/CONTRIBUTING.md

@@ -0,0 +1,95 @@
+# Contributing to git-nested
+
+## Setup
+
+```bash
+git clone https://github.com/YOUR_USERNAME/git-nested
+cd git-nested
+uv sync --dev      # or: pip install -e ".[dev]"
+uv run poe all     # verify your setup: the full gate
+```
+
+## Making changes
+
+1. Branch off `main`.
+2. Make your change and add tests for it.
+3. Run `uv run poe all` before opening a PR.
+4. Open a PR against `main` and fill out the template.
+
+## How the tests are laid out
+
+```
+tests/
+  conftest.py   shared fixtures and the git-nested runner
+  unit/         fast, no repositories -- one function at a time, with fakes
+  e2e/          real git repositories in a temp dir, driven through the CLI
+```
+
+Each directory is also a marker (`-m unit`, `-m e2e`), applied by path, so a
+new test file needs nothing added to it.
+
+```bash
+uv run poe test         # everything, with the coverage gate
+uv run poe test-unit    # just the unit tests -- seconds, no coverage gate
+uv run poe test tests/e2e/test_clone.py   # one file
+uv run pytest -k clone                    # or pytest directly
+```
+
+`poe test` requires **100% line coverage** and fails below it. A line that
+genuinely cannot be reached gets a `# pragma: no cover` with a comment saying
+why.
+
+Tests run in parallel against real repositories, so a flake is possible. To
+hunt one down:
+
+```bash
+uv run poe flakefinder   # reruns the suite 200 times; add -k to narrow it
+```
+
+### The standalone executable
+
+Releases ship a single-file executable built with PyInstaller
+(`scripts/create-python-exe.sh`). Freezing can break things the module tests
+never see, so the whole suite can also run *through* the binary:
+
+```bash
+uv run poe test-exe   # build dist/git-nested and test it
+uv run poe exe        # just build it
+GIT_NESTED_EXE=dist/git-nested uv run pytest   # test an existing binary
+```
+
+CI does both: `test.yml` builds the binary and tests it on every PR;
+`release-binary.yml` repeats that across six distro images before attaching
+the asset to a release.
+
+## Code quality
+
+`uv run poe all` runs the full gate CI enforces. Each check has its own task:
+
+```bash
+uv run poe pre-commit   # repo hygiene: whitespace, YAML/TOML/JSON, shebangs
+uv run poe lint         # ruff lint
+uv run poe format       # ruff format
+uv run poe mypy         # static typing
+uv run poe pyright      # static typing (different checker, both must pass)
+uv run poe bandit       # security linting
+uv run poe pip-audit    # dependency vulnerability scan
+uv run poe complexity   # cognitive complexity (complexipy)
+```
+
+## Commit messages
+
+Imperative mood ("Add", not "Added"), first line under 72 characters,
+reference issues where relevant.
+
+## Documentation
+
+Update [README.md](README.md) for user-facing changes and
+[docs/diagrams.md](docs/diagrams.md) when a command's underlying git calls
+change.
+
+## Reporting bugs and security issues
+
+Open a GitHub issue with steps to reproduce, expected vs. actual behaviour,
+and your git-nested/git/Python versions. For security vulnerabilities, see
+[SECURITY.md](SECURITY.md) instead of opening a public issue.