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

git_nested-1.1.0/.github/CODEOWNERS

@@ -0,0 +1,10 @@
+# Code owners for git-nested
+#
+# Owners listed here are automatically requested for review on pull requests
+# that touch matching files. The last matching pattern wins.
+#
+# Note: GitHub never requests a review from the author of the pull request,
+# so PRs opened by an owner get no automatic reviewer.
+
+# Default owner for everything in the repository
+* @thorsten-klein

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

@@ -0,0 +1,78 @@
+name: Build binary
+
+# Builds the standalone 'git-nested' executable 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.
+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
+    outputs:
+      version:
+        description: 'Version of the built git-nested, e.g. 1.2.3 -- for composing the exact git-nested-<version>-x64-linux.tar.xz filename in a caller'
+        value: ${{ jobs.build.outputs.version }}
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    # A PyInstaller binary links the glibc of the machine that built it, and
+    # glibc is only backward compatible -- 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: almalinux:8
+    outputs:
+      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.
+      - name: Install build prerequisites
+        run: dnf -y install python3.12 python3.12-pip git tar xz
+
+      - uses: actions/checkout@v4
+        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: |
+          scripts/create-python-exe.sh --output dist --python python3.12
+          # 'git-nested Version: X.Y.Z' -> X.Y.Z. Exposed as a job output so a
+          # caller can compose the exact git-nested-<version>-x64-linux.tar.xz
+          # filename itself (e.g. release-binary.yml's 'gh release upload')
+          # instead of globbing for it.
+          echo "version=$(dist/git-nested --version | head -1 | cut -d' ' -f3)" >> "$GITHUB_OUTPUT"
+
+      # the .tar.xz rather than the bare executable. It is what a release
+      # actually ships, and unlike a zipped artifact it keeps the exec bit,
+      # so consumers just untar and run it. Named git-nested-<version>-x64-linux
+      # by create-python-exe.sh, so the version can't be spelled out here --
+      # matched by glob instead (see steps.build.outputs.version for callers
+      # that need the exact name).
+      - uses: actions/upload-artifact@v4
+        with:
+          name: ${{ inputs.artifact }}
+          path: dist/git-nested-*-x64-linux.tar.xz
+          if-no-files-found: error

git_nested-1.1.0/.github/workflows/release-binary.yml

