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

{git_nested-1.2.0 → git_nested-1.2.1}/.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`
@@ -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/src/git_nested.egg-info → git_nested-1.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: git-nested
-Version: 1.2.0
+Version: 1.2.1
 Summary: Git Submodule Alternative
 Author-email: Thorsten Klein <thorsten.klein.git@gmail.com>
 License: MIT
@@ -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)

{git_nested-1.2.0 → git_nested-1.2.1}/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)

{git_nested-1.2.0 → git_nested-1.2.1}/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.1}/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.1/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.1/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.1}/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,7 @@ 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
             git-nested->>Git: rev-parse <nested_commit_ref>
             git-nested->>Git: add -f -- <subdir>/.gitnested
             git-nested->>Git: diff --cached --quiet
@@ -132,7 +132,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
@@ -282,7 +282,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: diff --cached --quiet
                 git-nested->>Git: commit --no-verify [--signoff] [-S] -m <message>
@@ -304,7 +304,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
@@ -416,7 +416,7 @@ 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
         git-nested->>Git: commit --no-verify [--signoff] [-S] -m <message>
         Note over git-nested: If it fails: reset -q --hard HEAD
@@ -652,7 +652,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: rev-parse <nested_commit_ref>
         git-nested->>Git: add -f -- <subdir>/.gitnested
         git-nested->>Git: diff --cached --quiet

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

@@ -79,7 +79,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 |

{git_nested-1.2.0 → git_nested-1.2.1}/doc/concepts/glossary.md

@@ -3,7 +3,7 @@
 The words this documentation uses, in alphabetical order.
 
 **`.gitnested` file**
-: A small YAML file in each nested folder. It records the upstream, the
+: A small YAML or TOML file in each nested folder. It records the upstream, the
   branch, the upstream commit and the sync point. It is committed to your
   repository, but never pushed upstream. See
   [The `.gitnested` file](../configuration/gitnested-file.md).

{git_nested-1.2.0 → git_nested-1.2.1}/doc/conf.py

@@ -82,6 +82,10 @@ html_static_path = ['_static']
 html_css_files = ['custom.css']
 html_js_files = ['custom.js']
 
+# The logo on top of the sidebar. The browser tab shows only its mark.
+html_logo = '_static/logo.svg'
+html_favicon = '_static/favicon.svg'
+
 html_theme_options = {
     'collapse_navigation': False,
     'navigation_depth': 3,

git_nested-1.2.1/doc/configuration/examples.md

@@ -0,0 +1,259 @@
+# `.gitnested` examples
+
+This page shows how `.gitnested` looks in common cases. Each example comes
+in YAML and in TOML. Both mean the same.
+
+- YAML is the default.
+- TOML needs Python 3.11 or newer. See
+  [The `.gitnested` file](gitnested-file.md#toml).
+- [The `.gitnested` file](gitnested-file.md) explains every field.
+
+git-nested writes most fields itself. You set the others with
+[`git nested config`](../cli/config.md) or with options of `clone`.
+
+## After a clone
+
+```bash
+git nested clone https://github.com/user/lib ext/lib
+```
+
+YAML:
+
+```yaml
+# This subdirectory is managed by "git nested".
+# Refer to: https://github.com/thorsten-klein/git-nested#readme
+#
+nested:
+  commit: 401b344cd6917389538657fa06cd5f007dfb664c
+  method: merge
+  cmdver: 1.1.1
+  remote: https://github.com/user/lib
+  branch: main
+  parent: b2dfdc71d112c5e7102726c32c323901a9457630
+```
+
+TOML:
+
+```toml
+# This subdirectory is managed by "git nested".
+# Refer to: https://github.com/thorsten-klein/git-nested#readme
+#
+[nested]
+commit = "401b344cd6917389538657fa06cd5f007dfb664c"
+method = "merge"
+cmdver = "1.1.1"
+remote = "https://github.com/user/lib"
+branch = "main"
+parent = "b2dfdc71d112c5e7102726c32c323901a9457630"
+```
+
+The examples below leave out the comment lines on top.
+
+## The smallest file
+
+Only `remote` and `branch` are needed. git-nested fills in the rest on the
+next pull.
+
+YAML:
+
+```yaml
+nested:
+  remote: https://github.com/user/lib
+  branch: main
+```
+
+TOML:
+
+```toml
+[nested]
+remote = "https://github.com/user/lib"
+branch = "main"
+```
+
+## No upstream yet
+
+```bash
+git nested init ext/lib
+```
+
+`init` without `-r` writes the remote `none`. Set the real remote later
+with `git nested config ext/lib remote <url>`.
+
+YAML:
+
+```yaml
+nested:
+  commit: ''
+  method: merge
+  cmdver: 1.1.1
+  remote: none
+  branch: main
+```
+
+TOML:
+
+```toml
+[nested]
+commit = ""
+method = "merge"
+cmdver = "1.1.1"
+remote = "none"
+branch = "main"
+```
+
+## Rebase, keep the upstream commits, never push
+
+```bash
+git nested clone --rebase https://github.com/user/lib ext/lib
+git nested config ext/lib squash false
+git nested config ext/lib readonly true
+```
+
+- `method: rebase` puts your changes on top of upstream.
+- `squash: false` keeps the upstream commits in your history.
+- `readonly: true` makes `push` refuse.
+
+YAML:
+
+```yaml
+nested:
+  commit: 401b344cd6917389538657fa06cd5f007dfb664c
+  method: rebase
+  cmdver: 1.1.1
+  remote: https://github.com/user/lib
+  branch: main
+  parent: b2dfdc71d112c5e7102726c32c323901a9457630
+  squash: 'false'
+  readonly: 'true'
+```
+
+TOML:
+
+```toml
+[nested]
+commit = "401b344cd6917389538657fa06cd5f007dfb664c"
+method = "rebase"
+cmdver = "1.1.1"
+remote = "https://github.com/user/lib"
+branch = "main"
+parent = "b2dfdc71d112c5e7102726c32c323901a9457630"
+squash = "false"
+readonly = "true"
+```
+
+`true` and `false` also work without quotes.
+
+## Only a part of upstream
+
+```bash
+git nested clone --filter src --filter 'docs/.*\.md' --exclude src/tests https://github.com/user/lib ext/lib
+```
+
+- `filter` lists what to take. A regular expression must match the whole
+  path.
+- `exclude` lists what to leave out.
+
+YAML:
+
+```yaml
+nested:
+  commit: 401b344cd6917389538657fa06cd5f007dfb664c
+  method: merge
+  cmdver: 1.1.1
+  filter:
+  - src
+  - docs/.*\.md
+  exclude:
+  - src/tests
+  remote: https://github.com/user/lib
+  branch: main
+  parent: b2dfdc71d112c5e7102726c32c323901a9457630
+```
+
+TOML:
+
+```toml
+[nested]
+commit = "401b344cd6917389538657fa06cd5f007dfb664c"
+method = "merge"
+cmdver = "1.1.1"
+filter = ["src", "docs/.*\\.md"]
+exclude = ["src/tests"]
+remote = "https://github.com/user/lib"
+branch = "main"
+parent = "b2dfdc71d112c5e7102726c32c323901a9457630"
+```
+
+In a TOML string, `\` is written `\\`.
+
+See [Nest only a part of upstream](../guides/partial.md).
+
+## One folder of upstream
+
+```bash
+git nested clone --path lib/python https://github.com/user/monorepo ext/lib
+```
+
+The content of `lib/python` is at the top of `ext/lib`.
+
+YAML:
+
+```yaml
+nested:
+  commit: 401b344cd6917389538657fa06cd5f007dfb664c
+  method: merge
+  cmdver: 1.1.1
+  path: lib/python
+  remote: https://github.com/user/monorepo
+  branch: main
+  parent: b2dfdc71d112c5e7102726c32c323901a9457630
+```
+
+TOML:
+
+```toml
+[nested]
+commit = "401b344cd6917389538657fa06cd5f007dfb664c"
+method = "merge"
+cmdver = "1.1.1"
+path = "lib/python"
+remote = "https://github.com/user/monorepo"
+branch = "main"
+parent = "b2dfdc71d112c5e7102726c32c323901a9457630"
+```
+
+## Pinned to a release
+
+```bash
+git nested clone --pin v2.1.0 https://github.com/user/lib ext/lib
+```
+
+A pull stays at `v2.1.0`. `git nested pull ext/lib --pin v2.2.0` moves on.
+
+YAML:
+
+```yaml
+nested:
+  commit: 9a38b6d7c1e04f2b8d5a6e3f1c2b4a7d8e9f0a1b
+  method: merge
+  cmdver: 1.1.1
+  pin: v2.1.0
+  remote: https://github.com/user/lib
+  branch: main
+  parent: b2dfdc71d112c5e7102726c32c323901a9457630
+```
+
+TOML:
+
+```toml
+[nested]
+commit = "9a38b6d7c1e04f2b8d5a6e3f1c2b4a7d8e9f0a1b"
+method = "merge"
+cmdver = "1.1.1"
+pin = "v2.1.0"
+remote = "https://github.com/user/lib"
+branch = "main"
+parent = "b2dfdc71d112c5e7102726c32c323901a9457630"
+```
+
+See [Pin a release](../guides/pin.md).

{git_nested-1.2.0 → git_nested-1.2.1}/doc/configuration/git-config.md

@@ -17,6 +17,17 @@ commits. Those hooks are for your changes, not for upstream content.
 
 See [Hooks and signing](../guides/hooks-and-signing.md).
 
+### `nested.format`
+
+```bash
+git config nested.format toml
+```
+
+The format of new `.gitnested` files: `yaml` (the default) or `toml`. TOML
+needs Python 3.11 or newer. Files that exist keep their format.
+
+See [The `.gitnested` file](gitnested-file.md#toml).
+
 ### `user.signingKey`
 
 git's own setting. `-S` uses it to pick the GPG key.

{git_nested-1.2.0 → git_nested-1.2.1}/doc/configuration/gitnested-file.md

@@ -5,11 +5,13 @@ the content comes from, and how far it is in step with upstream.
 
 - It is committed to your repository.
 - It is never pushed upstream.
-- It is YAML. All fields sit under `nested:`.
+- It is YAML or TOML. All fields sit under `nested`.
 
 Read and change it with [`git nested config`](../cli/config.md), not by
 hand.
 
+See [`.gitnested` examples](examples.md) for more examples.
+
 ## Example
 
 ```yaml
