path: root/contrib/subtree/
diff options
authorLuke Shumaker <>2021-04-27 21:17:44 (GMT)
committerJunio C Hamano <>2021-04-28 07:47:19 (GMT)
commit6468784dd2ca3ea2408f9915ab9b7ce136f0b024 (patch)
treea5e8b1f401990b54862b7bda00d3d35bdd027387 /contrib/subtree/
parente9525a8a0291eb5ef0a81473d2b8c4d4b3b198c8 (diff)
subtree: give the docs a once-over
Just went through the docs looking for anything inaccurate or that can be improved. In the '-h' text, in the man page synopsis, and in the man page description: Normalize the ordering of the list of sub-commands: 'add', 'merge', 'split', 'pull', 'push'. This allows us to kinda separate the lower-level add/merge/split from the higher-level pull/push. '-h' text: - correction: Indicate that split's arg is optional. - clarity: Emphasize that 'pull' takes the 'add'/'merge' flags. man page: - correction: State that all subcommands take options (it seemed to indicate that only 'split' takes any options other than '-P'). - correction: 'split' only guarantees that the results are identical if the flags are identical. - correction: The flag is named '--ignore-joins', not '--ignore-join'. - completeness: Clarify that 'push' always operates on HEAD, and that 'split' operates on HEAD if no local commit is given. - clarity: In the description, when listing commands, repeat what their arguments are. This way the reader doesn't need to flip back and forth between the command description and the synopsis and the full description to understand what's being said. - clarity: In the <variables> used to give command arguments, give slightly longer, descriptive names. Like <local-commit> instead of just <commit>. - clarity: Emphasize that 'pull' takes the 'add'/'merge' flags. - style: In the synopsis, list options before the subcommand. This makes things line up and be much more readable when shown non-monospace (such as in `make html`), and also more closely matches other man pages (like `git-submodule.txt`). - style: Use the correct syntax for indicating the options ([<options>] instead of [OPTIONS]). - style: In the synopsis, separate 'pull' and 'push' from the other lower-level commands. I think this helps readability. - style: Code-quote things in prose that seem like they should be code-quoted, like '.gitmodules', flags, or full commands. - style: Minor wording improvements, like more consistent mood (many of the command descriptions start in the imperative mood and switch to the indicative mode by the end). That sort of thing. - style: Capitalize "ID". - style: Remove the "This option is only valid for XXX command" remarks from each option, and instead rely on the section headings. - style: Since that line is getting edited anyway, switch "behaviour" to American "behavior". - style: Trim trailing whitespace. `todo`: - style: Trim trailing whitespace. Signed-off-by: Luke Shumaker <> Signed-off-by: Junio C Hamano <>
Diffstat (limited to 'contrib/subtree/')
1 files changed, 2 insertions, 2 deletions
diff --git a/contrib/subtree/ b/contrib/subtree/
index 768fa7b..3bffddf 100755
--- a/contrib/subtree/
+++ b/contrib/subtree/
@@ -25,9 +25,9 @@ OPTS_SPEC="\
git subtree add --prefix=<prefix> <commit>
git subtree add --prefix=<prefix> <repository> <ref>
git subtree merge --prefix=<prefix> <commit>
+git subtree split --prefix=<prefix> [<commit>]
git subtree pull --prefix=<prefix> <repository> <ref>
git subtree push --prefix=<prefix> <repository> <ref>
-git subtree split --prefix=<prefix> <commit>
h,help show the help
q quiet
@@ -40,7 +40,7 @@ b,branch= create a new branch from the split subtree
ignore-joins ignore prior --rejoin commits
onto= try connecting new tree to an existing one
rejoin merge the new branch back into HEAD
- options for 'add', 'merge', and 'pull'
+ options for 'add' and 'merge' (also: 'pull')
squash merge subtree changes as a single commit