@@ -0,0 +1,166 @@
+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.
+#
+# 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
+# already exist, which is only guaranteed once it is published.
+on:
+  release:
+    types: [published]
+  # on-demand -- builds and verifies without touching any release. Give 'tag'
+  # to also (re-)attach the asset to an existing release, e.g. after fixing
+  # the build for one already published.
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: 'Existing release tag to build from and attach the asset to (empty: build + verify only)'
+        required: false
+        default: ''
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.release.tag_name || inputs.tag || github.ref }}
+  cancel-in-progress: true
+
+env:
+  # The release this builds. Its tag is what setuptools-scm turns into the
+  # version frozen into the binary, so checking out anything else would
+  # produce an executable that misreports itself. Empty on a plain
+  # workflow_dispatch -- then the triggering ref is built as-is.
+  REF: ${{ github.event.release.tag_name || inputs.tag || github.ref }}
+
+jobs:
+  # the glibc floor and every other build decision live there, shared with
+  # 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:
+    uses: ./.github/workflows/build-binary.yml
+    with:
+      ref: ${{ github.event.release.tag_name || inputs.tag || github.ref }}
+      artifact: git-nested-binary
+
+  # The whole pytest suite, driven through the binary that is about to be
+  # attached -- the check that it is functionally complete, not just startable.
+  test:
+    needs: build
+    uses: ./.github/workflows/test-binary.yml
+    with:
+      ref: ${{ github.event.release.tag_name || inputs.tag || github.ref }}
+      artifact: git-nested-binary
+
+  # 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,
+  # and has to drive a real nested repo end to end there.
+  verify:
+    needs: build
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          # the glibc floor it was built against, and the oldest still-
+          # supported LTS releases -- the ones a modern-runner build breaks
+          - image: almalinux:8
+            install: dnf -y install git
+          - image: ubuntu:22.04
+            install: apt-get update -qq && DEBIAN_FRONTEND=noninteractive apt-get install -y -qq git
+          - image: debian:12
+            install: apt-get update -qq && DEBIAN_FRONTEND=noninteractive apt-get install -y -qq git
+          # ... plus the current end of the range, where a binary built too
+          # old would fail instead
+          - image: ubuntu:24.04
+            install: apt-get update -qq && DEBIAN_FRONTEND=noninteractive apt-get install -y -qq git
+          - image: fedora:latest
+            install: dnf -y install git
+          - image: archlinux:latest
+            install: pacman -Sy --noconfirm git
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: git-nested-binary
+
+      # Named git-nested-<version>-x64-linux.tar.xz -- resolved by glob since
+      # the version isn't known here.
+      - name: Unpack
+        run: tar -xf git-nested-*-x64-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:
+      # if any of these images had to install it, the binary would not be
+      # doing its job.
+      - name: Write the verification script
+        run: |
+          cat > verify.sh <<'EOF'
+          set -eu
+          if command -v python3 >/dev/null; then
+              echo "note: this image happens to ship python3; the binary does not use it"
+          else
+              echo "note: no python3 in this image at all"
+          fi
+
+          git-nested --version
+
+          # invoked as `git nested`, the way users run it: git finds the
+          # subcommand by looking for a 'git-nested' on PATH.
+          git config --global user.email ci@example.com
+          git config --global user.name CI
+          git config --global init.defaultBranch master
+          git config --global --add safe.directory '*'
+
+          mkdir -p /tmp/repo/doc
+          cd /tmp/repo
+          git init -q
+          touch doc/README.md
+          git add -A
+          git commit -qm "initial"
+
+          git nested init doc
+          test -f doc/.gitnested
+          cat doc/.gitnested
+          git nested status
+          EOF
+
+      # The binary and the script are mounted in, so the distro images need
+      # neither tar/xz nor anything else to take part beyond git -- the point
+      # is that nothing else is required. 'git-nested' is now a symlink to the
+      # versioned binary, so both have to be mounted together (into PATH)
+      # rather than just the single file -- a lone symlink mount would
+      # dangle, pointing at a sibling that was never brought along.
+      - name: Run on ${{ matrix.image }}
+        run: |
+          docker run --rm \
+            -v "$PWD:/work" -w /work \
+            ${{ matrix.image }} \
+            sh -c '${{ matrix.install }} >/dev/null && export PATH="/work:$PATH" && sh verify.sh'
+
+  upload:
+    # 'build' listed directly (not just transitively via 'test'/'verify')
+    # because a job's outputs are only visible to jobs that name it in
+    # 'needs'.
+    needs: [build, test, verify]
+    # nothing to attach when workflow_dispatch ran without a tag
+    if: github.event_name == 'release' || inputs.tag != ''
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: git-nested-binary
+
+      # --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 }}
+        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

git_nested-1.1.0/.github/workflows/test-binary.yml

