Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,13 @@ 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:

```bash
git nested submodules init --recursive
```

## Why git-nested?

- **Self-contained.** Your repository has all files. A plain `git clone`
Expand Down
4 changes: 4 additions & 0 deletions doc/architecture/diagrams.md
Original file line number Diff line number Diff line change
Expand Up @@ -781,6 +781,10 @@ sequenceDiagram

---

## submodules

`init` runs `init --from-submodule` for each submodule.

## diff

```mermaid
Expand Down
5 changes: 3 additions & 2 deletions doc/cli/config.md
Original file line number Diff line number Diff line change
Expand Up @@ -46,6 +46,7 @@ instead of editing the file by hand.
| `patches` | the folder with the local changes as patches, relative to the subdir | yes |
| `patches-ignore` | paths in the subdir that stay local, so no patch needs their changes | no |
| `patches-local` | patches a push leaves out, by file name | no |
| `submodules` | `nest` or `keep`: whether a pull nests the submodules in it. Unset: nest | yes |

The other keys are written by the commands themselves. Setting one by hand
would describe a state the repository is not in.
Expand All @@ -68,5 +69,5 @@ git commit -m "lib: pull with rebase, never push"
- A relative path as a `remote` value is taken relative to the folder you
are in, like git does. It is stored relative to the top of your
repository.
- An unknown key, or a bad value for `method`, `squash` or `readonly`, is
refused.
- An unknown key, or a bad value for `method`, `squash`, `readonly` or
`submodules`, is refused.
1 change: 1 addition & 0 deletions doc/cli/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,7 @@ Each command has its own page. This page lists what they share.
| [`push`](push.md) | push a nested repository's local changes upstream |
| [`fetch`](fetch.md) | fetch upstream content for a nested repository |
| [`status`](status.md) | report on the nested repositories of this repository |
| [`submodules`](submodules.md) | turn all submodules into nested repositories |
| [`diff`](diff.md) | show a nested repository's local changes against upstream |
| [`patches`](patches.md) | write, check, drop or cherry-pick the patches of a nested repository |
| [`verify`](verify.md) | check that a nested repository is its upstream commit plus patches or diffs |
Expand Down
1 change: 1 addition & 0 deletions doc/cli/init.md
Original file line number Diff line number Diff line change
Expand Up @@ -91,6 +91,7 @@ git nested init --from-submodule ext/lib
This removes the submodule and clones the same URL at the same commit into
its place. A relative submodule URL is resolved against the `origin` remote
of your repository. See [Upstream submodules](../guides/submodules.md).
To nest all submodules at once, use [`submodules init`](submodules.md).

## Notes

Expand Down
89 changes: 89 additions & 0 deletions doc/cli/submodules.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,89 @@
# `git nested submodules`

Turn all submodules into nested repositories.

```text
git nested submodules init [--recursive] [--resolve-relative <url>] [--only <path> | --ignore <path>]...
```

## What it does

Use it for a repository whose submodules should be plain files. You get one
repository with all the code in it.

The repository itself stays a normal git clone of its upstream. Each
submodule becomes a nested repository.

`init` nests every submodule at the commit it pins. Each submodule gets one
commit. With `--recursive`, it nests their submodules too. With `--only` or
`--ignore`, it nests only some of them.

No gitlink and no `.gitmodules` entry stays for a nested submodule.

## Options

| Option | Meaning |
|---|---|
| `--only <path>` | nest only the submodules at or below this path. The others stay submodules. Give it more than once for more paths |
| `--ignore <path>` | nest all submodules but the ones at or below this path. Give it more than once for more paths. Not with `--only` |
| `--recursive` | nest the submodules of the submodules too, at any depth. Without it, they stay submodules. The choice goes into each `.gitnested` as [`submodules`](../configuration/gitnested-file.md) |
| `--resolve-relative <url>` | resolve relative submodule urls against this url. Without it, `init` stops at a relative url |
| `-S`, `--gpg-sign` | GPG-sign the commits |
| `--signoff` | add a `Signed-off-by:` trailer to the commits |

## Examples

```bash
git clone https://github.com/user/project
cd project
git nested submodules init --recursive
```

### Relative urls

A url like `../lib.git` is relative to the url of the superproject. In a
fork, that is not `origin`. So `init` stops and asks for the url:

```bash
git nested submodules init --resolve-relative https://github.com/org/project
```

Now `../lib.git` is `https://github.com/org/lib.git`. This is only for
the first level. With `--recursive`, a deeper relative url is relative to
the url of its parent submodule, as in git.

### Only some submodules

Name the paths to nest:

```bash
git nested submodules init --only lib/core --only third_party
```

This nests `lib/core` and every submodule below `third_party`. The others
stay submodules.

Or name the ones to keep as submodules:

```bash
git nested submodules init --ignore vendor/big
```

`init` keeps `--only` and `--ignore` in `.gitmodules`, in a `[nested]`
section.

## Notes

- `init` needs a clean working tree.
- If your `.gitattributes` would change files of a nested repository, for
example `*.bat text eol=crlf`, git-nested adds `-text` for these files to
`.gitattributes`. So they stay as upstream has them, as in a submodule.
- Push your changes to each submodule's upstream with
[`push`](push.md), as for any nested repository.

