[PATCH 4/5] git-son: add documentation

From

EGEvan Haque via GitGitGadget <gitgitgadget@gmail.com>

Date

May 26, 2026, 16:47 UTC

Message-ID

<652381886f8cf839d533b9322c1c5e5983f3ffe4.1779814052.git.gitgitgadget@gmail.com>

In-Reply-To

<pull.2122.git.1779814052.gitgitgadget@gmail.com>

From: Evan Haque <evanhaque1@gmail.com>

Assisted-by: Claude Opus 4.6
Signed-off-by: Evan Haque <evanhaque1@gmail.com>
---
 Documentation/git-son.adoc | 64 ++++++++++++++++++++++++++++++++++++++
 Documentation/meson.build  |  1 +
 2 files changed, 65 insertions(+)
 create mode 100644 Documentation/git-son.adoc

diff --git a/Documentation/git-son.adoc b/Documentation/git-son.adoc
new file mode 100644
index 0000000000..17ec992bfd
--- /dev/null
+++ b/Documentation/git-son.adoc
@@ -0,0 +1,64 @@
+git-son(1)
+==========
+
+NAME
+----
+git-son - Create an independent child repository that knows its parent
+
+SYNOPSIS
+--------
+[verse]
+'git son' [--inherit] [--branch <branch>] <name>
+
+DESCRIPTION
+-----------
+
+Create a new independent Git repository inside the current working
+tree as a subdirectory named `<name>`. Unlike a submodule, the child
+repository is not tracked by the parent; instead, `<name>/` is added
+to the parent's `.gitignore`.
+
+The child repository is configured with a remote called `parent`
+pointing back to the parent repository's origin URL (or local path
+if no origin is set), allowing the child to fetch from the parent
+at any time.
+
+OPTIONS
+-------
+--inherit::
+	Fetch the parent's history into the child repository at
+	creation time. Without this flag, the child starts with a
+	single initial commit.
+
+--branch <branch>::
+	When used with `--inherit`, check out the given branch from
+	the parent instead of the default branch. This option
+	requires `--inherit`.
+
+<name>::
+	The name of the subdirectory (and child repository) to create.
+	Must not already exist.
+
+EXAMPLES
+--------
+
+Create a simple child repository:
+
+	git son my-tool
+
+Create a child that inherits the parent's history:
+
+	git son --inherit my-fork
+
+Create a child starting from a specific parent branch:
+
+	git son --inherit --branch feature my-experiment
+
+Later, from within the child, fetch updates from the parent:
+
+	cd my-tool
+	git fetch parent
+
+GIT
+---
+Part of the linkgit:git[1] suite
diff --git a/Documentation/meson.build b/Documentation/meson.build
index f4854f802d..1ae7e5f644 100644
--- a/Documentation/meson.build
+++ b/Documentation/meson.build
@@ -139,6 +139,7 @@ manpages = {
   'git-show-ref.adoc' : 1,
   'git-show.adoc' : 1,
   'git-sh-setup.adoc' : 1,
+  'git-son.adoc' : 1,
   'git-sparse-checkout.adoc' : 1,
   'git-stage.adoc' : 1,
   'git-stash.adoc' : 1,

-- 
gitgitgadget