@@ -0,0 +1,81 @@
+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
+# 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
+# metadata missing so the version is wrong, a data file left out of the archive
+# -- none of which the module tests can see.
+#
+# Called by test.yml (every push/PR) and by release-binary.yml (before the
+# asset is attached). release-binary.yml additionally runs the binary across
+# distro images, which is the other half: this job proves the binary is
+# complete, that one proves it is portable.
+on:
+  workflow_call:
+    inputs:
+      ref:
+        description: 'Commit/tag/branch whose tests to run. Empty: whatever triggered the caller.'
+        type: string
+        required: false
+        default: ''
+      artifact:
+        description: 'Name of the artifact holding the built binary'
+        type: string
+        required: false
+        default: git-nested-binary
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ inputs.ref }}
+          # no fetch-depth: 0 needed -- the version under test is read out of
+          # the binary (conftest's _version_under_test), not derived from the
+          # tags of this checkout.
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          python-version: '3.13'
+          enable-cache: true
+
+      # for pytest, pytest-xdist and the git_nested import conftest still needs
+      # for its helpers -- the code under test comes from the binary.
+      - name: Setup project
+        run: uv sync --frozen
+
+      - name: git config
+        run: |
+          git config --global user.email "you@example.com";
+          git config --global user.name "Your Name";
+          git config --global init.defaultBranch "master";
+          git config --global --add safe.directory "$PWD";
+          git config --global --add safe.directory "$PWD.git";
+
+      - uses: actions/download-artifact@v4
+        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'
+      # 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
+          bin/git-nested --version
+
+      # no coverage flags: the code being executed lives in another process
+      # inside the frozen archive, so there is nothing here for coverage to
+      # measure. test.yml's module run is what the coverage numbers come from.
+      - name: Run the suite against the binary
+        env:
+          GIT_NESTED_EXE: ${{ github.workspace }}/bin/git-nested
+          PYTHONIOENCODING: utf-8
+        run: uv run pytest -v -n=auto -W error

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

@@ -7,6 +7,24 @@ on:
     branches: ['*']
 
 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.
+  binary:
+    uses: ./.github/workflows/build-binary.yml
+    with:
+      artifact: git-nested-binary-ci
+
+  # ... and then runs the full pytest suite through that executable, so a
+  # binary that builds but does not work still fails the PR.
+  binary-test:
+    needs: binary
+    uses: ./.github/workflows/test-binary.yml
+    with:
+      artifact: git-nested-binary-ci
+
   test:
     runs-on: ${{ matrix.os }}
     strategy:
@@ -17,6 +35,11 @@ jobs:
     steps:
       - name: Checkout code
         uses: actions/checkout@v4
+        with:
+          # SonarCloud's blame-based analysis (new-code detection, issue
+          # authorship) needs real history, not the default shallow, tagless
+          # checkout.
+          fetch-depth: 0
       - name: Install uv
         uses: astral-sh/setup-uv@v7
         with:
@@ -43,3 +66,8 @@ jobs:
         uses: codecov/test-results-action@v1
         with:
           token: ${{ secrets.CODECOV_TOKEN }}
+      - name: SonarCloud Scan
+        if: matrix.os == 'ubuntu-latest' && matrix.python-version == '3.14'
+        uses: SonarSource/sonarqube-scan-action@v4
+        env:
+          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}

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

@@ -9,5 +9,8 @@ build/
 .pytest_cache/
 .coverage
 htmlcov/
+coverage.xml
+.coverage*
+junit.xml
 *.whl
 *.tar.gz

git_nested-1.1.0/.pre-commit-config.yaml

@@ -0,0 +1,62 @@
+# Repo-wide hygiene gate. Run over the whole tree by `uv run poe pre-commit`,
+# the first step of `uv run poe all`. Nothing installs an actual git hook --
+# that stays a per-developer `pre-commit install` if you want it.
+#
+# Everything language-specific already has its own poe task backed by a version
+# pinned in pyproject.toml's `lint` dependency group -- ruff, mypy, pyright,
+# bandit, pip-audit, complexipy. Duplicating any of them here would mean a
+# second, independently-pinned copy drifting from the one CI runs, so this file
+# deliberately stays limited to the checks nothing else covers.
+repos:
+  # General pre-commit hooks
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      # --- whitespace -----------------------------------------------------
+      # .patch/.diff are excluded throughout: trailing whitespace inside a
+      # hunk is content, and git's "-- \n" signature separator is load-bearing.
+      # Rewriting either corrupts the patch.
+      - id: trailing-whitespace
+        exclude: ^.*\.(patch|diff)$
+      - id: end-of-file-fixer
+        exclude: ^.*\.(patch|diff)$
+      - id: mixed-line-ending
+        args: ['--fix=lf']
+        exclude: ^.*\.(patch|diff)$
+
+      # --- parseability of the files that configure everything else -------
+      - id: check-yaml
+      - id: check-toml
+      - id: check-json
+
+      # --- python ---------------------------------------------------------
+      - id: debug-statements
+      - id: name-tests-test
+        args: ['--pytest-test-first']
+
+      # --- 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
+      - id: check-added-large-files
+        args: ['--maxkb=500', '--enforce-all']
+      - id: check-case-conflict
+      - id: check-merge-conflict
+      - id: check-symlinks
+      - id: destroyed-symlinks
+      - id: forbid-submodules
+
+
+# Configuration
+default_language_version:
+  python: python3.12
+
+# Minimum pre-commit version -- matches the floor pyproject.toml's `lint`
+# dependency group pins.
+minimum_pre_commit_version: '4.0.0'

