git-nested 1.2.0__tar.gz → 1.2.2__tar.gz

{git_nested-1.2.0 → git_nested-1.2.2}/.github/workflows/docs.yml

@@ -1,11 +1,13 @@
 name: Docs
 
 # Builds doc/ (see doc/conf.py) with Sphinx. On pull requests it only
-# builds, so a broken page fails the check. On main it also publishes the
-# site to the gh_pages branch, which GitHub Pages serves.
+# builds, so a broken page fails the check. On main and on a release tag it
+# also publishes the site to the gh_pages branch, which GitHub Pages serves.
+# A tag build shows the release version.
 on:
   push:
     branches: [main]
+    tags: ['*.*.*']
   pull_request:
     branches: ['**']
   # by hand: 'Run workflow' in the Actions tab, or `gh workflow run docs.yml`
@@ -25,7 +27,7 @@ jobs:
           # doc/conf.py shows the version from `git describe`, which needs the tags.
           fetch-depth: 0
       - name: Install uv
-        uses: astral-sh/setup-uv@v10.3.0
+        uses: astral-sh/setup-uv@v10.3.3
         with:
           python-version: '3.14'
           enable-cache: true
@@ -34,7 +36,7 @@ jobs:
       - name: Build docs
         run: uv run poe docs
       - name: Upload docs