@@ -25,6 +27,31 @@ nested:
   parent: b2dfdc71d112c5e7102726c32c323901a9457630
 ```
 
+## TOML
+
+With Python 3.11 or newer, `.gitnested` can also be TOML:
+
+```toml
+# This subdirectory is managed by "git nested".
+# Refer to: https://github.com/thorsten-klein/git-nested#readme
+#
+[nested]
+commit = "401b344cd6917389538657fa06cd5f007dfb664c"
+method = "merge"
+cmdver = "1.1.1"
+remote = "https://github.com/user/lib"
+branch = "main"
+parent = "b2dfdc71d112c5e7102726c32c323901a9457630"
+```
+
+- A file with a `[nested]` line is TOML. Any other file is YAML.
+- git-nested keeps the format of a file when it writes it.
+- New files are YAML. Set [`nested.format`](git-config.md#nestedformat) to
+  `toml` to get TOML instead.
+- Python 3.10 cannot read TOML. There, git-nested stops with an error.
+
+You can turn a YAML file into TOML by hand. The fields stay the same.
+
 ## Fields
 
 Fields that are not set take their default.

{git_nested-1.2.0 → git_nested-1.2.1}/doc/contributing/documentation.md

@@ -74,6 +74,9 @@ The pages are GitHub Markdown, read by [MyST](https://myst-parser.readthedocs.io
 push to `main`, it also publishes the site to the `gh_pages` branch. GitHub
 Pages serves it at <https://thorsten-klein.github.io/git-nested/>.
 
+A release tag like `1.2.0` publishes the site again. Then the site shows
+the release version.
+
 To publish by hand, start the workflow in the Actions tab, or run:
 
 ```bash