## See also

- [Upstream submodules](../guides/submodules.md)
- [`init --from-submodule`](init.md): nest one submodule.
- [`clone --recurse-submodules`](clone.md): nest a repository with
submodules in a subdirectory.
3 changes: 2 additions & 1 deletion doc/concepts/comparison.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,8 @@ your repository.
With git-nested the files are part of your repository. A plain `git clone`
gets them, and every commit is complete.

To switch, see [`git nested init --from-submodule`](../cli/init.md).
To switch, see [`git nested init --from-submodule`](../cli/init.md) for one
submodule, or [`git nested submodules`](../cli/submodules.md) for all of them.

## git subtree

Expand Down
10 changes: 10 additions & 0 deletions doc/configuration/gitnested-file.md
Original file line number Diff line number Diff line change
Expand Up @@ -194,6 +194,16 @@ A name with no patch file is an error. So when a patch is renumbered or
renamed, fix the list. A patch whose title starts with `git-nested local:`
stays local too, whatever its number.

### `submodules`

What happens to the submodules inside the nested repository:

- `nest`: they become nested repositories too.
- `keep`: they stay submodules.

`submodules init` writes it: `keep`, or `nest` with `--recursive`. Unset
means `nest`.

### `cmdver`

The git-nested version that last wrote the file. For information only.
Expand Down
15 changes: 15 additions & 0 deletions doc/guides/submodules.md
Original file line number Diff line number Diff line change
Expand Up @@ -53,3 +53,18 @@ This:

A relative submodule URL is resolved against the `origin` remote of your
repository.

## Turn a whole repository into one

Your repository has many submodules, maybe submodules in submodules. You
want all of them as plain files:

```bash
git nested submodules init --recursive
```

`init --recursive` nests all of them, at any depth. Without
`--recursive`, it nests only the first level. `--only <path>` nests only
some.

See [`submodules`](../cli/submodules.md).
2 changes: 2 additions & 0 deletions doc/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -74,6 +74,7 @@ The full reference of the command line. There is one page per command.
| [`push`](cli/push.md) | Send your changes upstream |
| [`fetch`](cli/fetch.md) | Download upstream changes, change no file |
| [`status`](cli/status.md) | Show all nested repositories |
| [`submodules`](cli/submodules.md) | Turn all submodules into nested repositories |
| [`diff`](cli/diff.md) | Compare a nested repository with upstream |
| [`patches`](cli/patches.md) | Keep local changes as patch files |
| [`verify`](cli/verify.md) | Check local changes against patch files |
Expand All @@ -100,6 +101,7 @@ cli/pull
cli/push
cli/fetch
cli/status
cli/submodules
cli/diff
cli/patches
cli/verify
Expand Down
3 changes: 3 additions & 0 deletions man/man1/git-nested.1
Original file line number Diff line number Diff line change
Expand Up @@ -99,6 +99,9 @@ run a git command in the worktree of a nested repository
.B status
report on the nested repositories of this repository
.TP
.B submodules
turn all submodules into nested repositories
.TP
.B verify
check that a nested repository is its upstream commit plus patches or diffs
.TP
Expand Down
13 changes: 10 additions & 3 deletions src/git_nested/cli/location.py
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@
# Commands whose missing <subdir> is not filled in from the current directory:
# status reports on all of them, clone guesses one from the upstream, and init
# is what makes a directory nested in the first place.
_NO_IMPLIED_SUBDIR = ('clone', 'completion', 'init', 'status', 'version')
_NO_IMPLIED_SUBDIR = ('clone', 'completion', 'init', 'status', 'submodules', 'version')


def at_top_level(git: GitRunner, command: str, ctx: CommandContext) -> AbstractContextManager[object]:
Expand All @@ -56,11 +56,13 @@ def at_top_level(git: GitRunner, command: str, ctx: CommandContext) -> AbstractC
# relative one keeps working in every clone of the parent repository.
ctx.upstream = _remote_from(prefix, ctx.upstream)
ctx.flags.remote = _remote_from(prefix, ctx.flags.remote)
ctx.flags.resolve_relative = _remote_from(prefix, ctx.flags.resolve_relative)
if ctx.config_key == 'remote':
ctx.config_value = _remote_from(prefix, ctx.config_value)

# --ignore paths are given like <subdir>.
ctx.flags.ignore = [_joined(prefix, Path(path)) for path in ctx.flags.ignore or []]
# --ignore and --only paths are given like <subdir>.
ctx.flags.ignore = _all_joined(prefix, ctx.flags.ignore)
ctx.flags.only = _all_joined(prefix, ctx.flags.only)
if ctx.subdir is not None:
ctx.subdir = _joined(prefix, Path(ctx.subdir))
elif command not in _NO_IMPLIED_SUBDIR and not ctx.flags.all:
Expand Down Expand Up @@ -99,6 +101,11 @@ def _remote_from(prefix: str, remote: str | None) -> str | None:
return joined if joined.startswith('.') else f'./{joined}'