-        if: github.event_name != 'pull_request' && github.ref == 'refs/heads/main'
+        if: github.event_name != 'pull_request' && (github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/tags/'))
         uses: actions/upload-artifact@v7
         with:
           name: docs-html
@@ -42,10 +44,14 @@ jobs:
           include-hidden-files: true
 
   # A job of its own, so only this one can write to the repository.
-  # Only main is published, also when the workflow is started by hand.
+  # Only main and tags are published, also when the workflow is started by hand.
   publish:
-    if: github.event_name != 'pull_request' && github.ref == 'refs/heads/main'
+    if: github.event_name != 'pull_request' && (github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/tags/'))
     needs: build
+    # One publish at a time: a tag and main are often pushed together.
+    concurrency:
+      group: gh-pages
+      cancel-in-progress: false
     runs-on: ubuntu-26.04
     permissions:
       contents: write

{git_nested-1.2.0 → git_nested-1.2.2}/.github/workflows/publish.yml

@@ -13,7 +13,7 @@ jobs:
         with:
           fetch-depth: 0
       - name: Install uv
-        uses: astral-sh/setup-uv@v10.3.0
+        uses: astral-sh/setup-uv@v10.3.3
         with:
           python-version: '3.13'
           enable-cache: true

{git_nested-1.2.0 → git_nested-1.2.2}/.github/workflows/test-binary.yml

@@ -38,7 +38,7 @@ jobs:
           # tags of this checkout.
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v10.3.0
+        uses: astral-sh/setup-uv@v10.3.3
         with:
           python-version: '3.13'
           enable-cache: true

{git_nested-1.2.0 → git_nested-1.2.2}/.github/workflows/test.yml

@@ -5,6 +5,15 @@ on:
     branches: [main]
   pull_request:
     branches: ['**']
+  # daily on main (scheduled runs always use the default branch), so a
+  # breaking change in a dependency, runner image or upstream download shows
+  # up even on a day without any commit
+  schedule:
+    - cron: '0 18 * * *'
+      timezone: Europe/Berlin
+  # by hand for any branch: 'Run workflow' in the Actions tab, or
+  # `gh workflow run test.yml --ref <branch>`
+  workflow_dispatch:
 
 # One run per branch/PR at a time. On a PR a newer push cancels the run in
 # progress: only the newest commit's results matter there, and waiting for a
@@ -68,7 +77,8 @@ jobs:
       fail-fast: false
       matrix:
         os: [ubuntu-26.04, macos-latest, windows-latest]
-        python-version: ['3.10', '3.11', '3.12', '3.13', '3.14']
+        # A PR runs only the oldest and newest Python. main runs all of them.
+        python-version: ${{ fromJSON(github.event_name == 'pull_request' && '["3.10", "3.14"]' || '["3.10", "3.11", "3.12", "3.13", "3.14"]') }}
 
     steps:
       - name: Checkout code
@@ -78,8 +88,29 @@ jobs:
           # authorship) needs real history, not the default shallow, tagless
           # checkout.
           fetch-depth: 0
+      # The tests start many git processes and write many small files.
+      # On Windows, Defender scans each one, which makes the tests slow.
+      - name: Turn off Defender scanning
+        if: runner.os == 'Windows'
+        shell: pwsh
+        run: Set-MpPreference -DisableRealtimeMonitoring $true
+      # A Dev Drive is a fast ReFS drive. TEMP points there, so the test
+      # repos in tmp_path live on it.
+      - name: Set up Dev Drive
+        if: runner.os == 'Windows'
+        uses: samypr100/setup-dev-drive@v4.1.0
+        with:
+          drive-size: 8GB
+          drive-path: ${{ runner.temp }}/dev_drive.vhdx
+          trusted-dev-drive: true
+          env-mapping: |
+            TEMP,{{ DEV_DRIVE }}/tmp
+            TMP,{{ DEV_DRIVE }}/tmp
+      - name: Create temp dir on Dev Drive
+        if: runner.os == 'Windows'
+        run: mkdir -p "$TEMP" && echo "TEMP=$TEMP"
       - name: Install uv
-        uses: astral-sh/setup-uv@v10.3.0
+        uses: astral-sh/setup-uv@v10.3.3
         with:
           python-version: ${{ matrix.python-version }}
           enable-cache: true

{git_nested-1.2.0/src/git_nested.egg-info → git_nested-1.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: git-nested
-Version: 1.2.0
+Version: 1.2.2
 Summary: Git Submodule Alternative
 Author-email: Thorsten Klein <thorsten.klein.git@gmail.com>
 License: MIT
@@ -8,7 +8,7 @@ Project-URL: Homepage, https://github.com/thorsten-klein/git-nested
 Project-URL: Documentation, https://thorsten-klein.github.io/git-nested/
 Project-URL: Repository, https://github.com/thorsten-klein/git-nested
 Project-URL: Issues, https://github.com/thorsten-klein/git-nested/issues
-Keywords: git,nested,submodule,nested
+Keywords: cli,dependency-management,developer-tools,git,git-extension,git-submodule,git-submodules,git-subrepo,git-subtree,git-tools,monorepo,multi-repo,nested-repositories,python,repository-management,submodules,subrepo,subtree,vendoring,version-control
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: Topic :: Software Development :: Version Control :: Git
@@ -26,6 +26,8 @@ Dynamic: license-file
 
 # git-nested
 
+<img src="https://raw.githubusercontent.com/thorsten-klein/git-nested/main/doc/_static/logo.svg" alt="logo" width="500"/>
+
 > An alternative to git-submodule and git-subtree for managing nested repositories.
 
 [![Test](https://github.com/thorsten-klein/git-nested/actions/workflows/test.yml/badge.svg)](https://github.com/thorsten-klein/git-nested/actions/workflows/test.yml)
@@ -54,6 +56,15 @@ git nested status                                      # see where everything st
 A small `.gitnested` file in the folder remembers the URL, the branch and
 the upstream commit. So the commands stay short.
 
+Your repository has submodules already? Turn them all into nested
+repositories, and keep following upstream:
+
+```bash
+git nested submodules init --recursive
+git fetch origin
+git nested submodules update origin/main
+```
+
 ## Why git-nested?
 
 - **Self-contained.** Your repository has all files. A plain `git clone`

{git_nested-1.2.0 → git_nested-1.2.2}/README.md

@@ -1,5 +1,7 @@
 # git-nested
 
+<img src="https://raw.githubusercontent.com/thorsten-klein/git-nested/main/doc/_static/logo.svg" alt="logo" width="500"/>
+
 > An alternative to git-submodule and git-subtree for managing nested repositories.
 
 [![Test](https://github.com/thorsten-klein/git-nested/actions/workflows/test.yml/badge.svg)](https://github.com/thorsten-klein/git-nested/actions/workflows/test.yml)
@@ -28,6 +30,15 @@ git nested status                                      # see where everything st
 A small `.gitnested` file in the folder remembers the URL, the branch and
 the upstream commit. So the commands stay short.
 
+Your repository has submodules already? Turn them all into nested
+repositories, and keep following upstream:
+
+```bash
+git nested submodules init --recursive
+git fetch origin
+git nested submodules update origin/main
+```
+
 ## Why git-nested?
 
 - **Self-contained.** Your repository has all files. A plain `git clone`

{git_nested-1.2.0 → git_nested-1.2.2}/doc/README.md

@@ -37,6 +37,8 @@ on GitHub, or as a website at <https://thorsten-klein.github.io/git-nested/>.
 
 - **[`configuration/gitnested-file.md`](configuration/gitnested-file.md)**:
   every field of the `.gitnested` file.
+- **[`configuration/examples.md`](configuration/examples.md)**: how
+  `.gitnested` looks in common cases, in YAML and TOML.
 - **[`configuration/git-config.md`](configuration/git-config.md)**: the
   `git config` settings git-nested reads and writes.
 

{git_nested-1.2.0 → git_nested-1.2.2}/doc/_static/custom.css

@@ -100,3 +100,12 @@
   color: #fcfcfc;
   text-decoration: underline;
 }
+
+/* 6. The logo in the sidebar (html_logo in doc/conf.py). It has no
+ *    background, so it needs a light one on the blue sidebar. */
+.wy-side-nav-search .wy-dropdown > a img.logo,
+.wy-side-nav-search > a img.logo {
+  background: #fcfcfc;
+  border-radius: 6px;
+  padding: 6px 10px;
+}

git_nested-1.2.2/doc/_static/favicon.svg

@@ -0,0 +1,29 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="8 0 256 256" width="256" height="256" role="img" aria-label="git-nested">
+<!-- outer commit tree -->
+  <g fill="none" stroke="#1B2330" stroke-width="10" stroke-linecap="round">
+    <path d="M64 40 V216"/>
+    <path d="M64 44 C 64 62, 160 48, 160 70"/>
+    <path d="M160 186 C 160 208, 64 194, 64 212"/>
+  </g>
+  <g fill="#1B2330">
+    <circle cx="64" cy="40"  r="15"/>
+    <circle cx="64" cy="128" r="15"/>
+    <circle cx="64" cy="216" r="15"/>
+  </g>
+
+  <!-- the nested repo: a commit that is itself a commit tree -->
+  <circle cx="160" cy="128" r="58" fill="#E6F6F0" stroke="#12A67E" stroke-width="10"/>
+
+  <!-- inner commit tree -->
+  <g fill="none" stroke="#0E7C5F" stroke-width="6" stroke-linecap="round">
+    <path d="M138 100 V156"/>
+    <path d="M138 104 C 138 114, 180 106, 180 118"/>
+    <path d="M180 138 C 180 150, 138 142, 138 152"/>
+  </g>
+  <g fill="#0E7C5F">
+    <circle cx="138" cy="100" r="8"/>
+    <circle cx="138" cy="128" r="8"/>
+    <circle cx="138" cy="156" r="8"/>
+  </g>
+  <circle cx="180" cy="128" r="10" fill="#FFFFFF" stroke="#0E7C5F" stroke-width="5"/>
+</svg>

git_nested-1.2.2/doc/_static/logo.svg

@@ -0,0 +1,30 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 800 256" width="800" height="256" role="img" aria-label="git-nested">
+<!-- outer commit tree -->
+  <g fill="none" stroke="#1B2330" stroke-width="10" stroke-linecap="round">
+    <path d="M64 40 V216"/>
+    <path d="M64 44 C 64 62, 160 48, 160 70"/>
+    <path d="M160 186 C 160 208, 64 194, 64 212"/>
+  </g>
+  <g fill="#1B2330">
+    <circle cx="64" cy="40"  r="15"/>
+    <circle cx="64" cy="128" r="15"/>
+    <circle cx="64" cy="216" r="15"/>
+  </g>
+
+  <!-- the nested repo: a commit that is itself a commit tree -->
+  <circle cx="160" cy="128" r="58" fill="#E6F6F0" stroke="#12A67E" stroke-width="10"/>
+
+  <!-- inner commit tree -->
+  <g fill="none" stroke="#0E7C5F" stroke-width="6" stroke-linecap="round">
+    <path d="M138 100 V156"/>
+    <path d="M138 104 C 138 114, 180 106, 180 118"/>
+    <path d="M180 138 C 180 150, 138 142, 138 152"/>
+  </g>
+  <g fill="#0E7C5F">
+    <circle cx="138" cy="100" r="8"/>
+    <circle cx="138" cy="128" r="8"/>
+    <circle cx="138" cy="156" r="8"/>
+  </g>
+  <circle cx="180" cy="128" r="10" fill="#FFFFFF" stroke="#0E7C5F" stroke-width="5"/>
+  <text x="262" y="156" font-family="'JetBrains Mono', 'Fira Code', ui-monospace, Menlo, Consolas, monospace" font-size="84" letter-spacing="-2"><tspan fill="#5B6676" font-weight="400">git-</tspan><tspan fill="#1B2330" font-weight="800">nested</tspan></text>
+</svg>

{git_nested-1.2.0 → git_nested-1.2.2}/doc/architecture/diagrams.md

@@ -53,7 +53,7 @@ sequenceDiagram
         git-nested->>Git: ls-files -- <subdir>
         git-nested->>Git: log --format=%H %T <upstream_head>
         Note over git-nested: Find the newest upstream commit<br/>whose tree matches <subdir> at HEAD
-        Note over git-nested: Write .gitnested YAML
+        Note over git-nested: Write .gitnested
         git-nested->>Git: rev-parse <matching_commit>
         git-nested->>Git: add -f -- <subdir>/.gitnested
         git-nested->>Git: commit --no-verify [--signoff] [-S] -m <message>
@@ -68,7 +68,13 @@ sequenceDiagram
             git-nested->>Git: merge-base --is-ancestor <upstream> <nested_ref>
             git-nested->>Git: ls-files -- <subdir>
             git-nested->>Git: read-tree --prefix=<subdir> -u <nested_commit_ref>
-            Note over git-nested: Write .gitnested YAML
+            Note over git-nested: Write .gitnested
+            opt patches in use
+                git-nested->>Git: checkout HEAD -- <inner repos added here>
+                git-nested->>Git: rm -r -f / checkout HEAD -- <patches-ignore paths>
+                git-nested->>Git: format-patch --zero-commit --no-signature -o <folder> <upstream>..<nested_commit_ref> -- <without local paths>
+                git-nested->>Git: add -A -f -- <folder>
+            end
             git-nested->>Git: rev-parse <nested_commit_ref>
             git-nested->>Git: add -f -- <subdir>/.gitnested
             git-nested->>Git: diff --cached --quiet
@@ -132,7 +138,7 @@ sequenceDiagram
 
     rect rgb(230, 245, 255)
         Note over git-nested,Git: update_gitrepo_file
-        Note over git-nested: Write .gitnested YAML
+        Note over git-nested: Write .gitnested
         git-nested->>Git: rev-parse <nested_commit_ref>
         git-nested->>Git: add -f -- <subdir>/.gitnested
     end
@@ -207,6 +213,13 @@ sequenceDiagram
     git-nested->>Git: diff-index --quiet --cached --ignore-submodules HEAD
     git-nested->>Git: rev-parse HEAD
 
+    opt patches in use (HEAD has a patch)
+        Note over git-nested: Stop if subdir has changes the patches do not hold
+        git-nested->>Git: worktree add --detach .git/tmp/patches/<subref> <recorded commit>
+        git-nested->>Git: am -3 --keep-cr <patch>... (in the worktree)
+        git-nested->>Git: diff --quiet HEAD <local tree> -- <without the patches folder, inner repos, patches-ignore>
+    end
+
     rect rgb(230, 245, 255)
         Note over git-nested,Git: do_fetch
         git-nested->>Git: fetch --no-tags --quiet <remote> <branch>
@@ -229,6 +242,12 @@ sequenceDiagram
             git-nested->>Git: branch -D nested/<subref>
         end
 
+        opt patches in use: instead of create_nested_branch and the merge or rebase
+            git-nested->>Git: worktree add --no-checkout -b nested/<subref> <worktree> refs/nested/<subref>/fetch
+            git-nested->>Git: am -3 --keep-cr <all patches> (in the worktree)
+            Note over git-nested: On a conflict: stop and name the patch. git am --continue goes on with the rest
+        end
+
         rect rgb(230, 245, 255)
             Note over git-nested,Git: create_nested_branch
             git-nested->>Git: rev-list refs/heads/nested/<subref> -1
@@ -265,6 +284,16 @@ sequenceDiagram
             git-nested->>Git: update-ref refs/nested/<subref>/branch nested/<subref>
         end
 
+        opt --ignore
+            Note over git-nested: Upstream, with the ignored paths from the recorded commit
+            git-nested->>Git: read-tree <upstream> (temporary index)
+            git-nested->>Git: rm --cached -r -q -f --ignore-unmatch -- <ignored>
+            git-nested->>Git: ls-tree -r -z --full-tree <recorded commit> -- <ignored>
+            git-nested->>Git: update-index -z --index-info
+            git-nested->>Git: commit-tree -p <upstream> <tree>
+            Note over git-nested: The merge and rebase below use this commit
+        end
+
         alt method = merge
             git-nested->>Git: merge --ff --no-edit refs/nested/<subref>/fetch
             Note over git-nested: (in worktree)
@@ -282,7 +311,13 @@ sequenceDiagram
                 git-nested->>Git: ls-files -- <subdir>
                 git-nested->>Git: rm -r -- <subdir>
                 git-nested->>Git: read-tree --prefix=<subdir> -u <nested_commit_ref>
-                Note over git-nested: Write .gitnested YAML
+                Note over git-nested: Write .gitnested
+                opt patches in use
+                    git-nested->>Git: checkout HEAD -- <inner repos added here>
+                    git-nested->>Git: rm -r -f / checkout HEAD -- <patches-ignore paths>
+                    git-nested->>Git: format-patch --zero-commit --no-signature -o <folder> <upstream>..<nested_commit_ref> -- <without local paths>
+                    git-nested->>Git: add -A -f -- <folder>
+                end
                 git-nested->>Git: add -f -- <subdir>/.gitnested
                 git-nested->>Git: diff --cached --quiet
                 git-nested->>Git: commit --no-verify [--signoff] [-S] -m <message>
@@ -304,7 +339,7 @@ sequenceDiagram
             git-nested->>Git: ls-files -- <subdir>
             git-nested->>Git: rm -r -- <subdir>
             git-nested->>Git: read-tree --prefix=<subdir> -u <nested_commit_ref>
-            Note over git-nested: Write .gitnested YAML
+            Note over git-nested: Write .gitnested
             git-nested->>Git: add -f -- <subdir>/.gitnested
             git-nested->>Git: commit --no-verify [--signoff] [-S] -m <message>
             git-nested->>Git: worktree prune
@@ -314,8 +349,11 @@ sequenceDiagram
         end
     end
 
-    opt Submodules of upstream that were nested, or --recurse-submodules
-        Note over git-nested: Nest each at the commit upstream pins now (as in clone)
+    opt Submodules of upstream that are nested
+        Note over git-nested: Put them back from HEAD, with your changes.<br/>Then pull each to the commit upstream pins now
+    end
+    opt --recurse-submodules
+        Note over git-nested: Nest each new one at the commit upstream pins (as in clone)
     end
 
     Note over git-nested: The commit message lists the new upstream commits
@@ -379,6 +417,8 @@ sequenceDiagram
         Note over git-nested: (Same branch creation as in pull — see pull diagram)
         git-nested->>Git: ls-tree -r -z --name-only HEAD -- <subdir>
         Note over git-nested: Also drop .gitnested.levelN files and inner nested repos upstream does not have
+        Note over git-nested: With --ignore: the ignored paths come from upstream
+        Note over git-nested: The patches folder is dropped. patches-ignore paths come from upstream
         git-nested->>Git: branch nested/<subref> <tip>
         git-nested->>Git: worktree add --no-checkout <worktree_path> nested/<subref>
         git-nested->>Git: reset -q --hard (in the worktree)
@@ -416,8 +456,10 @@ sequenceDiagram
     end
 
     opt --commit flag
-        Note over git-nested: Update .gitnested YAML
+        Note over git-nested: Update .gitnested
         git-nested->>Git: add -f -- <subdir>/.gitnested
+        Note over git-nested: Empty the patches folder: upstream has the changes now
+        git-nested->>Git: add -A -f -- <folder>
         git-nested->>Git: commit --no-verify [--signoff] [-S] -m <message>
         Note over git-nested: If it fails: reset -q --hard HEAD
     end
@@ -652,7 +694,14 @@ sequenceDiagram
         git-nested->>Git: ls-files -- <subdir>
         git-nested->>Git: rm -r -- <subdir>
         git-nested->>Git: read-tree --prefix=<subdir> -u <nested_commit_ref>
-        Note over git-nested: Write .gitnested YAML
+        Note over git-nested: Inner nested repos: checkout HEAD -- <path>, not the gitlink
+        Note over git-nested: Write .gitnested
+        opt patches in use
+            git-nested->>Git: checkout HEAD -- <inner repos added here>
+            git-nested->>Git: rm -r -f / checkout HEAD -- <patches-ignore paths>
+            git-nested->>Git: format-patch --zero-commit --no-signature -o <folder> <upstream>..<nested_commit_ref> -- <without local paths>
+            git-nested->>Git: add -A -f -- <folder>
+        end
         git-nested->>Git: rev-parse <nested_commit_ref>
         git-nested->>Git: add -f -- <subdir>/.gitnested
         git-nested->>Git: diff --cached --quiet
@@ -663,6 +712,10 @@ sequenceDiagram
         Note over git-nested: Remove empty parent dirs up to .git/tmp
         git-nested->>Git: update-ref refs/nested/<subref>/commit <nested_commit_ref>
     end
+
+    opt Inner nested repos
+        Note over git-nested: Pull each to the commit upstream pins now (as in pull)
+    end
 ```
 
 ---
@@ -728,6 +781,53 @@ sequenceDiagram
 
 ---
 
+## submodules
+
+`init` runs `init --from-submodule` for each submodule. `update` looks
+like this:
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant git-nested
+    participant Git
+
+    User->>git-nested: git nested submodules update <commit>
+    git-nested->>Git: merge-base --is-ancestor <commit> HEAD
+    Note over git-nested: Merged already: only update the nested repos that lag behind
+    opt --dry-run
+        Note over git-nested: Print the plan, also deeper down, then stop
+    end
+    git-nested->>Git: merge --no-commit --no-ff <commit>
+    Note over git-nested: Write .git/nested-submodules-update.json for --continue and --abort
+    git-nested->>Git: update-index --force-remove <gitlink>
+    Note over git-nested: Drop each gitlink and its part of .gitmodules
+    Note over git-nested: Merge .gitattributes without git-nested's block, then add the block again
+    git-nested->>Git: commit --no-edit
+    Note over git-nested: Stop on other conflicts. --continue goes on here
+    opt A submodule pull stopped before
+        Note over git-nested: --continue finishes it there, then runs commit
+    end
+
+    loop For each submodule upstream changed
+        alt moved
+            git-nested->>Git: mv <old> <new>
+        else removed
+            git-nested->>Git: rm -r <path>
+        else added
+            Note over git-nested: Same as clone. Not for update = none
+        else new pin
+            Note over git-nested: Same as pull -b <pin> -u. Skipped if it has a pin
+        end
+        git-nested->>Git: commit
+    end
+
+    opt --single-commit
+        git-nested->>Git: reset --soft <merge commit>
+        git-nested->>Git: commit --amend
+    end
+```
+
 ## diff
 
 ```mermaid
@@ -770,6 +870,131 @@ sequenceDiagram
 
 ---
 
+## verify
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant git-nested
+    participant Git
+
+    User->>git-nested: git nested verify <subdir> [--patches <patch>...]
+    git-nested->>Git: rev-parse --show-prefix
+    Note over git-nested: Below the top level: rev-parse --show-toplevel,<br/>paths rebased, then run from there
+    git-nested->>Git: rev-parse --git-dir
+    git-nested->>Git: rev-parse --git-dir
+    git-nested->>Git: symbolic-ref --short --quiet HEAD
+    git-nested->>Git: rev-parse --is-inside-work-tree
+    git-nested->>Git: rev-parse HEAD
+    Note over git-nested: Read .gitnested config
+
+    git-nested->>Git: rev-parse HEAD:<subdir>
+    git-nested->>Git: rev-list <commit>^{commit} -1
+    opt upstream commit not here
+        git-nested->>Git: fetch --no-tags --quiet <remote> <branch>
+        git-nested->>Git: rev-parse FETCH_HEAD^0
+        git-nested->>Git: update-ref refs/nested/<subref>/fetch FETCH_HEAD^0
+    end
+    opt path, filter or exclude configured
+        Note over git-nested: Build a commit with only the nested part of upstream
+        git-nested->>Git: commit-tree -p <commit> <tree>
+    end
+
+    git-nested->>Git: worktree add --detach --no-checkout .git/tmp/verify/<subref> <base>
+    git-nested->>Git: reset -q --hard (in the worktree)
+    Note over git-nested: A file a checkout made CRLF is applied as an LF copy
+    alt patches
+        git-nested->>Git: -c core.hooksPath=<empty> am -3 --quiet --no-gpg-sign --keep-cr <patch>... (in the worktree)
+    else diffs
+        loop For each diff
+            git-nested->>Git: apply --index <file> (in the worktree)
+        end
+    end
+    git-nested->>Git: commit --allow-empty --no-verify (in the worktree)
+    git-nested->>Git: diff --quiet HEAD <local tree> -- . ':(exclude,glob)**/.gitnested*' [':(exclude,literal)<path>']
+    Note over git-nested: Left out: the patches folder, inner nested repos, patches-ignore and --ignore paths
+    Note over git-nested: The diffs below use the same paths
+
+    opt it differs
+        git-nested->>Git: diff --stat HEAD <local tree>
+        alt patches
+            git-nested->>Git: diff --binary --full-index --output=<file> HEAD <local tree>
+            git-nested->>Git: apply --index <file>
+            git-nested->>Git: commit -m 'TODO: title' -m 'TODO: description'
+            git-nested->>Git: format-patch --zero-commit --no-signature -1 --start-number=<n> -o <dir> HEAD
+        else diff with --output
+            git-nested->>Git: diff --binary --output=<file> <base> <local tree>
+        end
+    end
+
+    git-nested->>Git: worktree prune
+    Note over git-nested: The worktree is removed, unless --keep
+```
+
+---
+
+## patches
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant git-nested
+    participant Git
+
+    User->>git-nested: git nested patches create|verify|drop <subdir>
+    git-nested->>Git: rev-parse --show-prefix
+    Note over git-nested: Below the top level: rev-parse --show-toplevel,<br/>paths rebased, then run from there
+    git-nested->>Git: rev-parse --git-dir
+    git-nested->>Git: rev-parse --git-dir
+    git-nested->>Git: symbolic-ref --short --quiet HEAD
+    git-nested->>Git: rev-parse --is-inside-work-tree
+    git-nested->>Git: rev-parse HEAD
+    Note over git-nested: Read .gitnested config. Refuse if the patches are off or do not work with the setup
+
+    git-nested->>Git: rev-parse HEAD:<subdir>
+    git-nested->>Git: rev-list <commit>^{commit} -1
+    opt upstream commit not here
+        git-nested->>Git: fetch --no-tags --quiet <remote> <branch>
+        git-nested->>Git: rev-parse FETCH_HEAD^0
+        git-nested->>Git: update-ref refs/nested/<subref>/fetch FETCH_HEAD^0
+    end
+
+    git-nested->>Git: worktree add --detach --no-checkout .git/tmp/patches/<subref> <commit>
+    git-nested->>Git: reset -q --hard (in the worktree)
+    opt the folder has patches (not with create --force)
+        Note over git-nested: A patch file a checkout made CRLF is applied as an LF copy
+        git-nested->>Git: -c core.hooksPath=<empty> am -3 --quiet --no-gpg-sign --keep-cr <patch>... (in the worktree)
+    end
+    git-nested->>Git: diff --stat HEAD <local tree> -- . ':(exclude,glob)**/.gitnested*' [':(exclude,literal)<path>']
+    Note over git-nested: Left out: the patches folder, inner nested repos and patches-ignore paths
+
+    opt create, and HEAD has more
+        git-nested->>Git: diff --binary --full-index --output=<file> HEAD <local tree>
+        git-nested->>Git: apply --index <file>
+        git-nested->>Git: commit -m 'TODO: title' -m 'TODO: description'
+    end
+    git-nested->>Git: format-patch --zero-commit --no-signature --no-numbered --no-cover-letter -o <scratch> <commit>..HEAD
+    Note over git-nested: Compare with the folder, byte for byte
+    alt create
+        Note over git-nested: Replace the patches in the folder if they differ
+    else verify
+        Note over git-nested: Fail if a change is not in a patch, or a patch differs
+    end
+
+    git-nested->>Git: worktree prune
+
+    opt drop <patch>...
+        Note over git-nested: Refuse a dirty working tree, and changes the patches do not hold
+        git-nested->>Git: worktree add --detach --no-checkout <tmp> <commit>
+        git-nested->>Git: am -3 --keep-cr <the other patches> (in the worktree)
+        git-nested->>Git: read-tree --prefix=<subdir> -u <result>
+        git-nested->>Git: format-patch --zero-commit --no-signature -o <folder> <commit>..<result>
+        git-nested->>Git: commit --no-verify -m '<subdir>: drop the patch <name>'
+    end
+```
+
+---
+
 ## clean
 
 ```mermaid

{git_nested-1.2.0 → git_nested-1.2.2}/doc/architecture/index.md

@@ -64,6 +64,8 @@ One module per command, for example `commands/pull.py`. Each has one
 | `history.py` | rebuilds the nested history: the core algorithm |
 | `content.py` | creates the nested branch, places its content, commits |
 | `filters.py` | applies `filter` and `exclude` |
+| `patches.py` | keeps local changes as patch files: reads, applies and writes them |
+| `patchbuild.py` | builds and checks patches in a temporary worktree |
 | `gitfile.py` | reads and writes `.gitnested`, and the level files |
 | `refs.py` | names of the nested branches and refs |
 | `worktree.py` | temporary worktrees and their branches |
@@ -79,7 +81,7 @@ One module per command, for example `commands/pull.py`. Each has one
 | `output.py` | everything git-nested prints; hides credentials |
 | `messages.py` | the long help texts, for example after a conflict |
 | `models.py` | `Flags`, `NestedConfig`, `CommandContext` |
-| `yamlio.py` | reads and writes the YAML of `.gitnested` |
+| `configio.py` | reads and writes `.gitnested`, as YAML or TOML |
 | `errors.py` | `GitNestedError`, the one exception type |
 | `constants.py` | shared names |
 | `_version.py` | the version |