{git_nested-1.0.4 → git_nested-1.1.0}/CONTRIBUTING.md

@@ -65,16 +65,58 @@ uv run poe test -vv
 uv run pytest
 ```
 
+### Testing 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 — an import PyInstaller did not collect, missing package metadata —
+so the whole suite can be run *through* the binary instead:
+
+```bash
+# Build dist/git-nested and run every test against it
+uv run poe test-exe
+
+# Just build it
+uv run poe exe
+
+# Or point the tests at any executable you already have
+GIT_NESTED_EXE=dist/git-nested uv run pytest
+```
+
+With `GIT_NESTED_EXE` set, `cmd_git_nested()` in `test/conftest.py` runs
+`git nested ...` as a subprocess against that binary rather than calling the
+module in-process; without it, nothing changes. CI does both: `test.yml` builds
+the binary and runs the suite against it on every PR, and `release-binary.yml`
+repeats that plus a run across six distro images before attaching the asset to
+a release.
+
 ### Code Quality
 
-We use [Ruff](https://github.com/astral-sh/ruff) for both linting and formatting:
+`uv run poe all` runs the full gate CI enforces: repo hygiene, linting,
+formatting, static typing, security, dependency, and complexity checks, then
+the test suite. Each has its own `poe` task if you want to run just one:
 
 ```bash
-# Check code quality
-uv run poe lint
+# Repo-wide hygiene (whitespace, YAML/TOML/JSON parseability, shebangs, ...)
+uv run poe pre-commit
 
-# Auto-format code
+# Lint and auto-format with Ruff (https://github.com/astral-sh/ruff)
+uv run poe lint
 uv run poe format
+
+# Static typing -- mypy and pyright are both run since they catch
+# different things; passing both is required
+uv run poe mypy
+uv run poe pyright
+
+# Security linting (bandit) and dependency vulnerability scanning (pip-audit)
+uv run poe bandit
+uv run poe pip-audit
+
+# Cognitive complexity (complexipy); threshold is set in pyproject.toml's
+# [tool.complexipy] to catch complexity creep in new code, not to demand
+# every existing function be simple
+uv run poe complexity
 ```
 
 Make sure all checks pass before submitting your PR.

{git_nested-1.0.4 → git_nested-1.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: git-nested
-Version: 1.0.4
+Version: 1.1.0
 Summary: Git Submodule Alternative
 Author-email: Thorsten Klein <thorsten.klein.git@gmail.com>
 License: MIT
@@ -80,7 +80,32 @@ git-nested now supports nested repositories within nested repositories (recursiv
 pip install git+https://github.com/thorsten-klein/git-nested
 ```
 
