[PATCH] Mention that git-branch -M can cause problems for tracking branches

[PATCH] Mention that git-branch -M can cause problems for tracking branches

[Jonas Fonseca]

Signed-off-by: Jonas Fonseca <fonseca@diku.dk>
---
 Documentation/git-branch.txt |    5 +++++
 1 files changed, 5 insertions(+), 0 deletions(-)

 I made a patch to discard the overwritten branch's configuration
 section, which Spearce felt was too lossy a behaviour. However, since
 it confused me, I think it should at least be mentioned in the manpage.
 Maybe the warning message from git should also be added to improve its
 "googlability".

diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt
index 5e81aa4..def4e85 100644
--- a/Documentation/git-branch.txt
+++ b/Documentation/git-branch.txt
@@ -165,6 +165,11 @@ If you are creating a branch that you want to immediately checkout, it's
 easier to use the git checkout command with its `-b` option to create
 a branch and check it out with a single command.
 
+When a branch is renamed so that it overwrites an existing branch unintended
+problems can arise. This is because git refuses to discard the configuration
+section of the overwritten branch. As a result git can become confused if, for
+example, the branches involved were used for tracking two different remote
+branches. The only way to fix this is to edit the configuration file manually.
 
 Author
 ------
-- 
1.5.3.4.1481.g854da-dirty

-- 
Jonas Fonseca

Re: [PATCH] Mention that git-branch -M can cause problems for tracking branches

[Junio C Hamano]

Jonas Fonseca <fonseca@diku.dk> writes:

> Signed-off-by: Jonas Fonseca <fonseca@diku.dk>
> ---
>  Documentation/git-branch.txt |    5 +++++
>  1 files changed, 5 insertions(+), 0 deletions(-)
>
>  I made a patch to discard the overwritten branch's configuration
>  section, which Spearce felt was too lossy a behaviour. However, since
>  it confused me, I think it should at least be mentioned in the manpage.
>  Maybe the warning message from git should also be added to improve its
>  "googlability".
>
> diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt
> index 5e81aa4..def4e85 100644
> --- a/Documentation/git-branch.txt
> +++ b/Documentation/git-branch.txt
> @@ -165,6 +165,11 @@ If you are creating a branch that you want to immediately checkout, it's
>  easier to use the git checkout command with its `-b` option to create
>  a branch and check it out with a single command.
>  
> +When a branch is renamed so that it overwrites an existing branch unintended
> +problems can arise. This is because git refuses to discard the configuration
> +section of the overwritten branch. As a result git can become confused if, for
> +example, the branches involved were used for tracking two different remote
> +branches. The only way to fix this is to edit the configuration file manually.

I do not understand this bit about "refuse".

 - To "refuse to discard", somebody has to ask to discard ---
   who asks so and when?

 - Is there a reason to "refuse" when such a removal request is
   made?  If so, what is it?  If not, why refusal?

Re: [PATCH] Mention that git-branch -M can cause problems for tracking branches

[Jonas Fonseca]

Junio C Hamano <gitster@pobox.com> wrote Fri, Nov 02, 2007:
> Jonas Fonseca <fonseca@diku.dk> writes:
> 
> > Signed-off-by: Jonas Fonseca <fonseca@diku.dk>
> > ---
> >  Documentation/git-branch.txt |    5 +++++
> >  1 files changed, 5 insertions(+), 0 deletions(-)
> >
> >  I made a patch to discard the overwritten branch's configuration
> >  section, which Spearce felt was too lossy a behaviour. However, since
> >  it confused me, I think it should at least be mentioned in the manpage.
> >  Maybe the warning message from git should also be added to improve its
> >  "googlability".
> >
> > diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt
> > index 5e81aa4..def4e85 100644
> > --- a/Documentation/git-branch.txt
> > +++ b/Documentation/git-branch.txt
> > @@ -165,6 +165,11 @@ If you are creating a branch that you want to immediately checkout, it's
> >  easier to use the git checkout command with its `-b` option to create
> >  a branch and check it out with a single command.
> >  
> > +When a branch is renamed so that it overwrites an existing branch unintended
> > +problems can arise. This is because git refuses to discard the configuration
> > +section of the overwritten branch. As a result git can become confused if, for
> > +example, the branches involved were used for tracking two different remote
> > +branches. The only way to fix this is to edit the configuration file manually.
> 
> I do not understand this bit about "refuse".
> 
>  - To "refuse to discard", somebody has to ask to discard ---
>    who asks so and when?

IMO, the user asks when using git-branch -M. And in case it is not clear
the problem arises for the command sequence:

	$ git branch --track o-next origin/next
	$ git branch --track m-next madcoder/next
	$ git branch -M o-next m-next
	$ git remote
	Warning: more than one branch.m-next.remote
	...

>  - Is there a reason to "refuse" when such a removal request is
>    made?  If so, what is it?  If not, why refusal?

Personally, I don't see why we need to refuse, since git-branch -M is
somewhat similar to saying -m (rename) plus adding a "force" flag
meaning: "yes, I know that this will potentially throw away settings for
an already existing branch".

The main reason to "refuse" the removal is that for the general case,
e.g. when using `git-config --rename-section`, this can potentially lead
to loss of valuable config settings. This was pointed out by Shawn in
his reply to my patch[0]. I agreed to this in my follow-up and asked if
it would be acceptable to add an additional flag to so that git-branch
can switch on this request for removal.

[0] http://thread.gmane.org/gmane.comp.version-control.git/61291

-- 
Jonas Fonseca

Re: [PATCH] Mention that git-branch -M can cause problems for tracking branches

[Junio C Hamano]

Jonas Fonseca <fonseca@diku.dk> writes:

> The main reason to "refuse" the removal is that for the general case,
> e.g. when using `git-config --rename-section`, this can potentially lead
> to loss of valuable config settings. This was pointed out by Shawn in
> his reply to my patch[0]. I agreed to this in my follow-up and asked if
> it would be acceptable to add an additional flag to so that git-branch
> can switch on this request for removal.

So when you rename branch.foo section to branch.bar, instead of
replacing the whole existing branch.bar with what used to be in
branch.foo, you _append_ that to branch.bar?

That sounds insane.

What good does it do to keep what used to be branch.bar?  The
old contents in the section are by no means "valuable".  They
were about 'bar' and do not even have anything to do with the
branch being renamed, which used to be called 'foo'.

Shawn's example of modifying multi-valued variable is
irrelevant.  Over there, we have options to replace everything
or append to it, don't we?

If the option is --rename-section, that is "rename section", not
"merge section".  If for some reason a merge section operation
is needed, that should be supplied in a separate patch, but for
the branch renaming I really do not see the need for it.