{git_nested-1.2.0 → git_nested-1.2.1}/doc/index.md

@@ -1,5 +1,7 @@
 # git-nested
 
+<img src="https://raw.githubusercontent.com/thorsten-klein/git-nested/main/doc/_static/logo.svg" alt="git-nested logo" width="500"/>
+
 Put another repository into a folder of yours. Pull its new changes. Push
 your changes back.
 
@@ -113,6 +115,7 @@ cli/environment-variables
 What git-nested stores, and where.
 
 - [The `.gitnested` file](configuration/gitnested-file.md)
+- [`.gitnested` examples](configuration/examples.md)
 - [git config settings](configuration/git-config.md)
 
 ```{toctree}
@@ -121,6 +124,7 @@ What git-nested stores, and where.
 :hidden:
 
 configuration/gitnested-file
+configuration/examples
 configuration/git-config
 ```
 

{git_nested-1.2.0 → git_nested-1.2.1}/doc/introduction/index.md

@@ -1,5 +1,7 @@
 # About git-nested
 
+<img src="https://raw.githubusercontent.com/thorsten-klein/git-nested/main/doc/_static/logo.svg" alt="git-nested logo" width="500"/>
+
 git-nested puts another git repository into a folder of your repository.
 The files are ordinary files in ordinary commits. You can still pull new
 changes from the other repository, and push your changes back to it.

