From 6468784dd2ca3ea2408f9915ab9b7ce136f0b024 Mon Sep 17 00:00:00 2001 From: Luke Shumaker Date: Tue, 27 Apr 2021 15:17:44 -0600 Subject: 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 used to give command arguments, give slightly longer, descriptive names. Like instead of just . - 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 ([] 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 --- contrib/subtree/git-subtree.sh | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'contrib/subtree/git-subtree.sh') diff --git a/contrib/subtree/git-subtree.sh b/contrib/subtree/git-subtree.sh index 768fa7b6b6..3bffddf277 100755 --- a/contrib/subtree/git-subtree.sh +++ b/contrib/subtree/git-subtree.sh @@ -25,9 +25,9 @@ OPTS_SPEC="\ git subtree add --prefix= git subtree add --prefix= git subtree merge --prefix= +git subtree split --prefix= [] git subtree pull --prefix= git subtree push --prefix= -git subtree split --prefix= -- 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 " -- cgit v1.3-6-g1900