| Message ID | d38e5a18-4d85-48f3-bc8b-8ca02ea683a4@gmail.com (mailing list archive) |
|---|---|
| State | Accepted |
| Commit | 5aea3955bcd716c5dcb3323ef4eab72da70db623 |
| Headers | show |
| Series | branch: clarify <oldbranch> term | expand |
Rubén Justo <rjusto@gmail.com> writes: > Since 52d59cc645 (branch: add a --copy (-c) option to go with --move > (-m), 2017-06-18) <oldbranch> is used in more operations than just -m. > > Let's also clarify what we do if <oldbranch> is omitted. > > Signed-off-by: Rubén Justo <rjusto@gmail.com> > --- > Documentation/git-branch.txt | 3 ++- > 1 file changed, 2 insertions(+), 1 deletion(-) > > diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt > index 4395aa9354..233264549c 100644 > --- a/Documentation/git-branch.txt > +++ b/Documentation/git-branch.txt > @@ -312,7 +312,8 @@ superproject's "origin/main", but tracks the submodule's "origin/main". > option is omitted, the current HEAD will be used instead. > > <oldbranch>:: > - The name of an existing branch to rename. > + The name of an existing branch. If this option is omitted, > + the name of the current branch will be used instead. Thanks. Will queue this patch as is for now, but I suspect that in the longer term it will help readers a lot to revamp the whole page. The description for the "branch rename" operation, for example, is split and partly repreated in three places, i.e. * a paragraph in the DESCRIPTION that talks about <oldbranch>, where readers will be helped by the same clarification as this patch gives; * -m/-M option description which is very sketchy and does not even hint that they take <oldbranch> and <newbranch>; and * <oldbranch> description as a separate bullet item in the same list, which does not even hint that this is used by -m/-M. which is unmanageable from writers' point of view, and hard to follow from readers' point of view. Such a rewrite may look like this: * Trim down the DESCRIPTION explanation to enumerate "features" offered, with pointers into the OPTIONS section using the option names as hints, e.g., The command offers many features that work on branches, depending on the options. - The default mode of operation is to list (the --list option explicitly calls for it, or the lack of other options to trigger different mode). - ... - An existing branch can be renamed to a different name with "-m/-M" options. - ... * Enhance the description in the OPTIONS section so that each bullet item (e.g., "-m") gives everything the user wants to know about that option, e.g., -m [<oldbranch>] <newbranch>:: -M [<oldbranch>] <newbranch>:: Rename <oldbranch> (defaults to the current branch) to <newbranch>. If <newbranch> already exists, `-m` will error out and renaming must be forced by using `-M` (in other words, `-M` works as a short-hand for `-m --force`). + The contents reflog of the <oldbranch> will also be renamed to become the reflog of the <newbranch>, and a reflog entry is added for the renaming of the branch. * Remove the non-option entries from the OPTIONS bullet list.
diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt index 4395aa9354..233264549c 100644 --- a/Documentation/git-branch.txt +++ b/Documentation/git-branch.txt @@ -312,7 +312,8 @@ superproject's "origin/main", but tracks the submodule's "origin/main". option is omitted, the current HEAD will be used instead. <oldbranch>:: - The name of an existing branch to rename. + The name of an existing branch. If this option is omitted, + the name of the current branch will be used instead. <newbranch>:: The new name for an existing branch. The same restrictions as for
Since 52d59cc645 (branch: add a --copy (-c) option to go with --move (-m), 2017-06-18) <oldbranch> is used in more operations than just -m. Let's also clarify what we do if <oldbranch> is omitted. Signed-off-by: Rubén Justo <rjusto@gmail.com> --- Documentation/git-branch.txt | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-)