Patchwork [1,of,4] commit: try to clarify when to use --new-branch

login
register
mail settings
Submitter timeless@mozdev.org
Date Dec. 7, 2015, 8:23 p.m.
Message ID <4eb33ce681a1ac1df408.1449519827@waste.org>
Download mbox | patch
Permalink /patch/11909/
State Accepted
Headers show

Comments

timeless@mozdev.org - Dec. 7, 2015, 8:23 p.m.
# HG changeset patch
# User timeless <timeless@mozdev.org>
# Date 1448909767 0
#      Mon Nov 30 18:56:07 2015 +0000
# Node ID 4eb33ce681a1ac1df40845145e336c5c39b7497a
# Parent  30a20167ae29e1874163b59a489de0cb1d859565
commit: try to clarify when to use --new-branch
Matt Mackall - Dec. 11, 2015, 8:19 p.m.
On Mon, 2015-12-07 at 14:23 -0600, timeless wrote:
> # HG changeset patch
> # User timeless <timeless@mozdev.org>
> # Date 1448909767 0
> #      Mon Nov 30 18:56:07 2015 +0000
> # Node ID 4eb33ce681a1ac1df40845145e336c5c39b7497a
> # Parent  30a20167ae29e1874163b59a489de0cb1d859565
> commit: try to clarify when to use --new-branch

--new-branch is a flag on push, so this is very confusing

> diff --git a/mercurial/commands.py b/mercurial/commands.py
> --- a/mercurial/commands.py
> +++ b/mercurial/commands.py
> @@ -1568,6 +1568,13 @@
>      head closed. When all heads of a branch are closed, the branch
>      will be considered closed and no longer listed.
>  
> +    .. note::
> +
> +      If you are thinking about closing a branch, but you never shared
> +      it, you should consider making it secret (see :hg:`help phase`) or
> +      obsolete (see :hg:`help obsolete`), or stripping it
> +      (see :hg:`help strip`) instead of merely closing it.

The first piece of advice is ok, I guess. But if you don't understand
named branches.. dumping phases onto the pile is probably asking a lot
of a user. I might suggest a simpler, less assertive "see also:
phases".

The second can't be used without an experimental out-of-tree
extensions. Definitely not advice we want in core help.

The third piece refers to a destructive extension. Also probably not good advice for core commands.

-- 
Mathematics is the supreme nostalgia of our time.
timeless - Dec. 29, 2015, 12:13 a.m.
Matt Mackall wrote:
> On Mon, 2015-12-07 at 14:23 -0600, timeless wrote:
>> commit: try to clarify when to use --new-branch
>
> --new-branch is a flag on push, so this is very confusing

oops, I meant --close-branch :)

>> +      If you are thinking about closing a branch, but you never shared
>> +      it, you should consider making it secret (see :hg:`help phase`) or
>> +      obsolete (see :hg:`help obsolete`), or stripping it
>> +      (see :hg:`help strip`) instead of merely closing it.
>
> The first piece of advice is ok, I guess. But if you don't understand
> named branches.. dumping phases onto the pile is probably asking a lot
> of a user. I might suggest a simpler, less assertive "see also:
> phases".

I sent a revised version.

> The second can't be used without an experimental out-of-tree
> extensions. Definitely not advice we want in core help.

At some point I need to look into help-hooks...

> The third piece refers to a destructive extension. Also probably not good advice for core commands.

Patch

diff --git a/mercurial/commands.py b/mercurial/commands.py
--- a/mercurial/commands.py
+++ b/mercurial/commands.py
@@ -1568,6 +1568,13 @@ 
     head closed. When all heads of a branch are closed, the branch
     will be considered closed and no longer listed.
 
+    .. note::
+
+      If you are thinking about closing a branch, but you never shared
+      it, you should consider making it secret (see :hg:`help phase`) or
+      obsolete (see :hg:`help obsolete`), or stripping it
+      (see :hg:`help strip`) instead of merely closing it.
+
     The --amend flag can be used to amend the parent of the
     working directory with a new commit that contains the changes
     in the parent in addition to those currently reported by :hg:`status`,