-#### Method 2: From Source with Shell Integration
+#### Method 2: Standalone Executable (no Python needed)
+
+Every [release](https://github.com/thorsten-klein/git-nested/releases) ships
+`git-nested-<version>-x64-linux.tar.xz`: a single file with git-nested, its
+dependencies and a Python interpreter inside. Only git itself has to be
+installed.
+
+```bash
+# Find the asset from the latest release
+ASSET=$(curl -sSL https://api.github.com/repos/thorsten-klein/git-nested/releases/latest | grep -o 'https://[^"]*\.tar\.xz')
+
+# Download the asset and unpack it
+curl -sSL "$ASSET" | tar -xJ
+sudo install git-nested /usr/local/bin/   # any directory on PATH works
+```
+
+The file has to keep the name `git-nested` — that is how `git nested ...`
+finds it. The archive also contains a versioned copy of the binary (e.g.
+`git-nested-1.2.3`) that `git-nested` symlinks to, and the completion scripts
+from `share/`.
+
+Built on x86_64 with glibc 2.28, so it runs on any x86_64 Linux from that
+version onwards (Ubuntu 20.04, Debian 10, RHEL/AlmaLinux 8 and newer). Not on
+musl distros such as Alpine.
+
+#### Method 3: From Source with Shell Integration
 
 Adds git-nested to PATH and enables tab completion:
 
@@ -90,7 +115,7 @@ echo 'source /path/to/git-nested/.rc' >> ~/.bashrc
 source ~/.bashrc
 ```
 
-#### Method 3: From Source (Manual)
+#### Method 4: From Source (Manual)
 
 ```bash
 git clone https://github.com/thorsten-klein/git-nested /path/to/git-nested
@@ -195,6 +220,22 @@ Fetch remote content for a nested repository.
 git nested fetch --help
 ```
 
+#### `git nested diff`
+
+Show the local diff of a nested repo compared to upstream. Fetches the latest upstream
+content first, so it always compares against the freshest available state. Requires that
+there are no uncommitted changes in the outer repository.
+
+```bash
+git nested diff --help
+```
+
+**Example:**
+```bash
+git nested diff ext/lib
+git nested diff --all  # Diff all nested repos
+```
+
 #### `git nested branch`
 
 Create a branch with local nested commits for manual conflict resolution.

{git_nested-1.0.4 → git_nested-1.1.0}/README.md

@@ -54,7 +54,32 @@ git-nested now supports nested repositories within nested repositories (recursiv
 pip install git+https://github.com/thorsten-klein/git-nested
 ```
 
-#### Method 2: From Source with Shell Integration
+#### Method 2: Standalone Executable (no Python needed)
+
+Every [release](https://github.com/thorsten-klein/git-nested/releases) ships
+`git-nested-<version>-x64-linux.tar.xz`: a single file with git-nested, its
+dependencies and a Python interpreter inside. Only git itself has to be
+installed.
+
+```bash
+# Find the asset from the latest release
+ASSET=$(curl -sSL https://api.github.com/repos/thorsten-klein/git-nested/releases/latest | grep -o 'https://[^"]*\.tar\.xz')
+
+# Download the asset and unpack it
+curl -sSL "$ASSET" | tar -xJ
+sudo install git-nested /usr/local/bin/   # any directory on PATH works
+```
+
+The file has to keep the name `git-nested` — that is how `git nested ...`
+finds it. The archive also contains a versioned copy of the binary (e.g.
+`git-nested-1.2.3`) that `git-nested` symlinks to, and the completion scripts
+from `share/`.
+
+Built on x86_64 with glibc 2.28, so it runs on any x86_64 Linux from that
+version onwards (Ubuntu 20.04, Debian 10, RHEL/AlmaLinux 8 and newer). Not on
+musl distros such as Alpine.
+
+#### Method 3: From Source with Shell Integration
 
 Adds git-nested to PATH and enables tab completion:
 
@@ -64,7 +89,7 @@ echo 'source /path/to/git-nested/.rc' >> ~/.bashrc
 source ~/.bashrc
 ```
 
-#### Method 3: From Source (Manual)
+#### Method 4: From Source (Manual)
 
 ```bash
 git clone https://github.com/thorsten-klein/git-nested /path/to/git-nested
@@ -169,6 +194,22 @@ Fetch remote content for a nested repository.
 git nested fetch --help
 ```
 
+#### `git nested diff`
+
+Show the local diff of a nested repo compared to upstream. Fetches the latest upstream
+content first, so it always compares against the freshest available state. Requires that
+there are no uncommitted changes in the outer repository.
+
+```bash
+git nested diff --help
+```
+
+**Example:**
+```bash
+git nested diff ext/lib
+git nested diff --all  # Diff all nested repos
+```
+
 #### `git nested branch`
 
 Create a branch with local nested commits for manual conflict resolution.