{git_nested-1.2.0 → git_nested-1.2.1}/doc/introduction/install.md

@@ -13,6 +13,7 @@
 | [Standalone executable](#standalone-executable) | Machines without Python |
 | [From source, with shell setup](#from-source-with-shell-setup) | Working on git-nested |
 | [From source, by hand](#from-source-by-hand) | Full control |
+| [From source, editable mode](#from-source-editable-mode) | Using your own changes everywhere |
 
 After the install, `git nested` works like any git command. git finds it
 because the program is called `git-nested` and is on your `PATH`.
@@ -106,6 +107,22 @@ export PATH="/path/to/git-nested/bin:$PATH"
 Add the `export` line to your shell profile (`~/.bashrc`, `~/.zshrc`) to
 keep it.
 
+### From source, editable mode
+
+This installs git-nested from your clone. Changes to the code work right
+away. You do not have to install again.
+
+```bash
+git clone https://github.com/thorsten-klein/git-nested /path/to/git-nested
+pip install -e /path/to/git-nested
+```
+
+Or as a tool of its own, with `uv`:
+
+```bash
+uv tool install --editable /path/to/git-nested
+```
+
 ## Shell completion
 
 The shell setup from source turns completion on for you. For any other way,

{git_nested-1.2.0 → git_nested-1.2.1}/src/git_nested/cli/setup.py

@@ -69,6 +69,9 @@ def setup_command(
 
     # clone and init have no .gitnested yet. clean does not need it.
     if command in ['clone', 'init', 'clean']:
+        # Check nested.format now, not after the content is in place.
+        if command != 'clean':
+            gitfile.new_file_is_toml(git)
         config = NestedConfig(remote=flags.remote or upstream or '', branch=flags.branch or '', pin=flags.pin or '')
     else:
         config = gitfile.read_config(gitnested, flags)