def _all_joined(prefix: str, paths: list[str] | None) -> list[str] | None:
"""Each of `paths` joined like a <subdir>. None stays None."""
return [_joined(prefix, Path(path)) for path in paths] if paths else paths


def _joined(prefix: str, subdir: Path) -> str:
"""`subdir`, typed below the top level at `prefix`, as a path from the top level."""
if subdir.anchor:
Expand Down
4 changes: 4 additions & 0 deletions src/git_nested/cli/parser.py
Original file line number Diff line number Diff line change
Expand Up @@ -70,6 +70,9 @@ def _flags_from_args(args: argparse.Namespace) -> Flags:
filter=getattr(args, 'filter', []),
force=getattr(args, 'force', False),
ignore=getattr(args, 'ignore', None),
only=getattr(args, 'only', None),
resolve_relative=getattr(args, 'resolve_relative', None),
recursive=getattr(args, 'recursive', False),
from_submodule=getattr(args, 'from_submodule', False),
from_patches=getattr(args, 'from_patches', False),
local=getattr(args, 'local', False),
Expand Down Expand Up @@ -210,5 +213,6 @@ def parse_args(git: GitRunner, args_list: list[str]) -> tuple[str, CommandContex
patch_names=getattr(args, 'patch_names', None),
patches=patches,
verify_mode=verify_mode,
submodules_action=getattr(args, 'submodules_action', None),
)
return args.command, context
39 changes: 38 additions & 1 deletion src/git_nested/cli/spec.py
Original file line number Diff line number Diff line change
Expand Up @@ -79,6 +79,7 @@
'update',
],
'status': ['ALL', 'all', 'fetch', 'short'],
'submodules': ['gpg_sign', 'ignore', 'only', 'recursive', 'resolve_relative', 'signoff'],
'verify': ['diffs', 'ignore', 'keep', 'output_dir', 'patches'],
'version': [],
}
Expand All @@ -101,6 +102,7 @@
'repair': "point a nested repository's sync point back into the current history",
'run': "run a git command in the worktree of a nested repository",
'status': "report on the nested repositories of this repository",
'submodules': "turn all submodules into nested repositories",
'verify': "check that a nested repository is its upstream commit plus patches or diffs",
'version': "print version information",
}
Expand Down Expand Up @@ -179,9 +181,28 @@
{
'action': 'append',
'metavar': 'PATH',
'help': "skip this path of <subdir>, just this time",
'help': "skip this path of <subdir>, just this time; submodules init: do not nest the submodules there",
},
),
(
'only',
('--only',),
{
'action': 'append',
'metavar': 'PATH',
'help': "init: nest only the submodules at or below this path; give it more than once for more",
},
),
(
'recursive',
('--recursive',),
{'action': 'store_true', 'help': "init: nest the submodules of the submodules too, at any depth"},
),
(
'resolve_relative',
('--resolve-relative',),
{'metavar': 'URL', 'help': "init: resolve relative submodule urls against this url"},
),
('exclude', ('--exclude',), {'action': 'append', 'help': "leave this path of the upstream repository out"}),
(
'gpg_sign',
Expand Down Expand Up @@ -334,6 +355,7 @@
# everything after <subdir> goes to git untouched, options included.
('git_args', {'nargs': '...', 'help': "the git command to run, with its arguments"}),
],
'submodules': [('submodules_action', {'metavar': 'action', 'choices': ['init'], 'help': "init"})],
'verify': [('subdir', {'help': _SUBDIR_HELP})],
}

Expand Down Expand Up @@ -424,6 +446,15 @@
"Report every nested repository in this repository: where it comes from, and whether it has local changes. "
"With -q, just the paths, one per line."
),
'submodules': (
"Turn the submodules of a repository into plain files. "
"Each submodule becomes a nested repository. "
"The repository itself stays a normal git clone of its upstream. "
"'init' nests all submodules at the commits they pin, one commit each. "
"With --recursive, their submodules too. "
"--only and --ignore pick some of them. "
"A relative submodule url needs --resolve-relative."
),
'verify': (
"Apply the files to the upstream commit in .gitnested, in a temporary worktree, and compare "
"the result with <subdir>. Patches go in with git am; plain diffs need --diffs. "
Expand Down Expand Up @@ -519,6 +550,12 @@
"git nested status",
"git nested status -q",
],
'submodules': [
"git nested submodules init",
"git nested submodules init --recursive",
"git nested submodules init --only lib/core",
"git nested submodules init --resolve-relative https://github.com/org/project",
],
'verify': [
"git nested verify ext/lib --patches patches/lib/*.patch",
"git nested verify -o patches/lib ext/lib",
Expand Down
2 changes: 2 additions & 0 deletions src/git_nested/commands/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,7 @@
repair,
run,
status,
submodules,
verify,
version,
)
Expand All @@ -52,6 +53,7 @@
'repair': repair.cmd_repair,
'run': run.cmd_run,
'status': status.cmd_status,
'submodules': submodules.cmd_submodules,
'verify': verify.cmd_verify,
'version': version.cmd_version,
}
Loading
Loading