[PATCH/RFC] branch: warn user about non-existent branch

[PATCH/RFC] branch: warn user about non-existent branch

[Kaartic Sivaraam]

The inexistence of the branch trying to be renamed wasn't checked
and was left for 'rename_ref' to point out. It's better to do it
explicitly as it leads to unconventional behaviour in the following
case,

        $ git branch -m foo master
        fatal: A branch named 'master' already exists.

It's conventional to report that the 'foo' doesn't exist rather than
repoting that 'master' exists, the same way the 'mv' command does.

        $ mv foo existing_file
        mv: cannot stat 'foo': No such file or directory

Further, there's no way for 'master' being overwritten with 'foo',
as it doesn't exist. Reporting the existence of 'master' is germane
only when 'master' is *really* going to be overwritten.

So, report the inexistence of the branch explicitly  before reporting
existence of new branch name to be consistent with it's counterpart,
the widely used, the 'mv' command.

Signed-off-by: Kaartic Sivaraam <kaarticsivaraam91196@gmail.com>
---
 I'm sending this patch as I didn't want to leave this thread
 open ended. I'm not yet sure if this is a good thing to do.
 This patch is open to comments, as the prvious ones I've sent
 have been.

 builtin/branch.c | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/builtin/branch.c b/builtin/branch.c
index a3bd2262b..0a9112335 100644
--- a/builtin/branch.c
+++ b/builtin/branch.c
@@ -473,6 +473,10 @@ static void rename_branch(const char *oldname, const char *newname, int force)
 			die(_("Invalid branch name: '%s'"), oldname);
 	}
 
+	/* Check for existence of oldref before proceeding */
+	if(!ref_exists(oldref.buf))
+		die(_("Branch '%s' does not exist."), oldname);
+
 	/*
 	 * A command like "git branch -M currentbranch currentbranch" cannot
 	 * cause the worktree to become inconsistent with HEAD, so allow it.
-- 
2.13.2.23.g14d9f4c6d

Change in output as a result of patch

[Kaartic Sivaraam]

The patch in the previous mail results in a change in output as
specified below.

    $ git branch
    * master
      foo
      bar

Before patch,

    $ git branch -m hypothet master
    fatal: A branch named 'master' already exists.

    $ git branch -m hypothet real
    error: refname refs/heads/hypothet not found
    fatal: Branch rename failed

After patch,

    $ git branch -m hypothet master
    fatal: Branch 'hypothet' does not exist.

    $ git branch -m hypothet real
    fatal: Branch 'hypothet' does not exist.

-- 
Kaartic

Re: Change in output as a result of patch

[Junio C Hamano]

Kaartic Sivaraam <kaarticsivaraam91196@gmail.com> writes:

> The patch in the previous mail results in a change in output as
> specified below.
>
>     $ git branch
>     * master
>       foo
>       bar
>
> Before patch,
>
>     $ git branch -m hypothet master
>     fatal: A branch named 'master' already exists.
>
>     $ git branch -m hypothet real
>     error: refname refs/heads/hypothet not found
>     fatal: Branch rename failed
>
> After patch,
>
>     $ git branch -m hypothet master
>     fatal: Branch 'hypothet' does not exist.
>
>     $ git branch -m hypothet real
>     fatal: Branch 'hypothet' does not exist.

Imagine this scenario instead, which I think is more realistic
example of making a typo.  The set of existing branches are like
this:

     $ git branch
       devel
     * test

And then you get these with your patch:

     $ git branch -m tets devel
     fatal: Branch 'tets' does not exist.

     $ git branch -m test devel
     fatal: A branch named 'devel' already exists.

My reaction to the above exchange would be a moderately strong
annoyance.  If I were told that I am using 'devel' for something
else already, my "corrected" attempt to turn the 'test' branch to a
real development branch after getting the first error would have
been:

     $ git branch -m test devel2

and I didn't have to get the second error.

I think your patch points in the right direction---if an operation
can fail due to two reasons, reordering the two checks and still
fail with a report for just the first one you happened to check
first does not give us a real improvement.  If it is easy to check
the other one after you noticed one of the condition is violated,
then you could give a more useful diagnosis, namely, "There is
branch 'tets' to rename, and there already is 'devel' branch".

I suspect that with a moderately-sized refactoring around
validate_new_branchname() function, this should be doable.  Instead
of passing two "int" parameters force and attr_only, make them into
a single "unsigned flag" and allow the caller to pass another option
to tell the function "do not die, do not issue a message, but tell
the caller what is wrong with a return value".  And by using that
updated API, rename_branch() could tell four cases apart and fail
the three bad cases in a more sensible way.

In any case, the illustrations of interaction before and after the
change is a very good thing to have when discussing a patch, and you
are encouraged to put them in your proposed log message.

Re: Change in output as a result of patch

[Kaartic Sivaraam]

Let me see if I got everything correctly. Correct me if any of the
below observations are wrong.

On Mon, 2017-07-24 at 14:25 -0700, Junio C Hamano wrote:
> Imagine this scenario instead, which I think is more realistic
> example of making a typo.  The set of existing branches are like
> this:
> 
>      $ git branch
>        devel
>      * test
> 
> And then you get these with your patch:
> 
>      $ git branch -m tets devel
>      fatal: Branch 'tets' does not exist.
> 
>      $ git branch -m test devel
>      fatal: A branch named 'devel' already exists.
> 
> My reaction to the above exchange would be a moderately strong
> annoyance.  If I were told that I am using 'devel' for something
> else already, my "corrected" attempt to turn the 'test' branch to a
> real development branch after getting the first error would have
> been:
> 
>      $ git branch -m test devel2
> 
> and I didn't have to get the second error.
> 
> I think your patch points in the right direction---if an operation
> can fail due to two reasons, reordering the two checks and still
> fail with a report for just the first one you happened to check
> first does not give us a real improvement.  If it is easy to check
> the other one after you noticed one of the condition is violated,
> then you could give a more useful diagnosis, namely, "There is
> branch 'tets' to rename, and there already is 'devel' branch".
> 
So what's expected is an error message that details all possible errors
found in a command in a single message. Now that would be better than
what 'mv' does.

> I suspect that with a moderately-sized refactoring around
> validate_new_branchname() function, this should be doable.  Instead
> of passing two "int" parameters force and attr_only, make them into
> a single "unsigned flag" and allow the caller to pass another option
> to tell the function "do not die, do not issue a message, but tell
> the caller what is wrong with a return value".  And by using that
> updated API, rename_branch() could tell four cases apart and fail
> the three bad cases in a more sensible way.
> 
Ok, now that seems to require little work. I'll see what I could come
up with.

Before I get into this I noticed that "--set-upstream" has been
deprecated since,

b347d06bf09 (branch: deprecate --set-upstream and show help if we detect possible mistaken use,
             Thu Aug 30 19:23:13 2012)

Is there any possibility for it to be removed some time in the near
future?

I'm asking this because IIRC, the 'attr_only' parameter of
"validate_new_branchname" was introduced to fix a regression
(fa7993767560) caused by the "--set-upstream" option. In case it has
been planned to be removed some time soon, it could make the word
easier (?), not sure though.

> In any case, the illustrations of interaction before and after the
> change is a very good thing to have when discussing a patch,
I would like to credit that to "Ævar Arnfjörð Bjarmason", who suggested
that to me in one of the other threads.

-- 
Kaartic

Re: Change in output as a result of patch

[Junio C Hamano]

Kaartic Sivaraam <kaarticsivaraam91196@gmail.com> writes:

> b347d06bf09 (branch: deprecate --set-upstream and show help if we detect possible mistaken use,
>              Thu Aug 30 19:23:13 2012)
>
> Is there any possibility for it to be removed some time in the near
> future?
>
> I'm asking this because IIRC, the 'attr_only' parameter of
> "validate_new_branchname" was introduced to fix a regression
> (fa7993767560) caused by the "--set-upstream" option. In case it has
> been planned to be removed some time soon, it could make the word
> easier (?), not sure though.

I suspect that it would not make the refactoring that much less
work, but you are right---it is about time we started looking into
removing the --set-upstream optin whose 5th anniversary after
deprecation is only one month away.

Can the '--set-upstream' option of branch be removed ?

[Kaartic Sivaraam]

I refactored builtin/branch.c to remove the '--set-upstream'
option,successfully. The corresponding patch follows. 

There's just one issue with the version of git that doesn't
have the '--set-upstream' option. It's described in the commit
log message of the following patch.

I guess it would be difficult to detect the removal of the option in
case it's used in scripts and might cause confusion to users?
Is it ok to proceed with the removal?

BTW, It's now clear  to me that removing '--set-upstream' has nothing
to do with merging the two parameter of 'validate_new_branchname'.

-- 
Kaartic

[PATCH 1/2 / RFC] builtin/branch: remove the deprecated '--set-upstream' option

[Kaartic Sivaraam]

The '--set-upstream' option of branch was deprecated in,

    b347d06bf branch: deprecate --set-upstream and show help if we detect
    possible mistaken use (Thu, 30 Aug 2012 19:23:13 +0200)

It was deprecated for the reasons specified in the commit message of
the referenced commit.

Refactor 'branch' so that it doesn't accept '--set-upstream'.

Note that, 'git branch' still *accepts* '--set-upstream' as a consequence
of "unique prefix can be abbrievated in option names". '--set-upstream'
is a unique prefix of '--set-upstream-to' after '--set-upstream' has
been removed.

The before/after behaviour for a simple case follows,

    $ git remote
    origin

Before,

    $ git branch
    * master

    $ git branch --set-upstream origin/master
    The --set-upstream flag is deprecated and will be removed. Consider using --track or --set-upstream-to
    Branch origin/master set up to track local branch master.

    $ git branch
    * master
      origin/master

After,

    $ git branch
    * master

    $ git branch --set-upstream origin/master
    Branch master set up to track remote branch master from origin.

    $ git branch
    * master

Note that the option used in the after sequence is still '--set-upstream'
though the behaviour is that of '--set-upstream-to'.

Signed-off-by: Kaartic Sivaraam <kaarticsivaraam91196@gmail.com>
---
 Documentation/git-branch.txt | 10 ++-------
 builtin/branch.c             | 24 ---------------------
 t/t3200-branch.sh            | 50 ++------------------------------------------
 3 files changed, 4 insertions(+), 80 deletions(-)

diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt
index 81bd0a7b7..23c47b850 100644
--- a/Documentation/git-branch.txt
+++ b/Documentation/git-branch.txt
@@ -14,7 +14,7 @@ SYNOPSIS
 	[(--merged | --no-merged) [<commit>]]
 	[--contains [<commit]] [--no-contains [<commit>]]
 	[--points-at <object>] [--format=<format>] [<pattern>...]
-'git branch' [--set-upstream | --track | --no-track] [-l] [-f] <branchname> [<start-point>]
+'git branch' [--track | --no-track] [-l] [-f] <branchname> [<start-point>]
 'git branch' (--set-upstream-to=<upstream> | -u <upstream>) [<branchname>]
 'git branch' --unset-upstream [<branchname>]
 'git branch' (-m | -M) [<oldbranch>] <newbranch>
@@ -81,7 +81,7 @@ OPTIONS
 --delete::
 	Delete a branch. The branch must be fully merged in its
 	upstream branch, or in `HEAD` if no upstream was set with
-	`--track` or `--set-upstream`.
+	`--track` or `--set-upstream-to`.
 
 -D::
 	Shortcut for `--delete --force`.
@@ -194,12 +194,6 @@ start-point is either a local or remote-tracking branch.
 	Do not set up "upstream" configuration, even if the
 	branch.autoSetupMerge configuration variable is true.
 
---set-upstream::
-	If specified branch does not exist yet or if `--force` has been
-	given, acts exactly like `--track`. Otherwise sets up configuration
-	like `--track` would when creating the branch, except that where
-	branch points to is not changed.
-
 -u <upstream>::
 --set-upstream-to=<upstream>::
 	Set up <branchname>'s tracking information so <upstream> is
diff --git a/builtin/branch.c b/builtin/branch.c
index a3bd2262b..a70fa8bc6 100644
--- a/builtin/branch.c
+++ b/builtin/branch.c
@@ -557,8 +557,6 @@ int cmd_branch(int argc, const char **argv, const char *prefix)
 		OPT__QUIET(&quiet, N_("suppress informational messages")),
 		OPT_SET_INT('t', "track",  &track, N_("set up tracking mode (see git-pull(1))"),
 			BRANCH_TRACK_EXPLICIT),
-		OPT_SET_INT( 0, "set-upstream",  &track, N_("change upstream info"),
-			BRANCH_TRACK_OVERRIDE),
 		OPT_STRING('u', "set-upstream-to", &new_upstream, N_("upstream"), N_("change the upstream info")),
 		OPT_BOOL(0, "unset-upstream", &unset_upstream, N_("Unset the upstream info")),
 		OPT__COLOR(&branch_use_color, N_("use colored output")),
@@ -755,8 +753,6 @@ int cmd_branch(int argc, const char **argv, const char *prefix)
 		strbuf_release(&buf);
 	} else if (argc > 0 && argc <= 2) {
 		struct branch *branch = branch_get(argv[0]);
-		int branch_existed = 0, remote_tracking = 0;
-		struct strbuf buf = STRBUF_INIT;
 
 		if (!strcmp(argv[0], "HEAD"))
 			die(_("it does not make sense to create 'HEAD' manually"));
@@ -767,29 +763,9 @@ int cmd_branch(int argc, const char **argv, const char *prefix)
 		if (filter.kind != FILTER_REFS_BRANCHES)
 			die(_("-a and -r options to 'git branch' do not make sense with a branch name"));
 
-		if (track == BRANCH_TRACK_OVERRIDE)
-			fprintf(stderr, _("The --set-upstream flag is deprecated and will be removed. Consider using --track or --set-upstream-to\n"));
-
-		strbuf_addf(&buf, "refs/remotes/%s", branch->name);
-		remote_tracking = ref_exists(buf.buf);
-		strbuf_release(&buf);
-
-		branch_existed = ref_exists(branch->refname);
 		create_branch(argv[0], (argc == 2) ? argv[1] : head,
 			      force, reflog, 0, quiet, track);
 
-		/*
-		 * We only show the instructions if the user gave us
-		 * one branch which doesn't exist locally, but is the
-		 * name of a remote-tracking branch.
-		 */
-		if (argc == 1 && track == BRANCH_TRACK_OVERRIDE &&
-		    !branch_existed && remote_tracking) {
-			fprintf(stderr, _("\nIf you wanted to make '%s' track '%s', do this:\n\n"), head, branch->name);
-			fprintf(stderr, "    git branch -d %s\n", branch->name);
-			fprintf(stderr, "    git branch --set-upstream-to %s\n", branch->name);
-		}
-
 	} else
 		usage_with_options(builtin_branch_usage, options);
 
diff --git a/t/t3200-branch.sh b/t/t3200-branch.sh
index dd37ac47c..3ae87c238 100755
--- a/t/t3200-branch.sh
+++ b/t/t3200-branch.sh
@@ -561,7 +561,8 @@ test_expect_success 'use --set-upstream-to modify a particular branch' '
 	git branch my13 &&
 	git branch --set-upstream-to master my13 &&
 	test "$(git config branch.my13.remote)" = "." &&
-	test "$(git config branch.my13.merge)" = "refs/heads/master"
+	test "$(git config branch.my13.merge)" = "refs/heads/master" &&
+	git branch --unset-upstream my13
 '
 
 test_expect_success '--unset-upstream should fail if given a non-existent branch' '
@@ -605,40 +606,6 @@ test_expect_success 'test --unset-upstream on a particular branch' '
 	test_must_fail git config branch.my14.merge
 '
 
-test_expect_success '--set-upstream shows message when creating a new branch that exists as remote-tracking' '
-	git update-ref refs/remotes/origin/master HEAD &&
-	git branch --set-upstream origin/master 2>actual &&
-	test_when_finished git update-ref -d refs/remotes/origin/master &&
-	test_when_finished git branch -d origin/master &&
-	cat >expected <<EOF &&
-The --set-upstream flag is deprecated and will be removed. Consider using --track or --set-upstream-to
-
-If you wanted to make '"'master'"' track '"'origin/master'"', do this:
-
-    git branch -d origin/master
-    git branch --set-upstream-to origin/master
-EOF
-	test_i18ncmp expected actual
-'
-
-test_expect_success '--set-upstream with two args only shows the deprecation message' '
-	git branch --set-upstream master my13 2>actual &&
-	test_when_finished git branch --unset-upstream master &&
-	cat >expected <<EOF &&
-The --set-upstream flag is deprecated and will be removed. Consider using --track or --set-upstream-to
-EOF
-	test_i18ncmp expected actual
-'
-
-test_expect_success '--set-upstream with one arg only shows the deprecation message if the branch existed' '
-	git branch --set-upstream my13 2>actual &&
-	test_when_finished git branch --unset-upstream my13 &&
-	cat >expected <<EOF &&
-The --set-upstream flag is deprecated and will be removed. Consider using --track or --set-upstream-to
-EOF
-	test_i18ncmp expected actual
-'
-
 test_expect_success '--set-upstream-to notices an error to set branch as own upstream' '
 	git branch --set-upstream-to refs/heads/my13 my13 2>actual &&
 	cat >expected <<-\EOF &&
@@ -961,19 +928,6 @@ test_expect_success 'attempt to delete a branch merged to its base' '
 	test_must_fail git branch -d my10
 '
 
-test_expect_success 'use set-upstream on the current branch' '
-	git checkout master &&
-	git --bare init myupstream.git &&
-	git push myupstream.git master:refs/heads/frotz &&
-	git remote add origin myupstream.git &&
-	git fetch &&
-	git branch --set-upstream master origin/frotz &&
-
-	test "z$(git config branch.master.remote)" = "zorigin" &&
-	test "z$(git config branch.master.merge)" = "zrefs/heads/frotz"
-
-'
-
 test_expect_success 'use --edit-description' '
 	write_script editor <<-\EOF &&
 		echo "New contents" >"$1"
-- 
2.14.0.rc1.434.g6eded367a

[PATCH 2/2 / RFC] branch: quote branch/ref names to improve readability

[Kaartic Sivaraam]

Signed-off-by: Kaartic Sivaraam <kaarticsivaraam91196@gmail.com>
---
 branch.c | 16 ++++++++--------
 1 file changed, 8 insertions(+), 8 deletions(-)

diff --git a/branch.c b/branch.c
index ad5a2299b..a40721f3c 100644
--- a/branch.c
+++ b/branch.c
@@ -90,24 +90,24 @@ int install_branch_config(int flag, const char *local, const char *origin, const
 		if (shortname) {
 			if (origin)
 				printf_ln(rebasing ?
-					  _("Branch %s set up to track remote branch %s from %s by rebasing.") :
-					  _("Branch %s set up to track remote branch %s from %s."),
+					  _("Branch '%s' set up to track remote branch '%s' from '%s' by rebasing.") :
+					  _("Branch '%s' set up to track remote branch '%s' from '%s'."),
 					  local, shortname, origin);
 			else
 				printf_ln(rebasing ?
-					  _("Branch %s set up to track local branch %s by rebasing.") :
-					  _("Branch %s set up to track local branch %s."),
+					  _("Branch '%s' set up to track local branch '%s' by rebasing.") :
+					  _("Branch '%s' set up to track local branch '%s'."),
 					  local, shortname);
 		} else {
 			if (origin)
 				printf_ln(rebasing ?
-					  _("Branch %s set up to track remote ref %s by rebasing.") :
-					  _("Branch %s set up to track remote ref %s."),
+					  _("Branch '%s' set up to track remote ref '%s' by rebasing.") :
+					  _("Branch '%s' set up to track remote ref '%s'."),
 					  local, remote);
 			else
 				printf_ln(rebasing ?
-					  _("Branch %s set up to track local ref %s by rebasing.") :
-					  _("Branch %s set up to track local ref %s."),
+					  _("Branch '%s' set up to track local ref '%s' by rebasing.") :
+					  _("Branch '%s' set up to track local ref '%s'."),
 					  local, remote);
 		}
 	}
-- 
2.14.0.rc1.434.g6eded367a

Re: Change in output as a result of patch

[Kaartic Sivaraam]

On Mon, 2017-07-24 at 14:25 -0700, Junio C Hamano wrote:
> I suspect that with a moderately-sized refactoring around
> validate_new_branchname() function, this should be doable.  Instead
> of passing two "int" parameters force and attr_only, make them into
> a single "unsigned flag"
I guess it's not possible to merge the two parameters into one as the
following code path shouldn't be taken when 'attr_only' is set,

    if (!attr_only) {
    	    const char *head;
    	    struct object_id oid;

    	    head = resolve_ref_unsafe("HEAD", 0, oid.hash, NULL);
    	    if (!is_bare_repository() && head && !strcmp(head, ref->buf))
    	    	    die(_("Cannot force update the current branch."));
    }

and I guess this means the 'attr_only' can't merged with 'force'.

Further, I saw this in 'branch.h'

>  NEEDSWORK: This needs to be split into two separate functions in the
>  longer run for sanity.

Any ways in which I could help with this?

-- 
Kaartic

Re: Can the '--set-upstream' option of branch be removed ?

[Junio C Hamano]

Kaartic Sivaraam <kaarticsivaraam91196@gmail.com> writes:

> I refactored builtin/branch.c to remove the '--set-upstream'
> option,successfully. The corresponding patch follows. 
>
> There's just one issue with the version of git that doesn't
> have the '--set-upstream' option. It's described in the commit
> log message of the following patch.

which is...

> Note that, 'git branch' still *accepts* '--set-upstream' as a consequence
> of "unique prefix can be abbrievated in option names". '--set-upstream'
> is a unique prefix of '--set-upstream-to' after '--set-upstream' has
> been removed.

... this.

Thanks for spotting the issue.  

I think in the longer term we still want to remove --set-upstream as
many people seem to say that its behaviour has been uttering
confusing to them and that is why we keep giving the warning any
time it is used.

> I guess it would be difficult to detect the removal of the option in
> case it's used in scripts and might cause confusion to users?

If we want to follow through the transition, because of the issue
you spotted, we'd need one extra step to make sure users won't be
hurt before removal: we would need to still recognize --set-upstream
as an option distinct from --set-upstream-to, and actively fail the
request, telling them that the former option no longer is supported.

Then after waiting for a few years, we may be able to re-introduce
the "--set-upstream" option that takes the arguments in the same
order as "--set-upstream-to", which would be the ideal endgame
(assuming that the reason why we started deprecating "--set-upstream"
and encouraged users to use "--set-upstream-to" still holds).

Re: Can the '--set-upstream' option of branch be removed ?

[Kaartic Sivaraam]

On Mon, 2017-08-07 at 13:59 -0700, Junio C Hamano wrote:
> Kaartic Sivaraam <kaarticsivaraam91196@gmail.com> writes:
> 
> > I refactored builtin/branch.c to remove the '--set-upstream'
> > option,successfully. The corresponding patch follows. 
> > 
> > There's just one issue with the version of git that doesn't
> > have the '--set-upstream' option. It's described in the commit
> > log message of the following patch.
> 
> which is...
> 
> > Note that, 'git branch' still *accepts* '--set-upstream' as a consequence
> > of "unique prefix can be abbrievated in option names". '--set-upstream'
> > is a unique prefix of '--set-upstream-to' after '--set-upstream' has
> > been removed.
> 
> ... this.
> 
> Thanks for spotting the issue.  
> 
Oh, I would have to thank you for enlightening me about,

    "unique prefix can be abbrievated in option names"

If I didn't know that, it would taken me some time (or an email) to
find why 'git' accepted  '--set-upstream' even after it's removal!

> I think in the longer term we still want to remove --set-upstream as
> many people seem to say that its behaviour has been uttering
> confusing to them and that is why we keep giving the warning any
> time it is used.
> 
I do accept that. The behaviour of '--set-upstream' is awkward.

> > I guess it would be difficult to detect the removal of the option in
> > case it's used in scripts and might cause confusion to users?
> 
> If we want to follow through the transition, because of the issue
> you spotted, we'd need one extra step to make sure users won't be
> hurt before removal: we would need to still recognize --set-upstream
> as an option distinct from --set-upstream-to, and actively fail thes
> request, telling them that the former option no longer is supported.
> 
There's no issue in doing that if people don't shout at us for the
behaviour :)

Just to be sure, you mean "die() with a good message" when you say
"fail these requests, telling them that the former option no longer is
supported."

> Then after waiting for a few years, we may be able to re-introduce
> the "--set-upstream" option that takes the arguments in the same
> order as "--set-upstream-to", which would be the ideal endgame
> (assuming that the reason why we started deprecating "--set-upstream"
> and encouraged users to use "--set-upstream-to" still holds).
> 
It's pretty surprising it takes almost a decade to *stop accepting* a
bad option though many users are confused by it. 

"It's easier to do things than to undo them!"

-- 
Kaartic

Re: Can the '--set-upstream' option of branch be removed ?

[Junio C Hamano]

Kaartic Sivaraam <kaarticsivaraam91196@gmail.com> writes:

> Just to be sure, you mean "die() with a good message" when you say
> "fail these requests, telling them that the former option no longer is
> supported."

Yes.

> It's pretty surprising it takes almost a decade to *stop accepting* a
> bad option though many users are confused by it.
>
> "It's easier to do things than to undo them!"

Yes, that is why we try to be extra cautious when adding new things.

[PATCH v2 1/2 / RFC] builtin/branch: stop supporting the use of --set-upstream option

[Kaartic Sivaraam]

The '--set-upstream' option of branch was deprecated in,

    b347d06bf branch: deprecate --set-upstream and show help if we
    detect possible mistaken use (Thu, 30 Aug 2012 19:23:13 +0200)

It was deprecated for the reasons specified in the commit message of
the referenced commit.

Refactor 'branch' so that it dies with an appropraite error message
when the '--set-upstream' is used.

Note that there's a reason behind "dying with an error message" instead of
"not accepting the '--set-upstream'". ;git branch' would still *accept*
'--set-upstream' even after it's removal as a consequence of "unique
prefix can be abbrievated in option names" AND '--set-upstream' is a unique
prefix of '--set-upstream-to' when '--set-upstream' has been removed. In
order to smooth the transition for users due to the "prefix issue" it was
decided to make branch die when seeing the '--set-upstream' flag for a few
years and let the users know that it would be removed some time in the future.

The before/after behaviour for a simple case follows,

    $ git remote
    origin

Before,

    $ git branch
    * master

    $ git branch --set-upstream origin/master
    The --set-upstream flag is deprecated and will be removed. Consider using --track or --set-upstream-to
    Branch origin/master set up to track local branch master.

    $ echo $?
    0

    $ git branch
    * master
      origin/master

After,

    $ git branch
    * master

    $ git branch --set-upstream origin/master
    fatal: the '--set-upstream' flag is no longer supported and will be removed. Consider using '--track' or '--set-upstream-to'

    $ echo $?
    128

    $ git branch
    * master

Signed-off-by: Kaartic Sivaraam <kaarticsivaraam91196@gmail.com>
---
 Changes in v2:

 The previous patch removed the concerned option while the current patch
 makes 'git branch' die on seeing the option.

 The possibility of '--set-upstream' becoming an alias of  '--set-upstream-to'
 was documented.

 Documentation/git-branch.txt |  8 +++----
 builtin/branch.c             | 21 +------------------
 t/t3200-branch.sh            | 50 ++++----------------------------------------
 t/t6040-tracking-info.sh     | 16 +++++++-------
 4 files changed, 17 insertions(+), 78 deletions(-)

diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt
index 81bd0a7b7..372107e0c 100644
--- a/Documentation/git-branch.txt
+++ b/Documentation/git-branch.txt
@@ -195,10 +195,10 @@ start-point is either a local or remote-tracking branch.
 	branch.autoSetupMerge configuration variable is true.
 
 --set-upstream::
-	If specified branch does not exist yet or if `--force` has been
-	given, acts exactly like `--track`. Otherwise sets up configuration
-	like `--track` would when creating the branch, except that where
-	branch points to is not changed.
+	This option is no longer supported and will be removed in the future.
+	Consider using --track or --set-upstream-to instead.
++
+Note: This could possibly become an alias of --set-upstream-to in the future.
 
 -u <upstream>::
 --set-upstream-to=<upstream>::
diff --git a/builtin/branch.c b/builtin/branch.c
index a3bd2262b..2fcb6f7e5 100644
--- a/builtin/branch.c
+++ b/builtin/branch.c
@@ -755,8 +755,6 @@ int cmd_branch(int argc, const char **argv, const char *prefix)
 		strbuf_release(&buf);
 	} else if (argc > 0 && argc <= 2) {
 		struct branch *branch = branch_get(argv[0]);
-		int branch_existed = 0, remote_tracking = 0;
-		struct strbuf buf = STRBUF_INIT;
 
 		if (!strcmp(argv[0], "HEAD"))
 			die(_("it does not make sense to create 'HEAD' manually"));
@@ -768,28 +766,11 @@ int cmd_branch(int argc, const char **argv, const char *prefix)
 			die(_("-a and -r options to 'git branch' do not make sense with a branch name"));
 
 		if (track == BRANCH_TRACK_OVERRIDE)
-			fprintf(stderr, _("The --set-upstream flag is deprecated and will be removed. Consider using --track or --set-upstream-to\n"));
+			die(_("the '--set-upstream' flag is no longer supported and will be removed. Consider using '--track' or '--set-upstream-to'"));
 
-		strbuf_addf(&buf, "refs/remotes/%s", branch->name);
-		remote_tracking = ref_exists(buf.buf);
-		strbuf_release(&buf);
-
-		branch_existed = ref_exists(branch->refname);
 		create_branch(argv[0], (argc == 2) ? argv[1] : head,
 			      force, reflog, 0, quiet, track);
 
-		/*
-		 * We only show the instructions if the user gave us
-		 * one branch which doesn't exist locally, but is the
-		 * name of a remote-tracking branch.
-		 */
-		if (argc == 1 && track == BRANCH_TRACK_OVERRIDE &&
-		    !branch_existed && remote_tracking) {
-			fprintf(stderr, _("\nIf you wanted to make '%s' track '%s', do this:\n\n"), head, branch->name);
-			fprintf(stderr, "    git branch -d %s\n", branch->name);
-			fprintf(stderr, "    git branch --set-upstream-to %s\n", branch->name);
-		}
-
 	} else
 		usage_with_options(builtin_branch_usage, options);
 
diff --git a/t/t3200-branch.sh b/t/t3200-branch.sh
index dd37ac47c..249be4b1a 100755
--- a/t/t3200-branch.sh
+++ b/t/t3200-branch.sh
@@ -561,7 +561,8 @@ test_expect_success 'use --set-upstream-to modify a particular branch' '
 	git branch my13 &&
 	git branch --set-upstream-to master my13 &&
 	test "$(git config branch.my13.remote)" = "." &&
-	test "$(git config branch.my13.merge)" = "refs/heads/master"
+	test "$(git config branch.my13.merge)" = "refs/heads/master" &&
+	git branch --unset-upstream my13
 '
 
 test_expect_success '--unset-upstream should fail if given a non-existent branch' '
@@ -605,38 +606,8 @@ test_expect_success 'test --unset-upstream on a particular branch' '
 	test_must_fail git config branch.my14.merge
 '
 
-test_expect_success '--set-upstream shows message when creating a new branch that exists as remote-tracking' '
-	git update-ref refs/remotes/origin/master HEAD &&
-	git branch --set-upstream origin/master 2>actual &&
-	test_when_finished git update-ref -d refs/remotes/origin/master &&
-	test_when_finished git branch -d origin/master &&
-	cat >expected <<EOF &&
-The --set-upstream flag is deprecated and will be removed. Consider using --track or --set-upstream-to
-
-If you wanted to make '"'master'"' track '"'origin/master'"', do this:
-
-    git branch -d origin/master
-    git branch --set-upstream-to origin/master
-EOF
-	test_i18ncmp expected actual
-'
-
-test_expect_success '--set-upstream with two args only shows the deprecation message' '
-	git branch --set-upstream master my13 2>actual &&
-	test_when_finished git branch --unset-upstream master &&
-	cat >expected <<EOF &&
-The --set-upstream flag is deprecated and will be removed. Consider using --track or --set-upstream-to
-EOF
-	test_i18ncmp expected actual
-'
-
-test_expect_success '--set-upstream with one arg only shows the deprecation message if the branch existed' '
-	git branch --set-upstream my13 2>actual &&
-	test_when_finished git branch --unset-upstream my13 &&
-	cat >expected <<EOF &&
-The --set-upstream flag is deprecated and will be removed. Consider using --track or --set-upstream-to
-EOF
-	test_i18ncmp expected actual
+test_expect_success '--set-upstream fails' '
+    test_must_fail git branch --set-upstream origin/master
 '
 
 test_expect_success '--set-upstream-to notices an error to set branch as own upstream' '
@@ -961,19 +932,6 @@ test_expect_success 'attempt to delete a branch merged to its base' '
 	test_must_fail git branch -d my10
 '
 
-test_expect_success 'use set-upstream on the current branch' '
-	git checkout master &&
-	git --bare init myupstream.git &&
-	git push myupstream.git master:refs/heads/frotz &&
-	git remote add origin myupstream.git &&
-	git fetch &&
-	git branch --set-upstream master origin/frotz &&
-
-	test "z$(git config branch.master.remote)" = "zorigin" &&
-	test "z$(git config branch.master.merge)" = "zrefs/heads/frotz"
-
-'
-
 test_expect_success 'use --edit-description' '
 	write_script editor <<-\EOF &&
 		echo "New contents" >"$1"
diff --git a/t/t6040-tracking-info.sh b/t/t6040-tracking-info.sh
index 97a07655a..4b522f456 100755
--- a/t/t6040-tracking-info.sh
+++ b/t/t6040-tracking-info.sh
@@ -188,35 +188,35 @@ test_expect_success 'fail to track annotated tags' '
 	test_must_fail git checkout heavytrack
 '
 
-test_expect_success 'setup tracking with branch --set-upstream on existing branch' '
+test_expect_success 'setup tracking with branch --set-upstream-to on existing branch' '
 	git branch from-master master &&
 	test_must_fail git config branch.from-master.merge > actual &&
-	git branch --set-upstream from-master master &&
+	git branch --set-upstream-to master from-master &&
 	git config branch.from-master.merge > actual &&
 	grep -q "^refs/heads/master$" actual
 '
 
-test_expect_success '--set-upstream does not change branch' '
+test_expect_success '--set-upstream-to does not change branch' '
 	git branch from-master2 master &&
 	test_must_fail git config branch.from-master2.merge > actual &&
 	git rev-list from-master2 &&
 	git update-ref refs/heads/from-master2 from-master2^ &&
 	git rev-parse from-master2 >expect2 &&
-	git branch --set-upstream from-master2 master &&
+	git branch --set-upstream-to master from-master2 &&
 	git config branch.from-master.merge > actual &&
 	git rev-parse from-master2 >actual2 &&
 	grep -q "^refs/heads/master$" actual &&
 	cmp expect2 actual2
 '
 
-test_expect_success '--set-upstream @{-1}' '
-	git checkout from-master &&
+test_expect_success '--set-upstream-to @{-1}' '
+	git checkout follower &&
 	git checkout from-master2 &&
 	git config branch.from-master2.merge > expect2 &&
-	git branch --set-upstream @{-1} follower &&
+	git branch --set-upstream-to @{-1} from-master &&
 	git config branch.from-master.merge > actual &&
 	git config branch.from-master2.merge > actual2 &&
-	git branch --set-upstream from-master follower &&
+	git branch --set-upstream-to follower from-master &&
 	git config branch.from-master.merge > expect &&
 	test_cmp expect2 actual2 &&
 	test_cmp expect actual
-- 
2.14.0.rc1.434.g6eded367a

[PATCH v2 2/2 / RFC] branch: quote branch/ref names to improve readability

[Kaartic Sivaraam]

Signed-off-by: Kaartic Sivaraam <kaarticsivaraam91196@gmail.com>
---
 branch.c | 16 ++++++++--------
 1 file changed, 8 insertions(+), 8 deletions(-)

diff --git a/branch.c b/branch.c
index ad5a2299b..a40721f3c 100644
--- a/branch.c
+++ b/branch.c
@@ -90,24 +90,24 @@ int install_branch_config(int flag, const char *local, const char *origin, const
 		if (shortname) {
 			if (origin)
 				printf_ln(rebasing ?
-					  _("Branch %s set up to track remote branch %s from %s by rebasing.") :
-					  _("Branch %s set up to track remote branch %s from %s."),
+					  _("Branch '%s' set up to track remote branch '%s' from '%s' by rebasing.") :
+					  _("Branch '%s' set up to track remote branch '%s' from '%s'."),
 					  local, shortname, origin);
 			else
 				printf_ln(rebasing ?
-					  _("Branch %s set up to track local branch %s by rebasing.") :
-					  _("Branch %s set up to track local branch %s."),
+					  _("Branch '%s' set up to track local branch '%s' by rebasing.") :
+					  _("Branch '%s' set up to track local branch '%s'."),
 					  local, shortname);
 		} else {
 			if (origin)
 				printf_ln(rebasing ?
-					  _("Branch %s set up to track remote ref %s by rebasing.") :
-					  _("Branch %s set up to track remote ref %s."),
+					  _("Branch '%s' set up to track remote ref '%s' by rebasing.") :
+					  _("Branch '%s' set up to track remote ref '%s'."),
 					  local, remote);
 			else
 				printf_ln(rebasing ?
-					  _("Branch %s set up to track local ref %s by rebasing.") :
-					  _("Branch %s set up to track local ref %s."),
+					  _("Branch '%s' set up to track local ref '%s' by rebasing.") :
+					  _("Branch '%s' set up to track local ref '%s'."),
 					  local, remote);
 		}
 	}
-- 
2.14.0.rc1.434.g6eded367a

Re: [PATCH v2 1/2 / RFC] builtin/branch: stop supporting the use of --set-upstream option

[Martin Ågren]

On 8 August 2017 at 19:11, Kaartic Sivaraam
<kaarticsivaraam91196@gmail.com> wrote:
> The '--set-upstream' option of branch was deprecated in,
>
>     b347d06bf branch: deprecate --set-upstream and show help if we
>     detect possible mistaken use (Thu, 30 Aug 2012 19:23:13 +0200)
>
> It was deprecated for the reasons specified in the commit message of
> the referenced commit.
>
> Refactor 'branch' so that it dies with an appropraite error message
> when the '--set-upstream' is used.

appropriate. (Also, is this really a refactoring?)

>
> Note that there's a reason behind "dying with an error message" instead of
> "not accepting the '--set-upstream'". ;git branch' would still *accept*
> '--set-upstream' even after it's removal as a consequence of "unique
> prefix can be abbrievated in option names" AND '--set-upstream' is a unique
> prefix of '--set-upstream-to' when '--set-upstream' has been removed. In
> order to smooth the transition for users due to the "prefix issue" it was
> decided to make branch die when seeing the '--set-upstream' flag for a few
> years and let the users know that it would be removed some time in the future.
>
> The before/after behaviour for a simple case follows,
>
>     $ git remote
>     origin
>
> Before,
>
>     $ git branch
>     * master
>
>     $ git branch --set-upstream origin/master
>     The --set-upstream flag is deprecated and will be removed. Consider using --track or --set-upstream-to
>     Branch origin/master set up to track local branch master.
>
>     $ echo $?
>     0
>
>     $ git branch
>     * master
>       origin/master
>
> After,
>
>     $ git branch
>     * master
>
>     $ git branch --set-upstream origin/master
>     fatal: the '--set-upstream' flag is no longer supported and will be removed. Consider using '--track' or '--set-upstream-to'
>
>     $ echo $?
>     128
>
>     $ git branch
>     * master
>
> Signed-off-by: Kaartic Sivaraam <kaarticsivaraam91196@gmail.com>
> ---
>  Changes in v2:
>
>  The previous patch removed the concerned option while the current patch
>  makes 'git branch' die on seeing the option.
>
>  The possibility of '--set-upstream' becoming an alias of  '--set-upstream-to'
>  was documented.
>
>  Documentation/git-branch.txt |  8 +++----
>  builtin/branch.c             | 21 +------------------
>  t/t3200-branch.sh            | 50 ++++----------------------------------------
>  t/t6040-tracking-info.sh     | 16 +++++++-------
>  4 files changed, 17 insertions(+), 78 deletions(-)
>
> diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt
> index 81bd0a7b7..372107e0c 100644
> --- a/Documentation/git-branch.txt
> +++ b/Documentation/git-branch.txt
> @@ -195,10 +195,10 @@ start-point is either a local or remote-tracking branch.
>         branch.autoSetupMerge configuration variable is true.
>
>  --set-upstream::
> -       If specified branch does not exist yet or if `--force` has been
> -       given, acts exactly like `--track`. Otherwise sets up configuration
> -       like `--track` would when creating the branch, except that where
> -       branch points to is not changed.
> +       This option is no longer supported and will be removed in the future.
> +       Consider using --track or --set-upstream-to instead.
> ++
> +Note: This could possibly become an alias of --set-upstream-to in the future.

Maybe the final note could be removed? Someone who is looking up
--set-upstream because Git just "crashed" on them will only want to know
what they should do instead. Our thoughts about the future are perhaps
not that interesting. (I sort of wonder if this option needs to be
documented at all, especially if this doesn't say anything more than
the die() just did.)

Also, I'm wondering if it should be "has been removed" instead of "will
be removed"? /Implementation-wise/, it has not been removed yet, but to
the user, it has. So maybe just "This option has been removed. Consider
using --track or --set-upstream-to instead." The same below.

I don't know if it's worth trying to use PARSE_OPT_HIDDEN in the
options-struct?

Martin

>  -u <upstream>::
>  --set-upstream-to=<upstream>::
> diff --git a/builtin/branch.c b/builtin/branch.c
> index a3bd2262b..2fcb6f7e5 100644
> --- a/builtin/branch.c
> +++ b/builtin/branch.c
> @@ -755,8 +755,6 @@ int cmd_branch(int argc, const char **argv, const char *prefix)
>                 strbuf_release(&buf);
>         } else if (argc > 0 && argc <= 2) {
>                 struct branch *branch = branch_get(argv[0]);
> -               int branch_existed = 0, remote_tracking = 0;
> -               struct strbuf buf = STRBUF_INIT;
>
>                 if (!strcmp(argv[0], "HEAD"))
>                         die(_("it does not make sense to create 'HEAD' manually"));
> @@ -768,28 +766,11 @@ int cmd_branch(int argc, const char **argv, const char *prefix)
>                         die(_("-a and -r options to 'git branch' do not make sense with a branch name"));
>
>                 if (track == BRANCH_TRACK_OVERRIDE)
> -                       fprintf(stderr, _("The --set-upstream flag is deprecated and will be removed. Consider using --track or --set-upstream-to\n"));
> +                       die(_("the '--set-upstream' flag is no longer supported and will be removed. Consider using '--track' or '--set-upstream-to'"));
>
> -               strbuf_addf(&buf, "refs/remotes/%s", branch->name);
> -               remote_tracking = ref_exists(buf.buf);
> -               strbuf_release(&buf);
> -
> -               branch_existed = ref_exists(branch->refname);
>                 create_branch(argv[0], (argc == 2) ? argv[1] : head,
>                               force, reflog, 0, quiet, track);
>
> -               /*
> -                * We only show the instructions if the user gave us
> -                * one branch which doesn't exist locally, but is the
> -                * name of a remote-tracking branch.
> -                */
> -               if (argc == 1 && track == BRANCH_TRACK_OVERRIDE &&
> -                   !branch_existed && remote_tracking) {
> -                       fprintf(stderr, _("\nIf you wanted to make '%s' track '%s', do this:\n\n"), head, branch->name);
> -                       fprintf(stderr, "    git branch -d %s\n", branch->name);
> -                       fprintf(stderr, "    git branch --set-upstream-to %s\n", branch->name);
> -               }
> -
>         } else
>                 usage_with_options(builtin_branch_usage, options);

Re: [PATCH v2 2/2 / RFC] branch: quote branch/ref names to improve readability

[Stefan Beller]

On Tue, Aug 8, 2017 at 10:11 AM, Kaartic Sivaraam
<kaarticsivaraam91196@gmail.com> wrote:
> Signed-off-by: Kaartic Sivaraam <kaarticsivaraam91196@gmail.com>
> ---
>  branch.c | 16 ++++++++--------
>  1 file changed, 8 insertions(+), 8 deletions(-)

I like this patch.

In submodule.c we quote a lot of things (branches, submodules, paths), so
this is another step to make the output as a whole more consistent.
(Though wondering for non-submodule users, if they perceive it as
inconsistency as other parts of the code may not follow the rigorous quoting)

>
> diff --git a/branch.c b/branch.c
> index ad5a2299b..a40721f3c 100644
> --- a/branch.c
> +++ b/branch.c
> @@ -90,24 +90,24 @@ int install_branch_config(int flag, const char *local, const char *origin, const
>                 if (shortname) {
>                         if (origin)
>                                 printf_ln(rebasing ?
> -                                         _("Branch %s set up to track remote branch %s from %s by rebasing.") :
> -                                         _("Branch %s set up to track remote branch %s from %s."),
> +                                         _("Branch '%s' set up to track remote branch '%s' from '%s' by rebasing.") :
> +                                         _("Branch '%s' set up to track remote branch '%s' from '%s'."),
>                                           local, shortname, origin);
>                         else
>                                 printf_ln(rebasing ?
> -                                         _("Branch %s set up to track local branch %s by rebasing.") :
> -                                         _("Branch %s set up to track local branch %s."),
> +                                         _("Branch '%s' set up to track local branch '%s' by rebasing.") :
> +                                         _("Branch '%s' set up to track local branch '%s'."),
>                                           local, shortname);
>                 } else {
>                         if (origin)
>                                 printf_ln(rebasing ?
> -                                         _("Branch %s set up to track remote ref %s by rebasing.") :
> -                                         _("Branch %s set up to track remote ref %s."),
> +                                         _("Branch '%s' set up to track remote ref '%s' by rebasing.") :
> +                                         _("Branch '%s' set up to track remote ref '%s'."),
>                                           local, remote);
>                         else
>                                 printf_ln(rebasing ?
> -                                         _("Branch %s set up to track local ref %s by rebasing.") :
> -                                         _("Branch %s set up to track local ref %s."),
> +                                         _("Branch '%s' set up to track local ref '%s' by rebasing.") :
> +                                         _("Branch '%s' set up to track local ref '%s'."),
>                                           local, remote);
>                 }
>         }
> --
> 2.14.0.rc1.434.g6eded367a
>

Re: [PATCH v2 2/2 / RFC] branch: quote branch/ref names to improve readability

[Junio C Hamano]

Stefan Beller <sbeller@google.com> writes:

> (Though wondering for non-submodule users, if they perceive it as
> inconsistency as other parts of the code may not follow the rigorous quoting)

Do you mean that we may instead want to remove the excessive quoting
of branch names and stuff from submodule.c code, because they are
newer ones that broke the consistency existed before them (i.e. not
quoting)?

That certainly is tempting, but I personally find it easier to read
a message that marks parts that holds "external data" differently
from the message's text, so I think this patch 2/2 goes in the right
direction.

Re: [PATCH v2 2/2 / RFC] branch: quote branch/ref names to improve readability

[Stefan Beller]

On Tue, Aug 8, 2017 at 12:43 PM, Junio C Hamano <gitster@pobox.com> wrote:
> Stefan Beller <sbeller@google.com> writes:
>
>> (Though wondering for non-submodule users, if they perceive it as
>> inconsistency as other parts of the code may not follow the rigorous quoting)
>
> Do you mean that we may instead want to remove the excessive quoting
> of branch names and stuff from submodule.c code, because they are
> newer ones that broke the consistency existed before them (i.e. not
> quoting)?

No, I do not. I was just wondering if a non-submodule user
may see differences between different commands now.

For example "checkout -b" already quotes 'external data', which
would be inline with this proposal, but there may be others.
My question was rather an encouragement to check the code base
if there are other occurrences left that do not quote.

In an ideal code base we could just grep for any %s that has no
surrounding quotes, but of course it is not as easy in the real world:
* some outputs use %s construction for non-human consumption
  in e.g. the diff machinery
* sometimes we play sentence lego, stringing words together
  which also is using %s unquoted correctly.

> That certainly is tempting, but I personally find it easier to read
> a message that marks parts that holds "external data" differently
> from the message's text, so I think this patch 2/2 goes in the right
> direction.

Yes. I like the direction this patch is going.

A note on 'external data':
For branchs, paths, submodule names a single quote seems
to be best (my opinion), whereas in e.g. git-status:

    Submodule 'sm1' 0000000...1beffeb (new submodule)

parens seem to do a better job as they describe the state,
not reproducing external data. (This is also the place
where I was reminded of potential sentence lego)

Re: [PATCH v2 1/2 / RFC] builtin/branch: stop supporting the use of --set-upstream option

[Kaartic Sivaraam]

On Wednesday 09 August 2017 12:03 AM, Martin Ågren wrote:
> (Also, is this really a refactoring?) 

Not quite.

>>   --set-upstream::
>> -       If specified branch does not exist yet or if `--force` has been
>> -       given, acts exactly like `--track`. Otherwise sets up configuration
>> -       like `--track` would when creating the branch, except that where
>> -       branch points to is not changed.
>> +       This option is no longer supported and will be removed in the future.
>> +       Consider using --track or --set-upstream-to instead.
>> ++
>> +Note: This could possibly become an alias of --set-upstream-to in the future.
> Maybe the final note could be removed? Someone who is looking up
> --set-upstream because Git just "crashed" on them will only want to know
> what they should do instead. Our thoughts about the future are perhaps
> not that interesting.
I thought it's better to document it to avoid people from getting surprised
when the options *starts working* again.

> (I sort of wonder if this option needs to be
> documented at all, especially if this doesn't say anything more than
> the die() just did.)
Yeah, it needs improvement.

> Also, I'm wondering if it should be "has been removed" instead of "will
> be removed"? /Implementation-wise/, it has not been removed yet, but to
> the user, it has. So maybe just "This option has been removed. Consider
> using --track or --set-upstream-to instead." The same below.
I guess you're right. I thought "no longer supported" was equally
communicative.

[PATCH v3 1/2 / RFC] builtin/branch: stop supporting the use of --set-upstream option

[Kaartic Sivaraam]

The '--set-upstream' option of branch was deprecated in,

    b347d06bf branch: deprecate --set-upstream and show help if we
    detect possible mistaken use (Thu, 30 Aug 2012 19:23:13 +0200)

It was deprecated for the reasons specified in the commit message of the
referenced commit.

Make 'branch' die with an appropraite error message when the '--set-upstream'
option is used.

Note that there's a reason behind "dying with an error message" instead of
"not accepting the option". 'git branch' would *accept* '--set-upstream'
even after it's removal as a consequence of,

        Unique prefix can be abbrievated in option names

                          AND

    '--set-upstream' is a unique prefix of '--set-upstream-to'
       (when the '--set-upstream' option has been removed)

In order to smooth the transition for users and to avoid them being affected
by the "prefix issue" it was decided to make branch die when seeing the
'--set-upstream' flag for a few years and let the users know that it would be
removed some time in the future.

The before/after behaviour for a simple case follows,

    $ git remote
    origin

Before,

    $ git branch
    * master

    $ git branch --set-upstream origin/master
    The --set-upstream flag is deprecated and will be removed. Consider using --track or --set-upstream-to
    Branch origin/master set up to track local branch master.

    $ echo $?
    0

    $ git branch
    * master
      origin/master

After,

    $ git branch
    * master

    $ git branch --set-upstream origin/master
    fatal: the '--set-upstream' flag is no longer supported and will be removed. Consider using '--track' or '--set-upstream-to'

    $ echo $?
    128

    $ git branch
    * master

Signed-off-by: Kaartic Sivaraam <kaarticsivaraam91196@gmail.com>
---
 Changes in v3:
 
    A few tweaks to the following:
     * Commit message
     * Error message (the one shown when '--set-upstream' is seen)
     * Updated the corresponding message in the options structure
     * Documentation

 A query,

    I see the following code in the code path a little above the die statement
    added in this change,

            if (!strcmp(argv[0], "HEAD"))
    		    	die(_("it does not make sense to create 'HEAD' manually"));

    It does seem to be doing quite a nice job of avoiding an ambiguity that could
    have bad consequences but it's still possible to create a branch named 'HEAD'
    using the '-b' option of 'checkout'. Should 'git checkout -b HEAD' actually
    fail(it does not currently) for the same reason 'git branch HEAD' fails?

    My guess is that people would use 'git checkout -b <new_branch_name> <starting_point>'
    more than it's 'git branch' counterpart.    


 Documentation/git-branch.txt |  8 +++----
 builtin/branch.c             | 23 ++------------------
 t/t3200-branch.sh            | 50 ++++----------------------------------------
 t/t6040-tracking-info.sh     | 16 +++++++-------
 4 files changed, 18 insertions(+), 79 deletions(-)

diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt
index 81bd0a7b7..93ee05c55 100644
--- a/Documentation/git-branch.txt
+++ b/Documentation/git-branch.txt
@@ -195,10 +195,10 @@ start-point is either a local or remote-tracking branch.
 	branch.autoSetupMerge configuration variable is true.
 
 --set-upstream::
-	If specified branch does not exist yet or if `--force` has been
-	given, acts exactly like `--track`. Otherwise sets up configuration
-	like `--track` would when creating the branch, except that where
-	branch points to is not changed.
+	As this option has confusing syntax it's no longer supported. Please use
+  --track or --set-upstream-to  instead.
++
+Note: This could possibly become an alias of --set-upstream-to in the future.
 
 -u <upstream>::
 --set-upstream-to=<upstream>::
diff --git a/builtin/branch.c b/builtin/branch.c
index a3bd2262b..b92070393 100644
--- a/builtin/branch.c
+++ b/builtin/branch.c
@@ -557,7 +557,7 @@ int cmd_branch(int argc, const char **argv, const char *prefix)
 		OPT__QUIET(&quiet, N_("suppress informational messages")),
 		OPT_SET_INT('t', "track",  &track, N_("set up tracking mode (see git-pull(1))"),
 			BRANCH_TRACK_EXPLICIT),
-		OPT_SET_INT( 0, "set-upstream",  &track, N_("change upstream info"),
+		OPT_SET_INT( 0, "set-upstream",  &track, N_("no longer supported"),
 			BRANCH_TRACK_OVERRIDE),
 		OPT_STRING('u', "set-upstream-to", &new_upstream, N_("upstream"), N_("change the upstream info")),
 		OPT_BOOL(0, "unset-upstream", &unset_upstream, N_("Unset the upstream info")),
@@ -755,8 +755,6 @@ int cmd_branch(int argc, const char **argv, const char *prefix)
 		strbuf_release(&buf);
 	} else if (argc > 0 && argc <= 2) {
 		struct branch *branch = branch_get(argv[0]);
-		int branch_existed = 0, remote_tracking = 0;
-		struct strbuf buf = STRBUF_INIT;
 
 		if (!strcmp(argv[0], "HEAD"))
 			die(_("it does not make sense to create 'HEAD' manually"));
@@ -768,28 +766,11 @@ int cmd_branch(int argc, const char **argv, const char *prefix)
 			die(_("-a and -r options to 'git branch' do not make sense with a branch name"));
 
 		if (track == BRANCH_TRACK_OVERRIDE)
-			fprintf(stderr, _("The --set-upstream flag is deprecated and will be removed. Consider using --track or --set-upstream-to\n"));
+			die(_("the '--set-upstream' option is no longer supported. Please use '--track' or '--set-upstream-to' instead."));
 
-		strbuf_addf(&buf, "refs/remotes/%s", branch->name);
-		remote_tracking = ref_exists(buf.buf);
-		strbuf_release(&buf);
-
-		branch_existed = ref_exists(branch->refname);
 		create_branch(argv[0], (argc == 2) ? argv[1] : head,
 			      force, reflog, 0, quiet, track);
 
-		/*
-		 * We only show the instructions if the user gave us
-		 * one branch which doesn't exist locally, but is the
-		 * name of a remote-tracking branch.
-		 */
-		if (argc == 1 && track == BRANCH_TRACK_OVERRIDE &&
-		    !branch_existed && remote_tracking) {
-			fprintf(stderr, _("\nIf you wanted to make '%s' track '%s', do this:\n\n"), head, branch->name);
-			fprintf(stderr, "    git branch -d %s\n", branch->name);
-			fprintf(stderr, "    git branch --set-upstream-to %s\n", branch->name);
-		}
-
 	} else
 		usage_with_options(builtin_branch_usage, options);
 
diff --git a/t/t3200-branch.sh b/t/t3200-branch.sh
index dd37ac47c..249be4b1a 100755
--- a/t/t3200-branch.sh
+++ b/t/t3200-branch.sh
@@ -561,7 +561,8 @@ test_expect_success 'use --set-upstream-to modify a particular branch' '
 	git branch my13 &&
 	git branch --set-upstream-to master my13 &&
 	test "$(git config branch.my13.remote)" = "." &&
-	test "$(git config branch.my13.merge)" = "refs/heads/master"
+	test "$(git config branch.my13.merge)" = "refs/heads/master" &&
+	git branch --unset-upstream my13
 '
 
 test_expect_success '--unset-upstream should fail if given a non-existent branch' '
@@ -605,38 +606,8 @@ test_expect_success 'test --unset-upstream on a particular branch' '
 	test_must_fail git config branch.my14.merge
 '
 
-test_expect_success '--set-upstream shows message when creating a new branch that exists as remote-tracking' '
-	git update-ref refs/remotes/origin/master HEAD &&
-	git branch --set-upstream origin/master 2>actual &&
-	test_when_finished git update-ref -d refs/remotes/origin/master &&
-	test_when_finished git branch -d origin/master &&
-	cat >expected <<EOF &&
-The --set-upstream flag is deprecated and will be removed. Consider using --track or --set-upstream-to
-
-If you wanted to make '"'master'"' track '"'origin/master'"', do this:
-
-    git branch -d origin/master
-    git branch --set-upstream-to origin/master
-EOF
-	test_i18ncmp expected actual
-'
-
-test_expect_success '--set-upstream with two args only shows the deprecation message' '
-	git branch --set-upstream master my13 2>actual &&
-	test_when_finished git branch --unset-upstream master &&
-	cat >expected <<EOF &&
-The --set-upstream flag is deprecated and will be removed. Consider using --track or --set-upstream-to
-EOF
-	test_i18ncmp expected actual
-'
-
-test_expect_success '--set-upstream with one arg only shows the deprecation message if the branch existed' '
-	git branch --set-upstream my13 2>actual &&
-	test_when_finished git branch --unset-upstream my13 &&
-	cat >expected <<EOF &&
-The --set-upstream flag is deprecated and will be removed. Consider using --track or --set-upstream-to
-EOF
-	test_i18ncmp expected actual
+test_expect_success '--set-upstream fails' '
+    test_must_fail git branch --set-upstream origin/master
 '
 
 test_expect_success '--set-upstream-to notices an error to set branch as own upstream' '
@@ -961,19 +932,6 @@ test_expect_success 'attempt to delete a branch merged to its base' '
 	test_must_fail git branch -d my10
 '
 
-test_expect_success 'use set-upstream on the current branch' '
-	git checkout master &&
-	git --bare init myupstream.git &&
-	git push myupstream.git master:refs/heads/frotz &&
-	git remote add origin myupstream.git &&
-	git fetch &&
-	git branch --set-upstream master origin/frotz &&
-
-	test "z$(git config branch.master.remote)" = "zorigin" &&
-	test "z$(git config branch.master.merge)" = "zrefs/heads/frotz"
-
-'
-
 test_expect_success 'use --edit-description' '
 	write_script editor <<-\EOF &&
 		echo "New contents" >"$1"
diff --git a/t/t6040-tracking-info.sh b/t/t6040-tracking-info.sh
index 97a07655a..4b522f456 100755
--- a/t/t6040-tracking-info.sh
+++ b/t/t6040-tracking-info.sh
@@ -188,35 +188,35 @@ test_expect_success 'fail to track annotated tags' '
 	test_must_fail git checkout heavytrack
 '
 
-test_expect_success 'setup tracking with branch --set-upstream on existing branch' '
+test_expect_success 'setup tracking with branch --set-upstream-to on existing branch' '
 	git branch from-master master &&
 	test_must_fail git config branch.from-master.merge > actual &&
-	git branch --set-upstream from-master master &&
+	git branch --set-upstream-to master from-master &&
 	git config branch.from-master.merge > actual &&
 	grep -q "^refs/heads/master$" actual
 '
 
-test_expect_success '--set-upstream does not change branch' '
+test_expect_success '--set-upstream-to does not change branch' '
 	git branch from-master2 master &&
 	test_must_fail git config branch.from-master2.merge > actual &&
 	git rev-list from-master2 &&
 	git update-ref refs/heads/from-master2 from-master2^ &&
 	git rev-parse from-master2 >expect2 &&
-	git branch --set-upstream from-master2 master &&
+	git branch --set-upstream-to master from-master2 &&
 	git config branch.from-master.merge > actual &&
 	git rev-parse from-master2 >actual2 &&
 	grep -q "^refs/heads/master$" actual &&
 	cmp expect2 actual2
 '
 
-test_expect_success '--set-upstream @{-1}' '
-	git checkout from-master &&
+test_expect_success '--set-upstream-to @{-1}' '
+	git checkout follower &&
 	git checkout from-master2 &&
 	git config branch.from-master2.merge > expect2 &&
-	git branch --set-upstream @{-1} follower &&
+	git branch --set-upstream-to @{-1} from-master &&
 	git config branch.from-master.merge > actual &&
 	git config branch.from-master2.merge > actual2 &&
-	git branch --set-upstream from-master follower &&
+	git branch --set-upstream-to follower from-master &&
 	git config branch.from-master.merge > expect &&
 	test_cmp expect2 actual2 &&
 	test_cmp expect actual
-- 
2.14.0.rc1.434.g6eded367a

Re: [PATCH v3 1/2 / RFC] builtin/branch: stop supporting the use of --set-upstream option

[Martin Ågren]

On 14 August 2017 at 10:54, Kaartic Sivaraam
<kaarticsivaraam91196@gmail.com> wrote:
> The '--set-upstream' option of branch was deprecated in,
>
>     b347d06bf branch: deprecate --set-upstream and show help if we
>     detect possible mistaken use (Thu, 30 Aug 2012 19:23:13 +0200)
>
> It was deprecated for the reasons specified in the commit message of the
> referenced commit.
>
> Make 'branch' die with an appropraite error message when the '--set-upstream'
> option is used.
>
> Note that there's a reason behind "dying with an error message" instead of
> "not accepting the option". 'git branch' would *accept* '--set-upstream'
> even after it's removal as a consequence of,
>
>         Unique prefix can be abbrievated in option names
>
>                           AND
>
>     '--set-upstream' is a unique prefix of '--set-upstream-to'
>        (when the '--set-upstream' option has been removed)
>
> In order to smooth the transition for users and to avoid them being affected
> by the "prefix issue" it was decided to make branch die when seeing the
> '--set-upstream' flag for a few years and let the users know that it would be
> removed some time in the future.
>
> The before/after behaviour for a simple case follows,
>
>     $ git remote
>     origin
>
> Before,
>
>     $ git branch
>     * master
>
>     $ git branch --set-upstream origin/master
>     The --set-upstream flag is deprecated and will be removed. Consider using --track or --set-upstream-to
>     Branch origin/master set up to track local branch master.
>
>     $ echo $?
>     0
>
>     $ git branch
>     * master
>       origin/master
>
> After,
>
>     $ git branch
>     * master
>
>     $ git branch --set-upstream origin/master
>     fatal: the '--set-upstream' flag is no longer supported and will be removed. Consider using '--track' or '--set-upstream-to'
>
>     $ echo $?
>     128
>
>     $ git branch
>     * master
>
> Signed-off-by: Kaartic Sivaraam <kaarticsivaraam91196@gmail.com>
> ---
>  Changes in v3:
>
>     A few tweaks to the following:
>      * Commit message
>      * Error message (the one shown when '--set-upstream' is seen)
>      * Updated the corresponding message in the options structure
>      * Documentation
>
>  A query,
>
>     I see the following code in the code path a little above the die statement
>     added in this change,
>
>             if (!strcmp(argv[0], "HEAD"))
>                         die(_("it does not make sense to create 'HEAD' manually"));
>
>     It does seem to be doing quite a nice job of avoiding an ambiguity that could
>     have bad consequences but it's still possible to create a branch named 'HEAD'
>     using the '-b' option of 'checkout'. Should 'git checkout -b HEAD' actually
>     fail(it does not currently) for the same reason 'git branch HEAD' fails?
>
>     My guess is that people would use 'git checkout -b <new_branch_name> <starting_point>'
>     more than it's 'git branch' counterpart.
>
>
>  Documentation/git-branch.txt |  8 +++----
>  builtin/branch.c             | 23 ++------------------
>  t/t3200-branch.sh            | 50 ++++----------------------------------------
>  t/t6040-tracking-info.sh     | 16 +++++++-------
>  4 files changed, 18 insertions(+), 79 deletions(-)
>
> diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt
> index 81bd0a7b7..93ee05c55 100644
> --- a/Documentation/git-branch.txt
> +++ b/Documentation/git-branch.txt
> @@ -195,10 +195,10 @@ start-point is either a local or remote-tracking branch.
>         branch.autoSetupMerge configuration variable is true.
>
>  --set-upstream::
> -       If specified branch does not exist yet or if `--force` has been
> -       given, acts exactly like `--track`. Otherwise sets up configuration
> -       like `--track` would when creating the branch, except that where
> -       branch points to is not changed.
> +       As this option has confusing syntax it's no longer supported. Please use

"has" or "had"? (I guess when someone reads this, it "has" no syntax at
all. ;) )

> +  --track or --set-upstream-to  instead.

Maybe indent with a tab instead of two spaces for consistency with the
rest of the file.

> ++
> +Note: This could possibly become an alias of --set-upstream-to in the future.

(But not here.)

>
>  -u <upstream>::
>  --set-upstream-to=<upstream>::
> diff --git a/builtin/branch.c b/builtin/branch.c
> index a3bd2262b..b92070393 100644
> --- a/builtin/branch.c
> +++ b/builtin/branch.c
> @@ -557,7 +557,7 @@ int cmd_branch(int argc, const char **argv, const char *prefix)
>                 OPT__QUIET(&quiet, N_("suppress informational messages")),
>                 OPT_SET_INT('t', "track",  &track, N_("set up tracking mode (see git-pull(1))"),
>                         BRANCH_TRACK_EXPLICIT),
> -               OPT_SET_INT( 0, "set-upstream",  &track, N_("change upstream info"),
> +               OPT_SET_INT( 0, "set-upstream",  &track, N_("no longer supported"),
>                         BRANCH_TRACK_OVERRIDE),
>                 OPT_STRING('u', "set-upstream-to", &new_upstream, N_("upstream"), N_("change the upstream info")),
>                 OPT_BOOL(0, "unset-upstream", &unset_upstream, N_("Unset the upstream info")),
> @@ -755,8 +755,6 @@ int cmd_branch(int argc, const char **argv, const char *prefix)
>                 strbuf_release(&buf);
>         } else if (argc > 0 && argc <= 2) {
>                 struct branch *branch = branch_get(argv[0]);
> -               int branch_existed = 0, remote_tracking = 0;
> -               struct strbuf buf = STRBUF_INIT;
>
>                 if (!strcmp(argv[0], "HEAD"))
>                         die(_("it does not make sense to create 'HEAD' manually"));
> @@ -768,28 +766,11 @@ int cmd_branch(int argc, const char **argv, const char *prefix)
>                         die(_("-a and -r options to 'git branch' do not make sense with a branch name"));
>
>                 if (track == BRANCH_TRACK_OVERRIDE)
> -                       fprintf(stderr, _("The --set-upstream flag is deprecated and will be removed. Consider using --track or --set-upstream-to\n"));
> +                       die(_("the '--set-upstream' option is no longer supported. Please use '--track' or '--set-upstream-to' instead."));
>
> -               strbuf_addf(&buf, "refs/remotes/%s", branch->name);
> -               remote_tracking = ref_exists(buf.buf);
> -               strbuf_release(&buf);
> -
> -               branch_existed = ref_exists(branch->refname);
>                 create_branch(argv[0], (argc == 2) ? argv[1] : head,
>                               force, reflog, 0, quiet, track);
>
> -               /*
> -                * We only show the instructions if the user gave us
> -                * one branch which doesn't exist locally, but is the
> -                * name of a remote-tracking branch.
> -                */
> -               if (argc == 1 && track == BRANCH_TRACK_OVERRIDE &&
> -                   !branch_existed && remote_tracking) {
> -                       fprintf(stderr, _("\nIf you wanted to make '%s' track '%s', do this:\n\n"), head, branch->name);
> -                       fprintf(stderr, "    git branch -d %s\n", branch->name);
> -                       fprintf(stderr, "    git branch --set-upstream-to %s\n", branch->name);
> -               }
> -

Nice. :)

>         } else
>                 usage_with_options(builtin_branch_usage, options);
>
> diff --git a/t/t3200-branch.sh b/t/t3200-branch.sh
> index dd37ac47c..249be4b1a 100755
> --- a/t/t3200-branch.sh
> +++ b/t/t3200-branch.sh
> @@ -561,7 +561,8 @@ test_expect_success 'use --set-upstream-to modify a particular branch' '
>         git branch my13 &&
>         git branch --set-upstream-to master my13 &&
>         test "$(git config branch.my13.remote)" = "." &&
> -       test "$(git config branch.my13.merge)" = "refs/heads/master"
> +       test "$(git config branch.my13.merge)" = "refs/heads/master" &&
> +       git branch --unset-upstream my13

I think it would be safer to use test_when_finished like on line 625.
Out of curiosity: are you adding this out of caution, or did some later
test fail without this?

>  '
>
>  test_expect_success '--unset-upstream should fail if given a non-existent branch' '
> @@ -605,38 +606,8 @@ test_expect_success 'test --unset-upstream on a particular branch' '
>         test_must_fail git config branch.my14.merge
>  '
>
> -test_expect_success '--set-upstream shows message when creating a new branch that exists as remote-tracking' '
> -       git update-ref refs/remotes/origin/master HEAD &&
> -       git branch --set-upstream origin/master 2>actual &&
> -       test_when_finished git update-ref -d refs/remotes/origin/master &&
> -       test_when_finished git branch -d origin/master &&
> -       cat >expected <<EOF &&
> -The --set-upstream flag is deprecated and will be removed. Consider using --track or --set-upstream-to
> -
> -If you wanted to make '"'master'"' track '"'origin/master'"', do this:
> -
> -    git branch -d origin/master
> -    git branch --set-upstream-to origin/master
> -EOF
> -       test_i18ncmp expected actual
> -'
> -
> -test_expect_success '--set-upstream with two args only shows the deprecation message' '
> -       git branch --set-upstream master my13 2>actual &&
> -       test_when_finished git branch --unset-upstream master &&
> -       cat >expected <<EOF &&
> -The --set-upstream flag is deprecated and will be removed. Consider using --track or --set-upstream-to
> -EOF
> -       test_i18ncmp expected actual
> -'
> -
> -test_expect_success '--set-upstream with one arg only shows the deprecation message if the branch existed' '
> -       git branch --set-upstream my13 2>actual &&
> -       test_when_finished git branch --unset-upstream my13 &&
> -       cat >expected <<EOF &&
> -The --set-upstream flag is deprecated and will be removed. Consider using --track or --set-upstream-to
> -EOF
> -       test_i18ncmp expected actual
> +test_expect_success '--set-upstream fails' '
> +    test_must_fail git branch --set-upstream origin/master
>  '
>
>  test_expect_success '--set-upstream-to notices an error to set branch as own upstream' '
> @@ -961,19 +932,6 @@ test_expect_success 'attempt to delete a branch merged to its base' '
>         test_must_fail git branch -d my10
>  '
>
> -test_expect_success 'use set-upstream on the current branch' '
> -       git checkout master &&
> -       git --bare init myupstream.git &&
> -       git push myupstream.git master:refs/heads/frotz &&
> -       git remote add origin myupstream.git &&
> -       git fetch &&
> -       git branch --set-upstream master origin/frotz &&
> -
> -       test "z$(git config branch.master.remote)" = "zorigin" &&
> -       test "z$(git config branch.master.merge)" = "zrefs/heads/frotz"
> -
> -'
> -
>  test_expect_success 'use --edit-description' '
>         write_script editor <<-\EOF &&
>                 echo "New contents" >"$1"
> diff --git a/t/t6040-tracking-info.sh b/t/t6040-tracking-info.sh
> index 97a07655a..4b522f456 100755
> --- a/t/t6040-tracking-info.sh
> +++ b/t/t6040-tracking-info.sh
> @@ -188,35 +188,35 @@ test_expect_success 'fail to track annotated tags' '
>         test_must_fail git checkout heavytrack
>  '
>
> -test_expect_success 'setup tracking with branch --set-upstream on existing branch' '
> +test_expect_success 'setup tracking with branch --set-upstream-to on existing branch' '
>         git branch from-master master &&
>         test_must_fail git config branch.from-master.merge > actual &&
> -       git branch --set-upstream from-master master &&
> +       git branch --set-upstream-to master from-master &&
>         git config branch.from-master.merge > actual &&
>         grep -q "^refs/heads/master$" actual
>  '
>
> -test_expect_success '--set-upstream does not change branch' '
> +test_expect_success '--set-upstream-to does not change branch' '
>         git branch from-master2 master &&
>         test_must_fail git config branch.from-master2.merge > actual &&
>         git rev-list from-master2 &&
>         git update-ref refs/heads/from-master2 from-master2^ &&
>         git rev-parse from-master2 >expect2 &&
> -       git branch --set-upstream from-master2 master &&
> +       git branch --set-upstream-to master from-master2 &&
>         git config branch.from-master.merge > actual &&
>         git rev-parse from-master2 >actual2 &&
>         grep -q "^refs/heads/master$" actual &&
>         cmp expect2 actual2
>  '

The two tests above were added when --set-upstream was originally added.
Now that you're converting them to use --set-upstream-to, to what extent
do they just test the same thing as the tests in t3200?

>
> -test_expect_success '--set-upstream @{-1}' '
> -       git checkout from-master &&
> +test_expect_success '--set-upstream-to @{-1}' '
> +       git checkout follower &&
>         git checkout from-master2 &&
>         git config branch.from-master2.merge > expect2 &&
> -       git branch --set-upstream @{-1} follower &&
> +       git branch --set-upstream-to @{-1} from-master &&
>         git config branch.from-master.merge > actual &&
>         git config branch.from-master2.merge > actual2 &&
> -       git branch --set-upstream from-master follower &&
> +       git branch --set-upstream-to follower from-master &&
>         git config branch.from-master.merge > expect &&
>         test_cmp expect2 actual2 &&
>         test_cmp expect actual

I couldn't find any test of --set-upstream-to=@{...} in t3200, so this
probably does test something previously untested.

Martin

Re: [PATCH v3 1/2 / RFC] builtin/branch: stop supporting the use of --set-upstream option

[Junio C Hamano]

Kaartic Sivaraam <kaarticsivaraam91196@gmail.com> writes:

> The '--set-upstream' option of branch was deprecated in,
>
>     b347d06bf branch: deprecate --set-upstream and show help if we
>     detect possible mistaken use (Thu, 30 Aug 2012 19:23:13 +0200)
>
> It was deprecated for the reasons specified in the commit message of the
> referenced commit.

I wonder if these two lines add any value here.  Those who know the
reason would not be helped, and those who don't know have to view
"git show b347d06bf" anyway.

> Make 'branch' die with an appropraite error message when the '--set-upstream'
> option is used.

OK.

> Note that there's a reason behind "dying with an error message" instead of
> "not accepting the option". 'git branch' would *accept* '--set-upstream'
> even after it's removal as a consequence of,
>
>         Unique prefix can be abbrievated in option names
>
>                           AND
>
>     '--set-upstream' is a unique prefix of '--set-upstream-to'
>        (when the '--set-upstream' option has been removed)
>
> In order to smooth the transition for users and to avoid them being affected
> by the "prefix issue" it was decided to make branch die when seeing the
> '--set-upstream' flag for a few years and let the users know that it would be
> removed some time in the future.

I somehow think the above wastes bits a bit too much.  Wouldn't it
be sufficient to say

    In order to prevent "--set-upstream" on a command line from
    being taken as an abbreviated form of "--set-upstream-to",
    explicitly catch "--set-upstream" option and die, instead of
    just removing it from the list of options.

>     $ git branch --set-upstream origin/master
>     The --set-upstream flag is deprecated and will be removed. Consider using --track or --set-upstream-to
>     Branch origin/master set up to track local branch master.

> After,
>
>     $ git branch
>     * master
>
>     $ git branch --set-upstream origin/master
>     fatal: the '--set-upstream' flag is no longer supported and will be removed. Consider using '--track' or '--set-upstream-to'

Because from the end-user's point of view, it has already been
removed, I'd phrase it more like

	The --set-upstream option has been removed.  Use --track or ...

and make sure we do not list "--set-upstream" in the list of
supported options in

	git branch -h

output.

>  A query,
>
>     I see the following code in the code path a little above the die statement
>     added in this change,
>
>             if (!strcmp(argv[0], "HEAD"))
>     		    	die(_("it does not make sense to create 'HEAD' manually"));
>
>     It does seem to be doing quite a nice job of avoiding an ambiguity that could
>     have bad consequences but it's still possible to create a branch named 'HEAD'
>     using the '-b' option of 'checkout'. Should 'git checkout -b HEAD' actually
>     fail(it does not currently) for the same reason 'git branch HEAD' fails?
>
>     My guess is that people would use 'git checkout -b <new_branch_name> <starting_point>'
>     more than it's 'git branch' counterpart.    

Thanks for noticing.  I offhand see no reason not to do what you
suggest above.

> -		OPT_SET_INT( 0, "set-upstream",  &track, N_("change upstream info"),
> +		OPT_SET_INT( 0, "set-upstream",  &track, N_("no longer supported"),
>  			BRANCH_TRACK_OVERRIDE),

Here we would want to use something like

	{ OPTION_SET_INT, 0, "set-upstream", &track, NULL, N_("do not use"),
	  PARSE_OPT_NOARG | PARSE_OPT_HIDDEN, NULL, BRANCH_TRACK_OVERRIDE },

in order to hide the option from "git branch -h" output.

All review comments from Martin were also good ones, and I won't
repeat them here.

Thanks.

Re: [PATCH v3 1/2 / RFC] builtin/branch: stop supporting the use of --set-upstream option

[Kaartic Sivaraam]

On Tuesday 15 August 2017 12:44 AM, Martin Ågren wrote:
>>   --set-upstream::
>> -       If specified branch does not exist yet or if `--force` has been
>> -       given, acts exactly like `--track`. Otherwise sets up configuration
>> -       like `--track` would when creating the branch, except that where
>> -       branch points to is not changed.
>> +       As this option has confusing syntax it's no longer supported. Please use
> "has" or "had"? (I guess when someone reads this, it "has" no syntax at
> all. ;) )
Got it.
>> diff --git a/t/t3200-branch.sh b/t/t3200-branch.sh
>> index dd37ac47c..249be4b1a 100755
>> --- a/t/t3200-branch.sh
>> +++ b/t/t3200-branch.sh
>> @@ -561,7 +561,8 @@ test_expect_success 'use --set-upstream-to modify a particular branch' '
>>          git branch my13 &&
>>          git branch --set-upstream-to master my13 &&
>>          test "$(git config branch.my13.remote)" = "." &&
>> -       test "$(git config branch.my13.merge)" = "refs/heads/master"
>> +       test "$(git config branch.my13.merge)" = "refs/heads/master" &&
>> +       git branch --unset-upstream my13
> I think it would be safer to use test_when_finished like on line 625.
> Out of curiosity: are you adding this out of caution, or did some later
> test fail without this?
One test seems to fail without this. I guess it's better to keep this 
change as a separate
commit.

>> diff --git a/t/t6040-tracking-info.sh b/t/t6040-tracking-info.sh
>> index 97a07655a..4b522f456 100755
>> --- a/t/t6040-tracking-info.sh
>> +++ b/t/t6040-tracking-info.sh
>> @@ -188,35 +188,35 @@ test_expect_success 'fail to track annotated tags' '
>>          test_must_fail git checkout heavytrack
>>   '
>>
>> -test_expect_success 'setup tracking with branch --set-upstream on existing branch' '
>> +test_expect_success 'setup tracking with branch --set-upstream-to on existing branch' '
>>          git branch from-master master &&
>>          test_must_fail git config branch.from-master.merge > actual &&
>> -       git branch --set-upstream from-master master &&
>> +       git branch --set-upstream-to master from-master &&
>>          git config branch.from-master.merge > actual &&
>>          grep -q "^refs/heads/master$" actual
>>   '
>>
>> -test_expect_success '--set-upstream does not change branch' '
>> +test_expect_success '--set-upstream-to does not change branch' '
>>          git branch from-master2 master &&
>>          test_must_fail git config branch.from-master2.merge > actual &&
>>          git rev-list from-master2 &&
>>          git update-ref refs/heads/from-master2 from-master2^ &&
>>          git rev-parse from-master2 >expect2 &&
>> -       git branch --set-upstream from-master2 master &&
>> +       git branch --set-upstream-to master from-master2 &&
>>          git config branch.from-master.merge > actual &&
>>          git rev-parse from-master2 >actual2 &&
>>          grep -q "^refs/heads/master$" actual &&
>>          cmp expect2 actual2
>>   '
> The two tests above were added when --set-upstream was originally added.
> Now that you're converting them to use --set-upstream-to, to what extent
> do they just test the same thing as the tests in t3200?
The first seems useless, I'll remove it. Regarding the second one, as 
far as I could see
there's no test in t3200 that does something similar so I guess it could 
be kept back.

---
Kaartic

Re: [PATCH v3 1/2 / RFC] builtin/branch: stop supporting the use of --set-upstream option

[Kaartic Sivaraam]

On Tuesday 15 August 2017 01:49 AM, Junio C Hamano wrote:
> I wonder if these two lines add any value here. Those who know the
> reason would not be helped, and those who don't know have to view
> "git show b347d06bf" anyway.
That's right.

>
> I somehow think the above wastes bits a bit too much.  Wouldn't it
> be sufficient to say
>
>      In order to prevent "--set-upstream" on a command line from
>      being taken as an abbreviated form of "--set-upstream-to",
>      explicitly catch "--set-upstream" option and die, instead of
>      just removing it from the list of options.
Thanks for the shorter version. I'll use this :)

> Because from the end-user's point of view, it has already been
> removed, I'd phrase it more like
>
> 	The --set-upstream option has been removed.  Use --track or ...
I thought I changed it. It seems to have gone missing. Thanks for 
noticing this.

> and make sure we do not list "--set-upstream" in the list of
> supported options in
>
> 	git branch -h
>
> output.
I guess the instructions given below are enough. They do seem to be 
doing hiding it
from 'git branch -h'

> Here we would want to use something like
> 	{ OPTION_SET_INT, 0, "set-upstream", &track, NULL, N_("do not use"),
> 	  PARSE_OPT_NOARG | PARSE_OPT_HIDDEN, NULL, BRANCH_TRACK_OVERRIDE },
>
> in order to hide the option from "git branch -h" output.
>
> All review comments from Martin were also good ones, and I won't
> repeat them here.
>

>>   A query,
>>
>>      I see the following code in the code path a little above the die statement
>>      added in this change,
>>
>>              if (!strcmp(argv[0], "HEAD"))
>>      		    	die(_("it does not make sense to create 'HEAD' manually"));
>>
>>      It does seem to be doing quite a nice job of avoiding an ambiguity that could
>>      have bad consequences but it's still possible to create a branch named 'HEAD'
>>      using the '-b' option of 'checkout'. Should 'git checkout -b HEAD' actually
>>      fail(it does not currently) for the same reason 'git branch HEAD' fails?
>>
>>      My guess is that people would use 'git checkout -b <new_branch_name> <starting_point>'
>>      more than it's 'git branch' counterpart.
> Thanks for noticing.  I offhand see no reason not to do what you
> suggest above.
There are two ways in which this could be done.

1. Duplicate the check done in 'builtin/branch.c' in 
'builtin/checkout.c'. This doesn't
     sound good to me.

2. Do the check in 'branch.c::validate_new_branchname' to ensure there's 
no way to
     create a branch with the name of 'HEAD'.

Which one is preferred?

Re: [PATCH v3 1/2 / RFC] builtin/branch: stop supporting the use of --set-upstream option

[Junio C Hamano]

Kaartic Sivaraam <kaarticsivaraam91196@gmail.com> writes:

> 1. Duplicate the check done in 'builtin/branch.c' in
> 'builtin/checkout.c'. This doesn't
>     sound good to me.

Doesn't sound good to me, either.  Some refactoring to make it
easier to reuse it from the new caller would be necessary.

Re: [PATCH v3 1/2 / RFC] builtin/branch: stop supporting the use of --set-upstream option

[Kaartic Sivaraam]

On Wednesday 16 August 2017 12:28 AM, Junio C Hamano wrote:
> Some refactoring to make it easier to reuse it from the new caller 
> would be necessary. 
Sorry but I think I don't get that correctly. What's the "new caller" 
being referred to here?
What should be refactored?

---
Kaartic

Re: [PATCH v3 1/2 / RFC] builtin/branch: stop supporting the use of --set-upstream option

[Junio C Hamano]

Kaartic Sivaraam <kaarticsivaraam91196@gmail.com> writes:

> On Wednesday 16 August 2017 12:28 AM, Junio C Hamano wrote:
>> Some refactoring to make it easier to reuse it from the new caller
>> would be necessary. 
> Sorry but I think I don't get that correctly. What's the "new caller"
> being referred to here?
> What should be refactored?

You said that "checkout" does not do a necessary check that is done
in "branch", so presumably "branch" already has a code to do so that
is not called by the current "checkout", right?  Then you would add
a new caller in "checkout" to trigger the same check that is already
done in "branch", but the code "branch" uses _might_ be too specific
to the kind of data the current implementation of "branch" uses and
it _may_ not be easy to call it directly from "checkout" (I didn't
check if that is the case).  If so, then the check implemented in
the current "branch" may need to be refactored before it can easily
be called from the new caller you would be adding to "checkout".

Re: [PATCH v3 1/2 / RFC] builtin/branch: stop supporting the use of --set-upstream option

[Kaartic Sivaraam]

On Wed, 2017-08-16 at 12:09 -0700, Junio C Hamano wrote:
> You said that "checkout" does not do a necessary check that is done
> in "branch", so presumably "branch" already has a code to do so that
> is not called by the current "checkout", right?  Then you would add
> a new caller in "checkout" to trigger the same check that is already
> done in "branch", but the code "branch" uses _might_ be too specific
> to the kind of data the current implementation of "branch" uses and
> it _may_ not be easy to call it directly from "checkout" (I didn't
> check if that is the case).  If so, then the check implemented in
> the current "branch" may need to be refactored before it can easily
> be called from the new caller you would be adding to "checkout".
> 
> 
Thanks. Now I get it. What about doing that check in
branch.c::create_branch or branch.c::validate_new_branchname? I guess
creating a branch named HEAD isn't that good an idea in any case. Doing
the check there might prevent a similar situation in future, I guess.
Further "branch" and "checkout" do call branch.c::create_branch which
in turn calls branch.c::validate_new_branchname.

-- 
Kaartic

[PATCH v4 1/3] test: cleanup cruft of a test

[Kaartic Sivaraam]

Avoiding the clean up step of tests may help in some cases but in other
cases they cause the other unrelated tests to fail for unobvious reasons.
It's better to cleanup a few things to keep other tests from failing
as a result of it.

So, cleanup a cruft left behind by an old test in order for the changes that
are to be introduced to be independent of it.

Signed-off-by: Kaartic Sivaraam <kaarticsivaraam91196@gmail.com>
---
 This was part of [PATCH v3 1/2] and has been separated as it seemed to be
 a "logically separate" change.

 t/t3200-branch.sh | 1 +
 1 file changed, 1 insertion(+)

diff --git a/t/t3200-branch.sh b/t/t3200-branch.sh
index dd37ac47c..b54b3ebf3 100755
--- a/t/t3200-branch.sh
+++ b/t/t3200-branch.sh
@@ -560,6 +560,7 @@ test_expect_success 'use --set-upstream-to modify HEAD' '
 test_expect_success 'use --set-upstream-to modify a particular branch' '
 	git branch my13 &&
 	git branch --set-upstream-to master my13 &&
+	test_when_finished "git branch --unset-upstream my13" &&
 	test "$(git config branch.my13.remote)" = "." &&
 	test "$(git config branch.my13.merge)" = "refs/heads/master"
 '
-- 
2.14.1.534.g641031ecb

[PATCH v4 2/3] builtin/branch: stop supporting the use of --set-upstream option

[Kaartic Sivaraam]

The '--set-upstream' option of branch was deprecated in,

    b347d06bf branch: deprecate --set-upstream and show help if we
    detect possible mistaken use (Thu, 30 Aug 2012 19:23:13 +0200)

In order to prevent "--set-upstream" on a command line from being taken as
an abbreviated form of "--set-upstream-to", explicitly catch "--set-upstream"
option and die, instead of just removing it from the list of options.

The option is planned to be removed after this change has been around for a few
years.

The before/after behaviour for a simple case follows,

    $ git remote
    origin

Before,

    $ git branch
    * master

    $ git branch --set-upstream origin/master
    The --set-upstream flag is deprecated and will be removed. Consider using --track or --set-upstream-to
    Branch origin/master set up to track local branch master.

    $ echo $?
    0

    $ git branch
    * master
      origin/master

After,

    $ git branch
    * master

    $ git branch --set-upstream origin/master
    fatal: the '--set-upstream' option is no longer supported. Please use '--track' or '--set-upstream-to' instead.

    $ echo $?
    128

    $ git branch
    * master

Helped-by: Martin Ågren <martin.agren@gmail.com>,  Junio C Hamano <gitster@pobox.com>
Signed-off-by: Kaartic Sivaraam <kaarticsivaraam91196@gmail.com>
---
 Changes in v4:

    - made a few changes suggested by Martin
    - hid the '--set-upstream' option from 'git branch -h' as suggested by Junio 
    - updated commit message as suggested by Junio
    - updated error message (this should have been in v3 but somehow got skipped)

 Note: I'm not using the word 'removed' in the error messages or in the documentation as
 I feel it counter-intuitive from the end user's perspective because 

    * 'git branch' still accepts the option in the command line

    *  The option has not yet been removed from the synopsis of the documentation and I think
       we can't remove it from the 'Synopsis' porion of the documentation as it doesn't make
       sense (at least to me) to give a description of an option not listed in the synopsis.
       Moreover, we have to state the reason for not supporting it in some place.

 I guess the phrase 'no longer supported' is equally communicative. Let me know if that was not
 a right decision.

 Documentation/git-branch.txt |  8 ++++----
 builtin/branch.c             | 25 +++--------------------
 t/t3200-branch.sh            | 47 ++------------------------------------------
 t/t6040-tracking-info.sh     | 20 +++++++------------
 4 files changed, 16 insertions(+), 84 deletions(-)

diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt
index 81bd0a7b7..948d9c9ef 100644
--- a/Documentation/git-branch.txt
+++ b/Documentation/git-branch.txt
@@ -195,10 +195,10 @@ start-point is either a local or remote-tracking branch.
 	branch.autoSetupMerge configuration variable is true.
 
 --set-upstream::
-	If specified branch does not exist yet or if `--force` has been
-	given, acts exactly like `--track`. Otherwise sets up configuration
-	like `--track` would when creating the branch, except that where
-	branch points to is not changed.
+	As this option had confusing syntax it's no longer supported. Please use
+	--track or --set-upstream-to instead.
++
+Note: This could possibly become an alias of --set-upstream-to in the future.
 
 -u <upstream>::
 --set-upstream-to=<upstream>::
diff --git a/builtin/branch.c b/builtin/branch.c
index a3bd2262b..6e3ea5787 100644
--- a/builtin/branch.c
+++ b/builtin/branch.c
@@ -557,8 +557,8 @@ int cmd_branch(int argc, const char **argv, const char *prefix)
 		OPT__QUIET(&quiet, N_("suppress informational messages")),
 		OPT_SET_INT('t', "track",  &track, N_("set up tracking mode (see git-pull(1))"),
 			BRANCH_TRACK_EXPLICIT),
-		OPT_SET_INT( 0, "set-upstream",  &track, N_("change upstream info"),
-			BRANCH_TRACK_OVERRIDE),
+		{ OPTION_SET_INT, 0, "set-upstream", &track, NULL, N_("do not use"),
+			PARSE_OPT_NOARG | PARSE_OPT_HIDDEN, NULL, BRANCH_TRACK_OVERRIDE },
 		OPT_STRING('u', "set-upstream-to", &new_upstream, N_("upstream"), N_("change the upstream info")),
 		OPT_BOOL(0, "unset-upstream", &unset_upstream, N_("Unset the upstream info")),
 		OPT__COLOR(&branch_use_color, N_("use colored output")),
@@ -755,8 +755,6 @@ int cmd_branch(int argc, const char **argv, const char *prefix)
 		strbuf_release(&buf);
 	} else if (argc > 0 && argc <= 2) {
 		struct branch *branch = branch_get(argv[0]);
-		int branch_existed = 0, remote_tracking = 0;
-		struct strbuf buf = STRBUF_INIT;
 
 		if (!strcmp(argv[0], "HEAD"))
 			die(_("it does not make sense to create 'HEAD' manually"));
@@ -768,28 +766,11 @@ int cmd_branch(int argc, const char **argv, const char *prefix)
 			die(_("-a and -r options to 'git branch' do not make sense with a branch name"));
 
 		if (track == BRANCH_TRACK_OVERRIDE)
-			fprintf(stderr, _("The --set-upstream flag is deprecated and will be removed. Consider using --track or --set-upstream-to\n"));
+			die(_("the '--set-upstream' option is no longer supported. Please use '--track' or '--set-upstream-to' instead."));
 
-		strbuf_addf(&buf, "refs/remotes/%s", branch->name);
-		remote_tracking = ref_exists(buf.buf);
-		strbuf_release(&buf);
-
-		branch_existed = ref_exists(branch->refname);
 		create_branch(argv[0], (argc == 2) ? argv[1] : head,
 			      force, reflog, 0, quiet, track);
 
-		/*
-		 * We only show the instructions if the user gave us
-		 * one branch which doesn't exist locally, but is the
-		 * name of a remote-tracking branch.
-		 */
-		if (argc == 1 && track == BRANCH_TRACK_OVERRIDE &&
-		    !branch_existed && remote_tracking) {
-			fprintf(stderr, _("\nIf you wanted to make '%s' track '%s', do this:\n\n"), head, branch->name);
-			fprintf(stderr, "    git branch -d %s\n", branch->name);
-			fprintf(stderr, "    git branch --set-upstream-to %s\n", branch->name);
-		}
-
 	} else
 		usage_with_options(builtin_branch_usage, options);
 
diff --git a/t/t3200-branch.sh b/t/t3200-branch.sh
index b54b3ebf3..34f556998 100755
--- a/t/t3200-branch.sh
+++ b/t/t3200-branch.sh
@@ -606,38 +606,8 @@ test_expect_success 'test --unset-upstream on a particular branch' '
 	test_must_fail git config branch.my14.merge
 '
 
-test_expect_success '--set-upstream shows message when creating a new branch that exists as remote-tracking' '
-	git update-ref refs/remotes/origin/master HEAD &&
-	git branch --set-upstream origin/master 2>actual &&
-	test_when_finished git update-ref -d refs/remotes/origin/master &&
-	test_when_finished git branch -d origin/master &&
-	cat >expected <<EOF &&
-The --set-upstream flag is deprecated and will be removed. Consider using --track or --set-upstream-to
-
-If you wanted to make '"'master'"' track '"'origin/master'"', do this:
-
-    git branch -d origin/master
-    git branch --set-upstream-to origin/master
-EOF
-	test_i18ncmp expected actual
-'
-
-test_expect_success '--set-upstream with two args only shows the deprecation message' '
-	git branch --set-upstream master my13 2>actual &&
-	test_when_finished git branch --unset-upstream master &&
-	cat >expected <<EOF &&
-The --set-upstream flag is deprecated and will be removed. Consider using --track or --set-upstream-to
-EOF
-	test_i18ncmp expected actual
-'
-
-test_expect_success '--set-upstream with one arg only shows the deprecation message if the branch existed' '
-	git branch --set-upstream my13 2>actual &&
-	test_when_finished git branch --unset-upstream my13 &&
-	cat >expected <<EOF &&
-The --set-upstream flag is deprecated and will be removed. Consider using --track or --set-upstream-to
-EOF
-	test_i18ncmp expected actual
+test_expect_success '--set-upstream fails' '
+    test_must_fail git branch --set-upstream origin/master
 '
 
 test_expect_success '--set-upstream-to notices an error to set branch as own upstream' '
@@ -962,19 +932,6 @@ test_expect_success 'attempt to delete a branch merged to its base' '
 	test_must_fail git branch -d my10
 '
 
-test_expect_success 'use set-upstream on the current branch' '
-	git checkout master &&
-	git --bare init myupstream.git &&
-	git push myupstream.git master:refs/heads/frotz &&
-	git remote add origin myupstream.git &&
-	git fetch &&
-	git branch --set-upstream master origin/frotz &&
-
-	test "z$(git config branch.master.remote)" = "zorigin" &&
-	test "z$(git config branch.master.merge)" = "zrefs/heads/frotz"
-
-'
-
 test_expect_success 'use --edit-description' '
 	write_script editor <<-\EOF &&
 		echo "New contents" >"$1"
diff --git a/t/t6040-tracking-info.sh b/t/t6040-tracking-info.sh
index 97a07655a..be78cc4fa 100755
--- a/t/t6040-tracking-info.sh
+++ b/t/t6040-tracking-info.sh
@@ -188,35 +188,29 @@ test_expect_success 'fail to track annotated tags' '
 	test_must_fail git checkout heavytrack
 '
 
-test_expect_success 'setup tracking with branch --set-upstream on existing branch' '
+test_expect_success '--set-upstream-to does not change branch' '
 	git branch from-master master &&
-	test_must_fail git config branch.from-master.merge > actual &&
-	git branch --set-upstream from-master master &&
-	git config branch.from-master.merge > actual &&
-	grep -q "^refs/heads/master$" actual
-'
-
-test_expect_success '--set-upstream does not change branch' '
+	git branch --set-upstream-to master from-master &&
 	git branch from-master2 master &&
 	test_must_fail git config branch.from-master2.merge > actual &&
 	git rev-list from-master2 &&
 	git update-ref refs/heads/from-master2 from-master2^ &&
 	git rev-parse from-master2 >expect2 &&
-	git branch --set-upstream from-master2 master &&
+	git branch --set-upstream-to master from-master2 &&
 	git config branch.from-master.merge > actual &&
 	git rev-parse from-master2 >actual2 &&
 	grep -q "^refs/heads/master$" actual &&
 	cmp expect2 actual2
 '
 
-test_expect_success '--set-upstream @{-1}' '
-	git checkout from-master &&
+test_expect_success '--set-upstream-to @{-1}' '
+	git checkout follower &&
 	git checkout from-master2 &&
 	git config branch.from-master2.merge > expect2 &&
-	git branch --set-upstream @{-1} follower &&
+	git branch --set-upstream-to @{-1} from-master &&
 	git config branch.from-master.merge > actual &&
 	git config branch.from-master2.merge > actual2 &&
-	git branch --set-upstream from-master follower &&
+	git branch --set-upstream-to follower from-master &&
 	git config branch.from-master.merge > expect &&
 	test_cmp expect2 actual2 &&
 	test_cmp expect actual
-- 
2.14.0.rc1.434.g6eded367a

[PATCH v4 3/3] branch: quote branch/ref names to improve readability

[Kaartic Sivaraam]

Signed-off-by: Kaartic Sivaraam <kaarticsivaraam91196@gmail.com>
---
 No changes in this one. Sending this just because of the change in the total number
 of commits.

 branch.c | 16 ++++++++--------
 1 file changed, 8 insertions(+), 8 deletions(-)

diff --git a/branch.c b/branch.c
index ad5a2299b..a40721f3c 100644
--- a/branch.c
+++ b/branch.c
@@ -90,24 +90,24 @@ int install_branch_config(int flag, const char *local, const char *origin, const
 		if (shortname) {
 			if (origin)
 				printf_ln(rebasing ?
-					  _("Branch %s set up to track remote branch %s from %s by rebasing.") :
-					  _("Branch %s set up to track remote branch %s from %s."),
+					  _("Branch '%s' set up to track remote branch '%s' from '%s' by rebasing.") :
+					  _("Branch '%s' set up to track remote branch '%s' from '%s'."),
 					  local, shortname, origin);
 			else
 				printf_ln(rebasing ?
-					  _("Branch %s set up to track local branch %s by rebasing.") :
-					  _("Branch %s set up to track local branch %s."),
+					  _("Branch '%s' set up to track local branch '%s' by rebasing.") :
+					  _("Branch '%s' set up to track local branch '%s'."),
 					  local, shortname);
 		} else {
 			if (origin)
 				printf_ln(rebasing ?
-					  _("Branch %s set up to track remote ref %s by rebasing.") :
-					  _("Branch %s set up to track remote ref %s."),
+					  _("Branch '%s' set up to track remote ref '%s' by rebasing.") :
+					  _("Branch '%s' set up to track remote ref '%s'."),
 					  local, remote);
 			else
 				printf_ln(rebasing ?
-					  _("Branch %s set up to track local ref %s by rebasing.") :
-					  _("Branch %s set up to track local ref %s."),
+					  _("Branch '%s' set up to track local ref '%s' by rebasing.") :
+					  _("Branch '%s' set up to track local ref '%s'."),
 					  local, remote);
 		}
 	}
-- 
2.14.1.534.g641031ecb

Re: [PATCH v4 2/3] builtin/branch: stop supporting the use of --set-upstream option

[Martin Ågren]

On 17 August 2017 at 04:54, Kaartic Sivaraam
<kaarticsivaraam91196@gmail.com> wrote:
> Helped-by: Martin Ågren <martin.agren@gmail.com>,  Junio C Hamano <gitster@pobox.com>
> Signed-off-by: Kaartic Sivaraam <kaarticsivaraam91196@gmail.com>

I didn't expect a "Helped-by", all I did was to give some random
comments. :-) I'm not so sure about the comma-separation, that seems to
be a first in the project.

>     *  The option has not yet been removed from the synopsis of the documentation and I think
>        we can't remove it from the 'Synopsis' porion of the documentation as it doesn't make
>        sense (at least to me) to give a description of an option not listed in the synopsis.

The "git interpret-trailers --parse" thread nearby is adding some
options without mentioning them in the synopsis [1], and those options
can actually be useful, whereas "--set-upstream" only results in a fatal
error. So I don't know.

>        Moreover, we have to state the reason for not supporting it in some place.
>
>  I guess the phrase 'no longer supported' is equally communicative. Let me know if that was not
>  a right decision.

I think it's ok. Of course, I know exactly what you want to say, and
why, so I'm biased. :-)

[1] https://public-inbox.org/git/20170815102334.qc4w7akl44bti44x@sigill.intra.peff.net/

Re: [PATCH v4 2/3] builtin/branch: stop supporting the use of --set-upstream option

[Junio C Hamano]

Martin Ågren <martin.agren@gmail.com> writes:

> On 17 August 2017 at 04:54, Kaartic Sivaraam
> <kaarticsivaraam91196@gmail.com> wrote:
>> Helped-by: Martin Ågren <martin.agren@gmail.com>,  Junio C Hamano <gitster@pobox.com>
>> Signed-off-by: Kaartic Sivaraam <kaarticsivaraam91196@gmail.com>
>
> I didn't expect a "Helped-by", all I did was to give some random
> comments. :-) I'm not so sure about the comma-separation, that seems to
> be a first in the project.

I didn't either ;-) 

The line looks odd so I'll remove it while queuing.

Thanks for noticing.

Re: [PATCH v4 2/3] builtin/branch: stop supporting the use of --set-upstream option

[Junio C Hamano]

Kaartic Sivaraam <kaarticsivaraam91196@gmail.com> writes:

> diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt
> index 81bd0a7b7..948d9c9ef 100644
> --- a/Documentation/git-branch.txt
> +++ b/Documentation/git-branch.txt
> @@ -195,10 +195,10 @@ start-point is either a local or remote-tracking branch.
>  	branch.autoSetupMerge configuration variable is true.
>  
>  --set-upstream::
> -	If specified branch does not exist yet or if `--force` has been
> -	given, acts exactly like `--track`. Otherwise sets up configuration
> -	like `--track` would when creating the branch, except that where
> -	branch points to is not changed.
> +	As this option had confusing syntax it's no longer supported. Please use
> +	--track or --set-upstream-to instead.
> ++
> +Note: This could possibly become an alias of --set-upstream-to in the future.

I'll tweak `--track` and `--set-upstream-to` in the updated text
and remove the 'Note:' thing that does not give any useful
information to the end users while queuing (no need to resend). 

Thanks.

Re: [PATCH v4 2/3] builtin/branch: stop supporting the use of --set-upstream option

[Kaartic Sivaraam]

On Friday 18 August 2017 01:28 AM, Junio C Hamano wrote:
> Kaartic Sivaraam <kaarticsivaraam91196@gmail.com> writes:
>
>> diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt
>> index 81bd0a7b7..948d9c9ef 100644
>> --- a/Documentation/git-branch.txt
>> +++ b/Documentation/git-branch.txt
>> @@ -195,10 +195,10 @@ start-point is either a local or remote-tracking branch.
>>   	branch.autoSetupMerge configuration variable is true.
>>   
>>   --set-upstream::
>> -	If specified branch does not exist yet or if `--force` has been
>> -	given, acts exactly like `--track`. Otherwise sets up configuration
>> -	like `--track` would when creating the branch, except that where
>> -	branch points to is not changed.
>> +	As this option had confusing syntax it's no longer supported. Please use
>> +	--track or --set-upstream-to instead.
>> ++
>> +Note: This could possibly become an alias of --set-upstream-to in the future.
> I'll tweak `--track` and `--set-upstream-to` in the updated text
> and remove the 'Note:' thing that does not give any useful
> information to the end users while queuing (no need to resend).
I thought I explained the reason for adding the note in one of the 
previous mails.
Here's the portion of the mail,

On Monday 14 August 2017 02:20 PM, Kaartic Sivaraam wrote:
 >
 > On Wednesday 09 August 2017 12:03 AM, Martin Ågren wrote:
 >>
 >> Maybe the final note could be removed? Someone who is looking up
 >> --set-upstream because Git just "crashed" on them will only want to know
 >> what they should do instead. Our thoughts about the future are perhaps
 >> not that interesting.
 >
 > I thought it's better to document it to avoid people from getting 
surprised
 > when the options *starts working* again.
 >

I hope that explains the reason.

---
Kaartic

Re: [PATCH v4 2/3] builtin/branch: stop supporting the use of --set-upstream option

[Kaartic Sivaraam]

On Friday 18 August 2017 01:25 AM, Junio C Hamano wrote:
> Martin Ågren <martin.agren@gmail.com> writes:
>
>> On 17 August 2017 at 04:54, Kaartic Sivaraam
>> <kaarticsivaraam91196@gmail.com> wrote:
>>> Helped-by: Martin Ågren <martin.agren@gmail.com>,  Junio C Hamano <gitster@pobox.com>
>>> Signed-off-by: Kaartic Sivaraam <kaarticsivaraam91196@gmail.com>
>> I didn't expect a "Helped-by", all I did was to give some random
>> comments. :-) I'm not so sure about the comma-separation, that seems to
>> be a first in the project.
> I didn't either ;-)
>
> The line looks odd so I'll remove it while queuing.
>
> Thanks for noticing.
I should have been better with my wordings :) How about converting that
line into two 'Suggestions-by:' or 'Reviewed-by:' ?


---
Kaartic

Re: [PATCH v4 2/3] builtin/branch: stop supporting the use of --set-upstream option

[Junio C Hamano]

Kaartic Sivaraam <kaarticsivaraam91196@gmail.com> writes:

> On Friday 18 August 2017 01:25 AM, Junio C Hamano wrote:
>> Martin Ågren <martin.agren@gmail.com> writes:
>>
>>> On 17 August 2017 at 04:54, Kaartic Sivaraam
>>> <kaarticsivaraam91196@gmail.com> wrote:
>>>> Helped-by: Martin Ågren <martin.agren@gmail.com>,  Junio C Hamano <gitster@pobox.com>
>>>> Signed-off-by: Kaartic Sivaraam <kaarticsivaraam91196@gmail.com>
>>> I didn't expect a "Helped-by", all I did was to give some random
>>> comments. :-) I'm not so sure about the comma-separation, that seems to
>>> be a first in the project.
>> I didn't either ;-)
>>
>> The line looks odd so I'll remove it while queuing.
>>
>> Thanks for noticing.
> I should have been better with my wordings :) How about converting that
> line into two 'Suggestions-by:' or 'Reviewed-by:' ?

I personally do not think either is needed for those small things we
saw in the discussion.

Unless Martin feels strongly about it, that is.

Thanks.

Re: [PATCH v4 2/3] builtin/branch: stop supporting the use of --set-upstream option

[Junio C Hamano]

Kaartic Sivaraam <kaarticsivaraam91196@gmail.com> writes:

> On Monday 14 August 2017 02:20 PM, Kaartic Sivaraam wrote:
>>
>> On Wednesday 09 August 2017 12:03 AM, Martin Ågren wrote:
>>>
>>> Maybe the final note could be removed? Someone who is looking up
>>> --set-upstream because Git just "crashed" on them will only want to know
>>> what they should do instead. Our thoughts about the future are perhaps
>>> not that interesting.
>>
>> I thought it's better to document it to avoid people from getting 
> surprised
>> when the options *starts working* again.
>
> I hope that explains the reason.

That is something we can say we _actually_ repurpose the option.
Until then, it is merely noise that distracts the users.

Re: [PATCH v4 2/3] builtin/branch: stop supporting the use of --set-upstream option

[Martin Ågren]

On 18 August 2017 at 18:30, Junio C Hamano <gitster@pobox.com> wrote:
> Kaartic Sivaraam <kaarticsivaraam91196@gmail.com> writes:
>
>> On Friday 18 August 2017 01:25 AM, Junio C Hamano wrote:
>>> Martin Ågren <martin.agren@gmail.com> writes:
>>>
>>>> On 17 August 2017 at 04:54, Kaartic Sivaraam
>>>> <kaarticsivaraam91196@gmail.com> wrote:
>>>>> Helped-by: Martin Ågren <martin.agren@gmail.com>,  Junio C Hamano <gitster@pobox.com>
>>>>> Signed-off-by: Kaartic Sivaraam <kaarticsivaraam91196@gmail.com>
>>>> I didn't expect a "Helped-by", all I did was to give some random
>>>> comments. :-) I'm not so sure about the comma-separation, that seems to
>>>> be a first in the project.
>>> I didn't either ;-)
>>>
>>> The line looks odd so I'll remove it while queuing.
>>>
>>> Thanks for noticing.
>> I should have been better with my wordings :) How about converting that
>> line into two 'Suggestions-by:' or 'Reviewed-by:' ?
>
> I personally do not think either is needed for those small things we
> saw in the discussion.
>
> Unless Martin feels strongly about it, that is.

No, no strong feelings. Thanks.

Re: [PATCH v3 1/2 / RFC] builtin/branch: stop supporting the use of --set-upstream option

[Junio C Hamano]

Kaartic Sivaraam <kaarticsivaraam91196@gmail.com> writes:

> On Wed, 2017-08-16 at 12:09 -0700, Junio C Hamano wrote:
>> You said that "checkout" does not do a necessary check that is done
>> in "branch", so presumably "branch" already has a code to do so that
>> is not called by the current "checkout", right?  Then you would add
>> a new caller in "checkout" to trigger the same check that is already
>> done in "branch", but the code "branch" uses _might_ be too specific
>> to the kind of data the current implementation of "branch" uses and
>> it _may_ not be easy to call it directly from "checkout" (I didn't
>> check if that is the case).  If so, then the check implemented in
>> the current "branch" may need to be refactored before it can easily
>> be called from the new caller you would be adding to "checkout".
>> 
>> 
> Thanks. Now I get it. What about doing that check in
> branch.c::create_branch or branch.c::validate_new_branchname? I guess
> creating a branch named HEAD isn't that good an idea in any case. Doing
> the check there might prevent a similar situation in future, I guess.
> Further "branch" and "checkout" do call branch.c::create_branch which
> in turn calls branch.c::validate_new_branchname.

The above analysis sounds sensible, so it appears that you already
found a function that is shared in the two codepaths, and have a
good plan to make them consistent?

I was sweeping my mailbox to collect loose ends that haven't been
tied down, and noticed that this topic does not seem to reach a
conclusion.  Do we want to reboot the effort?  Or should we just
throw it in the #leftoverbits bin for now?

Thanks.

Re: [PATCH v3 1/2 / RFC] builtin/branch: stop supporting the use of --set-upstream option

[Kaartic Sivaraam]

On Tue, 2017-09-12 at 15:49 +0900, Junio C Hamano wrote:
> Kaartic Sivaraam <kaarticsivaraam91196@gmail.com> writes:
> 
> > Thanks. Now I get it. What about doing that check in
> > branch.c::create_branch or branch.c::validate_new_branchname? I guess
> > creating a branch named HEAD isn't that good an idea in any case. Doing
> > the check there might prevent a similar situation in future, I guess.
> > Further "branch" and "checkout" do call branch.c::create_branch which
> > in turn calls branch.c::validate_new_branchname.
> 
> The above analysis sounds sensible, so it appears that you already
> found a function that is shared in the two codepaths, and have a
> good plan to make them consistent?
> 

Yes, I was just waiting for this reply. In the mean time I thought of
sending a patch for this but was procrastinating as I felt a little
lazy.

> I was sweeping my mailbox to collect loose ends that haven't been
> tied down, and noticed that this topic does not seem to reach a
> conclusion.  Do we want to reboot the effort?  Or should we just
> throw it in the #leftoverbits bin for now?
> 

Don't worry I'll send a patch for this, soon. I mean it :)

-- 
Kaartic

[PATCH/RFC] branch: strictly don't allow a branch with name 'HEAD'

[Kaartic Sivaraam]

Allowing a branch with a name 'HEAD' could trigger ambiguity. We could
avoid this by checking for it manually. Moreover this has been done
partially in 8efb8899c ("branch: segfault fixes and validation", 2013-02-23)
There was still a way to create a branch with name 'HEAD' by using

    $ git checkout -b HEAD

Avoid such loop holes by 'strictly' checking for a branch with name HEAD.
The check is referred to as strict because it's done in a place which is
supposed to be called to ensure that a new branch name is a valid one.

Signed-off-by: Kaartic Sivaraam <kaarticsivaraam91196@gmail.com>
---
 branch.c         | 3 +++
 builtin/branch.c | 3 ---
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/branch.c b/branch.c
index 36541d05c..ea1050649 100644
--- a/branch.c
+++ b/branch.c
@@ -184,6 +184,9 @@ int validate_new_branchname(const char *name, struct strbuf *ref,
 	if (strbuf_check_branch_ref(ref, name))
 		die(_("'%s' is not a valid branch name."), name);
 
+	if (!strcmp(name, "HEAD"))
+		die(_("it does not make sense to create 'HEAD' manually"));
+
 	if (!ref_exists(ref->buf))
 		return 0;
 	else if (!force && !attr_only)
diff --git a/builtin/branch.c b/builtin/branch.c
index 16d391b40..c86348d4c 100644
--- a/builtin/branch.c
+++ b/builtin/branch.c
@@ -762,9 +762,6 @@ int cmd_branch(int argc, const char **argv, const char *prefix)
 		int branch_existed = 0, remote_tracking = 0;
 		struct strbuf buf = STRBUF_INIT;
 
-		if (!strcmp(argv[0], "HEAD"))
-			die(_("it does not make sense to create 'HEAD' manually"));
-
 		if (!branch)
 			die(_("no such branch '%s'"), argv[0]);
 
-- 
2.14.1.1006.g90ad9a07c

[RFC PATCH 0/5] branch: improve error messages of branch renaming

[Kaartic Sivaraam]

In builtin/branch, the error messages weren't handled directly by the branch
renaming function and was left to the other function. Though this avoids
redundancy this gave unclear error messages in some cases. So, make builtin/branch
give more useful error messages.

The first two patches are preparatory/cleanup patches.

The third patch refactors a function to make it more usable/understandable(?).
This results only in one functional change as noted there. I've tried my best not
to screw anything up as a consequence of that refactor[note 1]. In case I missed
something, let me know.

The fourth patch introduces part of the logic needed to improve error messages.
It's kept separate to keep things reviewable.

The fifth patch is the main one which does the improvement of error messages.

These patches apply on top of 'master' and be found in my fork[2].

Note:

[1]: The Travis CI build did succeed but I don't think we can rely on that a lot
because the test aren't exhaustive (I guess).
https://travis-ci.org/sivaraam/git/builds/277146416

[2]: https://github.com/sivaraam/git/tree/work/branch-move-revamp

Kaartic Sivaraam (5):
  builtin/checkout: avoid usage of  '!!' for expressions
  branch: document the usage of certain parameters
  branch: cleanup branch name validation
  branch: introduce dont_fail parameter for update validation
  builtin/branch: give more useful error messages when renaming

 branch.c           | 67 +++++++++++++++++++++++++++++++++++++++---------------
 branch.h           | 44 +++++++++++++++++++++++++----------
 builtin/branch.c   | 48 +++++++++++++++++++++++++++++++++-----
 builtin/checkout.c |  7 +++---
 t/t3200-branch.sh  |  4 ++++
 5 files changed, 130 insertions(+), 40 deletions(-)

-- 
2.14.1.868.g66c78774b

[RFC PATCH 1/5] builtin/checkout: avoid usage of '!!'

[Kaartic Sivaraam]

Documentation/CodingGuidelines says,

    "Some clever tricks, like using the !! operator with arithmetic
     constructs, can be extremely confusing to others.  Avoid them,
     unless there is a compelling reason to use them."

There was a usage for which there's no compelling reason.So, replace
such a usage as with something else that expresses the intent more
clearly.

Signed-off-by: Kaartic Sivaraam <kaarticsivaraam91196@gmail.com>
---
 I think the expression,

    !!opts.new_branch_force

 is equivalent to,

    opts.new_branch_force != NULL

 in all cases. If it's not, let me know.

 builtin/checkout.c | 7 +++----
 1 file changed, 3 insertions(+), 4 deletions(-)

diff --git a/builtin/checkout.c b/builtin/checkout.c
index 5c202b7af..76859da9d 100644
--- a/builtin/checkout.c
+++ b/builtin/checkout.c
@@ -1281,11 +1281,10 @@ int cmd_checkout(int argc, const char **argv, const char *prefix)
 
 	if (opts.new_branch) {
 		struct strbuf buf = STRBUF_INIT;
+		int force = opts.new_branch_force != NULL;
 
-		opts.branch_exists =
-			validate_new_branchname(opts.new_branch, &buf,
-						!!opts.new_branch_force,
-						!!opts.new_branch_force);
+		opts.branch_exists = validate_new_branchname(opts.new_branch, &buf,
+							     force, force);
 
 		strbuf_release(&buf);
 	}
-- 
2.14.1.868.g66c78774b

[RFC PATCH 2/5] branch: document the usage of certain parameters

[Kaartic Sivaraam]

Documentation for a certain function was incomplete as it didn't say
what certain parameters were used for.

So, document them for the sake of completeness and easy reference.

Signed-off-by: Kaartic Sivaraam <kaarticsivaraam91196@gmail.com>
---
 branch.h | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/branch.h b/branch.h
index b07788558..33b7f5d88 100644
--- a/branch.h
+++ b/branch.h
@@ -15,6 +15,11 @@
  *
  *   - reflog creates a reflog for the branch
  *
+ *   - if 'force' is true, clobber_head indicates whether the branch could be
+ *     the current branch; else it has no effect
+ *
+ *   - quiet suppresses tracking information
+ *
  *   - track causes the new branch to be configured to merge the remote branch
  *     that start_name is a tracking branch for (if any).
  */
-- 
2.14.1.1006.g90ad9a07c

[RFC PATCH 3/5] branch: cleanup branch name validation

[Kaartic Sivaraam]

The function that validates a new branch name was clumsy because,

  1. It did more than just validating the branch name

  2. Despite it's name, it is more often than not used to validate
     existing branch names through the 'force' and 'attr_only'
     parameters (whose names by the way weren't communicative).

  3. The 'attr_only' parameter should have been "true" only when
     callers like to update some attribute of the branch and "false"
     when they were updating where the branch points to. It was misused
     by callers by setting it to "true" (to skip tests) even though they
     were force updating where the current branch was pointing to!

     This is an example of spoiling code clarity by making the caller
     rely on how the function is implemented thus making it hard to
     modify/maintain.

This makes it unclear what the function does at all and would confuse
the people who would ever want to it for the first time.

So, refactor it into a function that validates whether the branch could
be updated. This doesn't bear the uncommunicative 'new'. Further replace
the 'force' parameter with a 'could_exist' parameter which specifies
whether the given branch name could exist or not (it's just a better name
for 'force'). Also replace  the 'attr_only' with 'clobber_head' which is
a more communicative way of seeing "If the branch could exist, it's OK if
it is the current branch".

Separate the validation of an existing branch into another function.
This (at last!) addresses the NEEDSWORK that was added in fa7993767
(branch --set-upstream: regression fix, 2011-09-16)

This refactor has only one functional change. It enforces strictly that
an existing branch should be updated only with the 'force' switch. So,
it's no more possible to do,

        $ git branch -m master master

(which doesn't seem that useful). This strongly enforces the following
statement of the 'git branch' documentation,

        "If <newbranch> exists, -M must be used to force the
         rename to happen."

Signed-off-by: Kaartic Sivaraam <kaarticsivaraam91196@gmail.com>
---
 branch.c           | 41 ++++++++++++++++++++++++++++++-----------
 branch.h           | 20 ++++++++------------
 builtin/branch.c   |  2 +-
 builtin/checkout.c |  4 ++--
 t/t3200-branch.sh  |  4 ++++
 5 files changed, 45 insertions(+), 26 deletions(-)

diff --git a/branch.c b/branch.c
index 703ded69c..2020dedf6 100644
--- a/branch.c
+++ b/branch.c
@@ -178,18 +178,19 @@ int read_branch_desc(struct strbuf *buf, const char *branch_name)
 	return 0;
 }
 
-int validate_new_branchname(const char *name, struct strbuf *ref,
-			    int force, int attr_only)
+int validate_branch_update(const char *name, struct strbuf *ref,
+			   int could_exist, int clobber_head)
 {
 	if (strbuf_check_branch_ref(ref, name))
 		die(_("'%s' is not a valid branch name."), name);
 
 	if (!ref_exists(ref->buf))
 		return 0;
-	else if (!force && !attr_only)
+
+	if (!could_exist)
 		die(_("A branch named '%s' already exists."), ref->buf + strlen("refs/heads/"));
 
-	if (!attr_only) {
+	if (!clobber_head) {
 		const char *head;
 		struct object_id oid;
 
@@ -197,9 +198,29 @@ int validate_new_branchname(const char *name, struct strbuf *ref,
 		if (!is_bare_repository() && head && !strcmp(head, ref->buf))
 			die(_("Cannot force update the current branch."));
 	}
+
 	return 1;
 }
 
+/*
+ * Validates whether the branch with the given name exists, returning the
+ * interpreted ref in ref.
+ *
+ * This method is invoked if the caller merely wants to know if it is OK
+ * to change some attribute for the named branch (e.g. tracking upstream).
+ *
+ */
+static void validate_existing_branch(const char *name, struct strbuf *ref)
+{
+	if (strbuf_check_branch_ref(ref, name))
+		die(_("'%s' is not a valid branch name."), name);
+
+	if (ref_exists(ref->buf))
+		return;
+	else
+		die(_("branch '%s' doesn't exist"), name);
+}
+
 static int check_tracking_branch(struct remote *remote, void *cb_data)
 {
 	char *tracking_branch = cb_data;
@@ -243,13 +264,11 @@ void create_branch(const char *name, const char *start_name,
 	if (track == BRANCH_TRACK_EXPLICIT || track == BRANCH_TRACK_OVERRIDE)
 		explicit_tracking = 1;
 
-	if (validate_new_branchname(name, &ref, force,
-				    track == BRANCH_TRACK_OVERRIDE ||
-				    clobber_head)) {
-		if (!force)
-			dont_change_ref = 1;
-		else
-			forcing = 1;
+	if (track == BRANCH_TRACK_OVERRIDE) {
+		validate_existing_branch(name, &ref);
+		dont_change_ref = 1;
+	} else {
+		forcing = validate_branch_update(name, &ref, force, clobber_head);
 	}
 
 	real_ref = NULL;
diff --git a/branch.h b/branch.h
index 33b7f5d88..b4bfff84a 100644
--- a/branch.h
+++ b/branch.h
@@ -28,22 +28,18 @@ void create_branch(const char *name, const char *start_name,
 		   int clobber_head, int quiet, enum branch_track track);
 
 /*
- * Validates that the requested branch may be created, returning the
- * interpreted ref in ref, force indicates whether (non-head) branches
- * may be overwritten. A non-zero return value indicates that the force
- * parameter was non-zero and the branch already exists.
+ * Validates whether the branch with the given name may be updated (created, renamed etc.,)
+ * with respect to the given conditions. It returns the interpreted ref in ref.
  *
- * Contrary to all of the above, when attr_only is 1, the caller is
- * not interested in verifying if it is Ok to update the named
- * branch to point at a potentially different commit. It is merely
- * asking if it is OK to change some attribute for the named branch
- * (e.g. tracking upstream).
+ * could_exist indicates whether the branch could exist or not.
  *
- * NEEDSWORK: This needs to be split into two separate functions in the
- * longer run for sanity.
+ * if 'could_exist' is true, clobber_head indicates whether the branch could be the
+ * current branch; else it has no effect.
+ *
+ * A non-zero return value indicates that a branch already exists and can be force updated.
  *
  */
-int validate_new_branchname(const char *name, struct strbuf *ref, int force, int attr_only);
+int validate_branch_update(const char *name, struct strbuf *ref, int could_exist, int clobber_head);
 
 /*
  * Remove information about the state of working on the current
diff --git a/builtin/branch.c b/builtin/branch.c
index 355f9ef5d..27ddcad97 100644
--- a/builtin/branch.c
+++ b/builtin/branch.c
@@ -483,7 +483,7 @@ static void rename_branch(const char *oldname, const char *newname, int force)
 	 */
 	clobber_head_ok = !strcmp(oldname, newname);
 
-	validate_new_branchname(newname, &newref, force, clobber_head_ok);
+	validate_branch_update(newname, &newref, force, clobber_head_ok);
 
 	reject_rebase_or_bisect_branch(oldref.buf);
 
diff --git a/builtin/checkout.c b/builtin/checkout.c
index 76859da9d..2e870ab4b 100644
--- a/builtin/checkout.c
+++ b/builtin/checkout.c
@@ -1283,8 +1283,8 @@ int cmd_checkout(int argc, const char **argv, const char *prefix)
 		struct strbuf buf = STRBUF_INIT;
 		int force = opts.new_branch_force != NULL;
 
-		opts.branch_exists = validate_new_branchname(opts.new_branch, &buf,
-							     force, force);
+		opts.branch_exists = validate_branch_update(opts.new_branch, &buf,
+							    force, force);
 
 		strbuf_release(&buf);
 	}
diff --git a/t/t3200-branch.sh b/t/t3200-branch.sh
index d97164997..ec85cd959 100755
--- a/t/t3200-branch.sh
+++ b/t/t3200-branch.sh
@@ -137,6 +137,10 @@ test_expect_success 'git branch -m -f o/q o/p should work when o/p exists' '
 	git branch -m -f o/q o/p
 '
 
+test_expect_success 'git branch -m o/o o/o should fail when o/o exists' '
+	test_must_fail git branch -m o/o o/o
+'
+
 test_expect_success 'git branch -m q r/q should fail when r exists' '
 	git branch q &&
 	git branch r &&
-- 
2.14.1.1006.g90ad9a07c

[RFC PATCH 4/5] branch: introduce dont_fail parameter for update validation

[Kaartic Sivaraam]

This parameter allows the branch update validation function to
optionally return a flag specifying the reason for failure, when
requested. This allows the caller to know why it was about to die.
This allows more useful error messages to be given to the user when
trying to rename a branch.

The flags are specified in the form of an enum and values for success
flags have been assigned explicitly to clearly express that certain
callers rely those values and they cannot be arbitrary.

Only the logic has been added but no caller has been made to use it, yet.
So, no functional changes.

Signed-off-by: Kaartic Sivaraam <kaarticsivaraam91196@gmail.com>
---
 branch.c           | 34 +++++++++++++++++++++++-----------
 branch.h           | 23 +++++++++++++++++++++--
 builtin/branch.c   |  2 +-
 builtin/checkout.c |  2 +-
 4 files changed, 46 insertions(+), 15 deletions(-)

diff --git a/branch.c b/branch.c
index 2020dedf6..9dda336a0 100644
--- a/branch.c
+++ b/branch.c
@@ -178,28 +178,40 @@ int read_branch_desc(struct strbuf *buf, const char *branch_name)
 	return 0;
 }
 
-int validate_branch_update(const char *name, struct strbuf *ref,
-			   int could_exist, int clobber_head)
+int validate_branch_update(const char *name, struct strbuf *ref, int could_exist,
+			   int clobber_head, unsigned dont_fail)
 {
-	if (strbuf_check_branch_ref(ref, name))
-		die(_("'%s' is not a valid branch name."), name);
+	if (strbuf_check_branch_ref(ref, name)) {
+		if (dont_fail)
+			return INVALID_BRANCH_NAME;
+		else
+			die(_("'%s' is not a valid branch name."), name);
+	}
 
 	if (!ref_exists(ref->buf))
-		return 0;
+		return VALID_BRANCH_NAME;
 
-	if (!could_exist)
-		die(_("A branch named '%s' already exists."), ref->buf + strlen("refs/heads/"));
+	if (!could_exist) {
+		if (dont_fail)
+			return BRANCH_EXISTS;
+		else
+			die(_("A branch named '%s' already exists."), ref->buf + strlen("refs/heads/"));
+	}
 
 	if (!clobber_head) {
 		const char *head;
 		struct object_id oid;
 
 		head = resolve_ref_unsafe("HEAD", 0, oid.hash, NULL);
-		if (!is_bare_repository() && head && !strcmp(head, ref->buf))
-			die(_("Cannot force update the current branch."));
+		if (!is_bare_repository() && head && !strcmp(head, ref->buf)) {
+			if (dont_fail)
+				return CANNOT_FORCE_UPDATE_CURRENT_BRANCH;
+			else
+				die(_("Cannot force update the current branch."));
+		}
 	}
 
-	return 1;
+	return FORCE_UPDATING_BRANCH;
 }
 
 /*
@@ -268,7 +280,7 @@ void create_branch(const char *name, const char *start_name,
 		validate_existing_branch(name, &ref);
 		dont_change_ref = 1;
 	} else {
-		forcing = validate_branch_update(name, &ref, force, clobber_head);
+		forcing = validate_branch_update(name, &ref, force, clobber_head, 0);
 	}
 
 	real_ref = NULL;
diff --git a/branch.h b/branch.h
index 6ada7af59..c6a8a75bb 100644
--- a/branch.h
+++ b/branch.h
@@ -27,6 +27,16 @@ void create_branch(const char *name, const char *start_name,
 		   int force, int reflog,
 		   int clobber_head, int quiet, enum branch_track track);
 
+enum branch_validation_result {
+	/* Flags that say it's NOT OK to update */
+	BRANCH_EXISTS = -3,
+	CANNOT_FORCE_UPDATE_CURRENT_BRANCH,
+	INVALID_BRANCH_NAME,
+	/* Flags that say it's OK to update */
+	VALID_BRANCH_NAME = 0,
+	FORCE_UPDATING_BRANCH = 1
+};
+
 /*
  * Validates whether the branch with the given name may be updated (created, renamed etc.,)
  * with respect to the given conditions. It returns the interpreted ref in ref.
@@ -36,10 +46,19 @@ void create_branch(const char *name, const char *start_name,
  * if 'could_exist' is true, clobber_head indicates whether the branch could be the
  * current branch else it has no effect.
  *
- * A non-zero return value indicates that a branch already exists and can be force updated.
+ * The return values have the following meaning,
+ *
+ *   - If dont_fail is 0, the function dies in case of failure and returns flags of
+ *     'validate_result' that specify it is OK to update the branch. The positive
+ *     non-zero flag implies that the branch can be force updated.
+ *
+ *   - If dont_fail is 1, the function doesn't die in case of failure but returns flags
+ *     of 'validate_result' that specify the reason for failure. The behaviour in case of
+ *     success is same as above.
  *
  */
-int validate_branch_update(const char *name, struct strbuf *ref, int could_exist, int clobber_head);
+int validate_branch_update(const char *name, struct strbuf *ref, int could_exist,
+			   int clobber_head, unsigned dont_fail);
 
 /*
  * Remove information about the state of working on the current
diff --git a/builtin/branch.c b/builtin/branch.c
index 27ddcad97..205c12a11 100644
--- a/builtin/branch.c
+++ b/builtin/branch.c
@@ -483,7 +483,7 @@ static void rename_branch(const char *oldname, const char *newname, int force)
 	 */
 	clobber_head_ok = !strcmp(oldname, newname);
 
-	validate_branch_update(newname, &newref, force, clobber_head_ok);
+	validate_branch_update(newname, &newref, force, clobber_head_ok, 0);
 
 	reject_rebase_or_bisect_branch(oldref.buf);
 
diff --git a/builtin/checkout.c b/builtin/checkout.c
index 2e870ab4b..c7e11c352 100644
--- a/builtin/checkout.c
+++ b/builtin/checkout.c
@@ -1284,7 +1284,7 @@ int cmd_checkout(int argc, const char **argv, const char *prefix)
 		int force = opts.new_branch_force != NULL;
 
 		opts.branch_exists = validate_branch_update(opts.new_branch, &buf,
-							    force, force);
+							    force, force, 0);
 
 		strbuf_release(&buf);
 	}
-- 
2.14.1.868.g66c78774b

[RFC PATCH 5/5] builtin/branch: give more useful error messages when renaming

[Kaartic Sivaraam]

When trying to rename an inexistent branch to an existing branch
the rename failed specifying the new branch name exists rather than
specifying that the branch trying to be renamed doesn't exist.

    $ git branch -m tset master
    fatal: A branch named 'master' already exists.

It's conventional to report that 'tset' doesn't exist rather than
reporting that 'master' exists, the same way the 'mv' command does.

    $ git branch -m tset master
    fatal: branch 'tset' doesn't exist.

That has the problem that the error about an existing branch is shown
only after the user corrects the error about inexistent branch.

    $ git branch -m test master
    fatal: A branch named 'master' already exists.

This isn't useful either because the user would have corrected this error in
a single go if he had been told this alongside the first error. So, give
more useful error messages by giving errors about old branch name and new
branch name at the same time. This is possible as the branch update validation
function now returns the reason it was about to die, when requested.

    $ git branch -m tset master
    fatal: branch 'tset' doesn't exist, and branch 'master' already exists

Note: Thanks to the strbuf API that made it possible to easily construct
the composite error message strings!

Signed-off-by: Kaartic Sivaraam <kaarticsivaraam91196@gmail.com>
---
 builtin/branch.c | 48 ++++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 42 insertions(+), 6 deletions(-)

diff --git a/builtin/branch.c b/builtin/branch.c
index 205c12a11..27d24e83d 100644
--- a/builtin/branch.c
+++ b/builtin/branch.c
@@ -456,25 +456,56 @@ static void reject_rebase_or_bisect_branch(const char *target)
 	free_worktrees(worktrees);
 }
 
+static void get_error_msg(struct strbuf* error_msg, const char* oldname, unsigned old_branch_exists,
+			  const char* newname, int new_branch_validation_result)
+{
+	const char* connector_string = ", and ";
+	const unsigned connector_length = 6;
+	unsigned connector_added = 0;
+
+	if (!old_branch_exists) {
+		strbuf_addf(error_msg, _("branch '%s' doesn't exist"), oldname);
+
+		/* add the 'connector_string' and remove it later if it's not needed */
+		strbuf_addstr(error_msg, connector_string);
+		connector_added = 1;
+	}
+
+	switch (new_branch_validation_result) {
+		case BRANCH_EXISTS:
+			strbuf_addf(error_msg, _("branch '%s' already exists"), newname);
+			break;
+		case CANNOT_FORCE_UPDATE_CURRENT_BRANCH:
+			strbuf_addstr(error_msg, _("cannot force update the current branch"));
+			break;
+		case INVALID_BRANCH_NAME:
+			strbuf_addf(error_msg, _("branch name '%s' is invalid"), newname);
+			break;
+		case VALID_BRANCH_NAME:
+		case FORCE_UPDATING_BRANCH:
+			if(connector_added)
+				strbuf_remove(error_msg, error_msg->len-connector_length, connector_length);
+	}
+}
+
 static void rename_branch(const char *oldname, const char *newname, int force)
 {
 	struct strbuf oldref = STRBUF_INIT, newref = STRBUF_INIT, logmsg = STRBUF_INIT;
 	struct strbuf oldsection = STRBUF_INIT, newsection = STRBUF_INIT;
 	int recovery = 0;
 	int clobber_head_ok;
+	struct strbuf error_msg = STRBUF_INIT, empty = STRBUF_INIT;
 
 	if (!oldname)
 		die(_("cannot rename the current branch while not on any."));
 
-	if (strbuf_check_branch_ref(&oldref, oldname)) {
+	if (strbuf_check_branch_ref(&oldref, oldname) && ref_exists(oldref.buf))
+	{
 		/*
 		 * Bad name --- this could be an attempt to rename a
 		 * ref that we used to allow to be created by accident.
 		 */
-		if (ref_exists(oldref.buf))
-			recovery = 1;
-		else
-			die(_("Invalid branch name: '%s'"), oldname);
+		recovery = 1;
 	}
 
 	/*
@@ -483,7 +514,10 @@ static void rename_branch(const char *oldname, const char *newname, int force)
 	 */
 	clobber_head_ok = !strcmp(oldname, newname);
 
-	validate_branch_update(newname, &newref, force, clobber_head_ok, 0);
+	get_error_msg(&error_msg, oldname, ref_exists(oldref.buf),
+			newname, validate_branch_update(newname, &newref, force, clobber_head_ok, 1));
+	if (strbuf_cmp(&error_msg, &empty))
+		die("%s", error_msg.buf);
 
 	reject_rebase_or_bisect_branch(oldref.buf);
 
@@ -509,6 +543,8 @@ static void rename_branch(const char *oldname, const char *newname, int force)
 		die(_("Branch is renamed, but update of config-file failed"));
 	strbuf_release(&oldsection);
 	strbuf_release(&newsection);
+	strbuf_release(&error_msg);
+	strbuf_release(&empty);
 }
 
 static GIT_PATH_FUNC(edit_description, "EDIT_DESCRIPTION")
-- 
2.14.1.868.g66c78774b

[RFC SAMPLE] builtin/branch: give more useful error messages when renaming

[Kaartic Sivaraam]

The patch series results in a change in output as specified below. Only 
few cases
have been shown here to keep it short. The output for other cases are 
similar.

$ git branch
* master
   foo
   bar

Before patch,

$ # Trying to rename non-existent branch
$ git branch -m hypothet no_such_branch
error: refname refs/heads/hypothet not found
fatal: Branch rename failed


$ # Trying to rename non-existent branch into existing one
$ git branch -m hypothet master
error: refname refs/heads/hypothet not found
fatal: Branch rename failed


$ # Trying to force update current branch
$ git branch -M foo master
fatal: Cannot force update the current branch.

$ # Trying to force rename an in-existent branch with an invalid name
$ git branch -M hypothet ?123
fatal: '?123' is not a valid branch name.


After patch,

$ # Trying to rename non-existent branch
$ git branch -m hypothet no_such_branch
fatal: branch 'hypothet' doesn't exist

$ # Trying to rename non-existent branch into existing one
$ git branch -m hypothet master
fatal: branch 'hypothet' doesn't exist, and branch 'master' already exists


$ # Trying to force update current branch
$ git branch -M foo master
fatal: cannot force update the current branch

$ # Trying to force rename an in-existent branch with an invalid name
$ git branch -M hypothet ?123
fatal: branch 'hypothet' doesn't exist, and branch name '?123' is invalid

Re: [RFC SAMPLE] builtin/branch: give more useful error messages when renaming

[Kaartic Sivaraam]

Sorry, the email client seems to have crapped up the formatting. In case
it looks difficult to follow, let me know so that I could send a better 
version.

---
Kaartic

Re: [RFC PATCH 1/5] builtin/checkout: avoid usage of '!!'

[Junio C Hamano]

Kaartic Sivaraam <kaarticsivaraam91196@gmail.com> writes:

> There was a usage for which there's no compelling reason.So, replace
> such a usage as with something else that expresses the intent more
> clearly.

I actually think this is a good example of the exception-rule.  The
function wants to take true or false in "int", and the caller has a
pointer.  And !!ptr is a shorter and more established way than ptr
!= NULL to turn non-NULL ness into an int boolean, without having to
either repeat or introducing an otherwise unnecessary temporary.

Re: [RFC PATCH 2/5] branch: document the usage of certain parameters

[Junio C Hamano]

Kaartic Sivaraam <kaarticsivaraam91196@gmail.com> writes:

> Documentation for a certain function was incomplete as it didn't say
> what certain parameters were used for.
>
> So, document them for the sake of completeness and easy reference.

Thanks.

> @@ -15,6 +15,11 @@
>   *
>   *   - reflog creates a reflog for the branch
>   *
> + *   - if 'force' is true, clobber_head indicates whether the branch could be
> + *     the current branch; else it has no effect

Everybody else in this list begins with what it is describing for
easy eyeballing.  Can you make this match that pattern?

Also, what does "could be" mean in that sentence?  Is the caller
telling the function "how, I do not exactly know if that is the
case, but the branch I am asking to create you might be the same
branch as what is currently checked out, so be extra careful"?

Or is the comment telling a potential caller that it can pass true
to signal that create_branch() is allowed to (re)"create" the branch
that is already checked out (hence it already exists)?

I think the confusing statement above arises because an assumption
is unstated there.  If the reader knows "Even with force, calling
create_branch() on the currently checked out branch is normally
forbidden", then the reader can guess your "could" mean the latter.

	- clobber_head_ok allows the currently checked out (hence
          existing) branch to be overwritten; without force, it has
          no effect.

perhaps?  As the underlying helper calls it clobber_head_ok, and
that name is more clearly expresses that this is a permission than
the current name, I chose to add _ok to the above example, but if
you are to take the suggestion, you'd need to also update the names
in the declaration, too.

> + *
> + *   - quiet suppresses tracking information
> + *
>   *   - track causes the new branch to be configured to merge the remote branch
>   *     that start_name is a tracking branch for (if any).
>   */

Re: [RFC PATCH 3/5] branch: cleanup branch name validation

[Junio C Hamano]

Kaartic Sivaraam <kaarticsivaraam91196@gmail.com> writes:

> -int validate_new_branchname(const char *name, struct strbuf *ref,
> -			    int force, int attr_only)
> +int validate_branch_update(const char *name, struct strbuf *ref,
> +			   int could_exist, int clobber_head)

"update" to me means something already exists and the caller is
asking this function if it is OK to update it, but is that what this
function is used for?  I do not find the original name too bad, but
if I were renaming it, I'd call it ok_to_create_branch(), with the
understanding that forcing a recreation of an existing branch falls
into the wider definition of "create".

Also I'd avoid "could", which can be taken as an optimization hint
(i.e. "you usually do not have to worry about this thing to already
exist, but I am telling you that for this one call that is not the
case and you need to be a bit more careful by spending extra cycles
to see if it is and deal with the situation accordingly if it indeed
is"), and use "ok" as part of the name for the parameter (or flip
the meaning of it and say "create_only" or something).

Re: [RFC PATCH 1/5] builtin/checkout: avoid usage of '!!'

[Kaartic Sivaraam]

On Wednesday 20 September 2017 09:30 AM, Junio C Hamano wrote:
> Kaartic Sivaraam <kaarticsivaraam91196@gmail.com> writes:
>
>> There was a usage for which there's no compelling reason.So, replace
>> such a usage as with something else that expresses the intent more
>> clearly.
> I actually think this is a good example of the exception-rule.  The
> function wants to take true or false in "int", and the caller has a
> pointer.  And !!ptr is a shorter and more established way than ptr
> != NULL to turn non-NULL ness into an int boolean, without having to
> either repeat or introducing an otherwise unnecessary temporary.

Though !!ptr might might be a shorter way to turn a pointer into an
int boolean I think the documentation says pretty well why we
shouldn't be using it,

         "..  can be extremely confusing to others".

Should I drop this treating is an exception rule (or) should I keep this
back?

Thanks,
Kaartic

Re: [RFC PATCH 2/5] branch: document the usage of certain parameters

[Kaartic Sivaraam]

On Wednesday 20 September 2017 09:42 AM, Junio C Hamano wrote:
>
>> @@ -15,6 +15,11 @@
>>    *
>>    *   - reflog creates a reflog for the branch
>>    *
>> + *   - if 'force' is true, clobber_head indicates whether the branch could be
>> + *     the current branch; else it has no effect
> Everybody else in this list begins with what it is describing for
> easy eyeballing.  Can you make this match that pattern?

Sure!

> Also, what does "could be" mean in that sentence?  Is the caller
> telling the function "how, I do not exactly know if that is the
> case, but the branch I am asking to create you might be the same
> branch as what is currently checked out, so be extra careful"?
>
> Or is the comment telling a potential caller that it can pass true
> to signal that create_branch() is allowed to (re)"create" the branch
> that is already checked out (hence it already exists)?

Thanks. I didn't anticipate the possibility of misinterpretation.

> I think the confusing statement above arises because an assumption
> is unstated there.  If the reader knows "Even with force, calling
> create_branch() on the currently checked out branch is normally
> forbidden", then the reader can guess your "could" mean the latter.
>
> 	- clobber_head_ok allows the currently checked out (hence
>            existing) branch to be overwritten; without force, it has
>            no effect.
>
> perhaps?

Sounds better. Will use it.

> ...  As the underlying helper calls it clobber_head_ok, and
> that name is more clearly expresses that this is a permission than
> the current name, I chose to add _ok to the above example, but if
> you are to take the suggestion, you'd need to also update the names
> in the declaration, too.

Yes.

One thing I haven't done suspecting it wouldn't be encouraged is,
rearranging the order of parameters to group the related ones
together i.e., something like,

diff --git a/branch.c b/branch.c
index 703ded69c..0ea105b55 100644
--- a/branch.c
+++ b/branch.c
@@ -229,7 +229,7 @@ N_("\n"
  "\"git push -u\" to set the upstream config as you push.");
  
  void create_branch(const char *name, const char *start_name,
-		   int force, int reflog, int clobber_head,
+		   int force, int clobber_head_ok, int reflog,
  		   int quiet, enum branch_track track)
  {
  	struct commit *commit;
@@ -245,7 +245,7 @@ void create_branch(const char *name, const char *start_name,
  
  	if (validate_new_branchname(name, &ref, force,
  				    track == BRANCH_TRACK_OVERRIDE ||
-				    clobber_head)) {
+				    clobber_head_ok)) {
  		if (!force)
  			dont_change_ref = 1;
  		else
diff --git a/branch.h b/branch.h
index 33b7f5d88..c62763ac9 100644
--- a/branch.h
+++ b/branch.h
@@ -13,10 +13,10 @@
   *
   *   - force enables overwriting an existing (non-head) branch
   *
- *   - reflog creates a reflog for the branch
+ *   - clobber_head_ok allows the currently checked out (hence existing)
+ *     branch to be overwritten; without 'force', it has no effect.
   *
- *   - if 'force' is true, clobber_head indicates whether the branch could be
- *     the current branch; else it has no effect
+ *   - reflog creates a reflog for the branch
   *
   *   - quiet suppresses tracking information
   *
@@ -24,8 +24,8 @@
   *     that start_name is a tracking branch for (if any).
   */
  void create_branch(const char *name, const char *start_name,
-		   int force, int reflog,
-		   int clobber_head, int quiet, enum branch_track track);
+		   int force, int clobber_head_ok,
+		   int reflog, int quiet, enum branch_track track);
  
  /*
   * Validates that the requested branch may be created, returning the
diff --git a/builtin/branch.c b/builtin/branch.c
index 355f9ef5d..62c311478 100644
--- a/builtin/branch.c
+++ b/builtin/branch.c
@@ -773,7 +773,7 @@ int cmd_branch(int argc, const char **argv, const char *prefix)
  			die(_("the '--set-upstream' option is no longer supported. Please use '--track' or '--set-upstream-to' instead."));
  
  		create_branch(argv[0], (argc == 2) ? argv[1] : head,
-			      force, reflog, 0, quiet, track);
+			      force, 0, reflog, quiet, track);
  
  	} else
  		usage_with_options(builtin_branch_usage, options);
diff --git a/builtin/checkout.c b/builtin/checkout.c
index 76859da9d..116d4709d 100644
--- a/builtin/checkout.c
+++ b/builtin/checkout.c
@@ -641,8 +641,8 @@ static void update_refs_for_switch(const struct checkout_opts *opts,
  		else
  			create_branch(opts->new_branch, new->name,
  				      opts->new_branch_force ? 1 : 0,
-				      opts->new_branch_log,
  				      opts->new_branch_force ? 1 : 0,
+				      opts->new_branch_log,
  				      opts->quiet,
  				      opts->track);
  		new->name = opts->new_branch;


Can I do this or should I keep the patch focused around the
documentation part alone?

---
Kaartic

Re: [RFC PATCH 1/5] builtin/checkout: avoid usage of '!!'

[Kaartic Sivaraam]

Wait, I missed a contradiction here.

On Wednesday 20 September 2017 09:30 AM, Junio C Hamano wrote:
> ....  And !!ptr is a shorter and more established way than ptr
> != NULL to turn non-NULL ness into an int boolean,

Documentation/SubmittingPatches says:

>  - Some clever tricks, like using the !! operator with arithmetic
>    constructs, can be extremely confusing to others.
If !!ptr is a **more established way** to then why should it confuse 
others. Of course,
!!ptr was stated as an "exception-rule" where ptr is a pointer (possibly 
NULL). That makes
me wonder in what case is it "confusing" at all?

---
Kaartic

Re: [RFC PATCH 3/5] branch: cleanup branch name validation

[Kaartic Sivaraam]

On Wednesday 20 September 2017 09:50 AM, Junio C Hamano wrote:
> Kaartic Sivaraam <kaarticsivaraam91196@gmail.com> writes:
>
>> -int validate_new_branchname(const char *name, struct strbuf *ref,
>> -			    int force, int attr_only)
>> +int validate_branch_update(const char *name, struct strbuf *ref,
>> +			   int could_exist, int clobber_head)
> "update" to me means something already exists and the caller is
> asking this function if it is OK to update it, but is that what this
> function is used for?

Of course not. I couldn't come up with better names.

>   I do not find the original name too bad, but
> if I were renaming it, I'd call it ok_to_create_branch(), with the
> understanding that forcing a recreation of an existing branch falls
> into the wider definition of "create".

Thanks for giving a better alternative. Sounds catchy. How about
`validate_branch_creation`? For some unknown reason, I seem to
like to have the word "validate" in the name. If that's not ok, I'll
use the suggested name.

> Also I'd avoid "could", which can be taken as an optimization hint
> (i.e. "you usually do not have to worry about this thing to already
> exist, but I am telling you that for this one call that is not the
> case and you need to be a bit more careful by spending extra cycles
> to see if it is and deal with the situation accordingly if it indeed
> is"), and use "ok" as part of the name for the parameter (or flip
> the meaning of it and say "create_only" or something).

Will fix that.

---
Kaartic

Re: [RFC PATCH 3/5] branch: cleanup branch name validation

[Kaartic Sivaraam]

On Wednesday 20 September 2017 09:50 AM, Junio C Hamano wrote:
> Also I'd avoid "could", which can be taken as an optimization hint
> (i.e. "you usually do not have to worry about this thing to already
> exist, but I am telling you that for this one call that is not the
> case and you need to be a bit more careful by spending extra cycles
> to see if it is and deal with the situation accordingly if it indeed
> is"), and use "ok" as part of the name for the parameter (or flip
> the meaning of it and say "create_only" or something).

Consider I'm gonna replace 'force' with a parameter that has the flipped
meaning. Does 'shouldnt_exist' seem to be a good name for this new
parameter?

Re: [RFC PATCH 5/5] builtin/branch: give more useful error messages when renaming

[Stefan Beller]

On Tue, Sep 19, 2017 at 12:15 AM, Kaartic Sivaraam
<kaarticsivaraam91196@gmail.com> wrote:
> When trying to rename an inexistent branch to an existing branch
> the rename failed specifying the new branch name exists rather than
> specifying that the branch trying to be renamed doesn't exist.
>
>     $ git branch -m tset master
>     fatal: A branch named 'master' already exists.
>
> It's conventional to report that 'tset' doesn't exist rather than
> reporting that 'master' exists, the same way the 'mv' command does.
>
>     $ git branch -m tset master

This is not the 'mv' command as promised? So this is just
to demonstrate the (still fictional) better error message?
Maybe use a real 'mv' command here?

>     fatal: branch 'tset' doesn't exist.
>
> That has the problem that the error about an existing branch is shown
> only after the user corrects the error about inexistent branch.
>
>     $ git branch -m test master
>     fatal: A branch named 'master' already exists.
>
> This isn't useful either because the user would have corrected this error in
> a single go if he had been told this alongside the first error. So, give
> more useful error messages by giving errors about old branch name and new
> branch name at the same time. This is possible as the branch update validation
> function now returns the reason it was about to die, when requested.
>
>     $ git branch -m tset master
>     fatal: branch 'tset' doesn't exist, and branch 'master' already exists
>
> Note: Thanks to the strbuf API that made it possible to easily construct
> the composite error message strings!

This shall be read as an apology to all translators out there. ;)
Playing sentence lego in source code is not optimal, as other
languages are very different and you cannot assume even simplest
things about them (because of their variety).

In this case it might not be as bad, because we're providing a
whole sentence per _(translatable) unit.

Re: [RFC PATCH 1/5] builtin/checkout: avoid usage of '!!'

[Junio C Hamano]

Kaartic Sivaraam <kaarticsivaraam91196@gmail.com> writes:

> Wait, I missed a contradiction here.
> ..
> Documentation/SubmittingPatches says:
>
>>  - Some clever tricks, like using the !! operator with arithmetic
>>    constructs, can be extremely confusing to others.

What does "with arithmetic constructs" mean?  Would it refer to
things like

	!!i != !!(j + 3)

that unnecessarily obfuscates what is going on?

The primary reason why !!ptr is good in the code that this patch
touches is because what is doubly negated is a pointer, not an
integer or other things.  The called function does *not* limit its
input to 0 or 1 (it wants 0 for false and everything else for true),
so we wouldn't be doing !!i if what we are passing is already an
integer.  But we cannot just pass a pointer to such a parameter
without getting the compiler upset.

Re: [RFC PATCH 2/5] branch: document the usage of certain parameters

[Junio C Hamano]

Kaartic Sivaraam <kaarticsivaraam91196@gmail.com> writes:

> Can I do this or should I keep the patch focused around the
> documentation part alone?

You can do both if you wanted to but not in a same patch that makes
the result noisier than it needs to.

Re: [RFC PATCH 3/5] branch: cleanup branch name validation

[Junio C Hamano]

Kaartic Sivaraam <kaarticsivaraam91196@gmail.com> writes:

> Thanks for giving a better alternative. Sounds catchy. How about
> `validate_branch_creation`?

I do not know what you meant by "catchy", but "git grep ok_to_" will
tell you that ok-to-$do-something is quite an establish phrasing (if
I thought it was a bad way to name it, I would have explicitly said
so).

Re: [RFC PATCH 5/5] builtin/branch: give more useful error messages when renaming

[Kaartic Sivaraam]

On Thursday 21 September 2017 02:27 AM, Stefan Beller wrote:
>
>> It's conventional to report that 'tset' doesn't exist rather than
>> reporting that 'master' exists, the same way the 'mv' command does.
>>
>>      $ git branch -m tset master
> This is not the 'mv' command as promised? So this is just
> to demonstrate the (still fictional) better error message?

Yes

> Maybe use a real 'mv' command here?

It didn't want to do that to avoid preserve continuity. I'll change the 
commit
message a little to fix this.

---
Kaartic

Re: [RFC PATCH 1/5] builtin/checkout: avoid usage of '!!'

[Kaartic Sivaraam]

On Thursday 21 September 2017 07:01 AM, Junio C Hamano wrote:
> What does "with arithmetic constructs" mean? Would it refer to
> things like
>
> 	!!i != !!(j + 3)
>
> that unnecessarily obfuscates what is going on?

Thanks that clears the confusion because I haven't seen constructs
like this before (who would even do something like this?)

> The primary reason why !!ptr is good in the code that this patch
> touches is because what is doubly negated is a pointer, not an
> integer or other things.  The called function does *not* limit its
> input to 0 or 1 (it wants 0 for false and everything else for true),
> so we wouldn't be doing !!i if what we are passing is already an
> integer.  But we cannot just pass a pointer to such a parameter
> without getting the compiler upset.
>
>

Done. So I'll drop this patch.

---
Kaartic

Re: [RFC PATCH 3/5] branch: cleanup branch name validation

[Kaartic Sivaraam]

On Thursday 21 September 2017 07:07 AM, Junio C Hamano wrote:
> Kaartic Sivaraam <kaarticsivaraam91196@gmail.com> writes:
>
>> Thanks for giving a better alternative. Sounds catchy. How about
>> `validate_branch_creation`?
> I do not know what you meant by "catchy",

I was intending that 'ok_to_create_branch' was a "nice alternative" when I
said catchy (I should better be more clear in the future).

> but "git grep ok_to_" will
> tell you that ok-to-$do-something is quite an establish phrasing (if
> I thought it was a bad way to name it, I would have explicitly said
> so).
>

Well, it might be an established phrase but I feel that the 'ok_to' part 
of the
name implies that it returns some sort of boolean value ('ok' or 'not ok')
rather than the status. This doesn't seem to be the case for the
`validate_new_branchname` which returns values only upon success
and dies in case of failure (Note: only the PATCH 4/5 in the series adds 
the
logic to return a value in case of failure; when requested). So, I find the
name "ok_to_create_branch" to be less communicative. Though I don't find
the name "validate_branch_creation" to be conveys this meaning any better;
I thought of using it as it doesn't seem to be implying a boolean return 
value.

---
Kaartic

[RFC PATCH v2 0/5] Give more useful error messages when renaming a branch

[Kaartic Sivaraam]

    [1/5] and [2/5] - cleanup patches
    [3/5] - refactor of a function that seemed a little unintuitive
    [4/5] - just a preparatory step adding part of the logic
    [5/5] - main patch that tries to improve the error messages

Changes in v2:

    - dropped [1/5] of v1
    
    [1/5]

        - incroporated suggestions of Junio

    [2/5]

        - new in this series
        - just a little thing I thought could improve things

    [3/5]

        - used the name 'validate_branch_creation' for the refactor
          instead of 'validate_branch_update'

        - changed the parameter names

    [5/5]

        - In v1 I added the connector string and removed it when it wasn't 
          necessary. It's not possible to do that as that string has to be
          translated too and it won't have the same number of characters in
          other languages. So, I switched to adding the connector only when
          needed. Though this seems to introduce some redundancy, I find it
          to be the only reliable way.          

        - tweaked commit message a little as suggested by Stefan

There is no change in the error messages themselves. So the sample input
output interaction sent for v1 still holds.

This series applies on top of 'master' and can be found in my fork[1].
In case you were wondering, the Travis-CI tests did pass.

[1]: https://github.com/sivaraam/git/tree/work/branch-move-revamp
[2]: https://travis-ci.org/sivaraam/git/builds/279199977

Kaartic Sivaraam (5):
  branch: improve documentation and naming of certain parameters
  branch: re-order function arguments to group related arguments
  branch: cleanup branch name validation
  branch: introduce dont_fail parameter for create validation
  builtin/branch: give more useful error messages when renaming

 branch.c           | 69 +++++++++++++++++++++++++++++++++++++++---------------
 branch.h           | 53 ++++++++++++++++++++++++++++++-----------
 builtin/branch.c   | 43 ++++++++++++++++++++++++++++------
 builtin/checkout.c |  8 +++----
 t/t3200-branch.sh  |  4 ++++
 5 files changed, 133 insertions(+), 44 deletions(-)

-- 
2.14.1.935.ge2b2bcd8a

[RFC PATCH v2 1/5] branch: improve documentation and naming of certain parameters

[Kaartic Sivaraam]

Documentation for a certain function was incomplete as it didn't say
what certain parameters were used for. Further a parameter name wasn't
very communicative.

So, add missing documentation for the sake of completeness and easy
reference. Also, rename the concerned parameter to make it's name more
communicative.

Signed-off-by: Kaartic Sivaraam <kaarticsivaraam91196@gmail.com>
---
 branch.c | 4 ++--
 branch.h | 7 ++++++-
 2 files changed, 8 insertions(+), 3 deletions(-)

diff --git a/branch.c b/branch.c
index 703ded69c..8d4360aa5 100644
--- a/branch.c
+++ b/branch.c
@@ -229,7 +229,7 @@ N_("\n"
 "\"git push -u\" to set the upstream config as you push.");
 
 void create_branch(const char *name, const char *start_name,
-		   int force, int reflog, int clobber_head,
+		   int force, int reflog, int clobber_head_ok,
 		   int quiet, enum branch_track track)
 {
 	struct commit *commit;
@@ -245,7 +245,7 @@ void create_branch(const char *name, const char *start_name,
 
 	if (validate_new_branchname(name, &ref, force,
 				    track == BRANCH_TRACK_OVERRIDE ||
-				    clobber_head)) {
+				    clobber_head_ok)) {
 		if (!force)
 			dont_change_ref = 1;
 		else
diff --git a/branch.h b/branch.h
index b07788558..cb6411f84 100644
--- a/branch.h
+++ b/branch.h
@@ -15,12 +15,17 @@
  *
  *   - reflog creates a reflog for the branch
  *
+ *   - clobber_head_ok allows the currently checked out (hence existing)
+ *     branch to be overwritten; without 'force', it has no effect.
+ *
+ *   - quiet suppresses tracking information
+ *
  *   - track causes the new branch to be configured to merge the remote branch
  *     that start_name is a tracking branch for (if any).
  */
 void create_branch(const char *name, const char *start_name,
 		   int force, int reflog,
-		   int clobber_head, int quiet, enum branch_track track);
+		   int clobber_head_ok, int quiet, enum branch_track track);
 
 /*
  * Validates that the requested branch may be created, returning the
-- 
2.14.1.935.ge2b2bcd8a

[RFC PATCH v2 2/5] branch: re-order function arguments to group related arguments

[Kaartic Sivaraam]

The ad-hoc patches to add new arguments to a function when needed
resulted in the related arguments not being close to each other.
This misleads the person reading the code to believe that there isn't
much relation between those arguments while it's not the case.

So, re-order the arguments to keep the related arguments close to each
other.

Signed-off-by: Kaartic Sivaraam <kaarticsivaraam91196@gmail.com>
---
 branch.c           | 2 +-
 branch.h           | 4 ++--
 builtin/branch.c   | 2 +-
 builtin/checkout.c | 2 +-
 4 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/branch.c b/branch.c
index 8d4360aa5..0ea105b55 100644
--- a/branch.c
+++ b/branch.c
@@ -229,7 +229,7 @@ N_("\n"
 "\"git push -u\" to set the upstream config as you push.");
 
 void create_branch(const char *name, const char *start_name,
-		   int force, int reflog, int clobber_head_ok,
+		   int force, int clobber_head_ok, int reflog,
 		   int quiet, enum branch_track track)
 {
 	struct commit *commit;
diff --git a/branch.h b/branch.h
index cb6411f84..a6740bb9f 100644
--- a/branch.h
+++ b/branch.h
@@ -24,8 +24,8 @@
  *     that start_name is a tracking branch for (if any).
  */
 void create_branch(const char *name, const char *start_name,
-		   int force, int reflog,
-		   int clobber_head_ok, int quiet, enum branch_track track);
+		   int force, int clobber_head_ok,
+		   int reflog, int quiet, enum branch_track track);
 
 /*
  * Validates that the requested branch may be created, returning the
diff --git a/builtin/branch.c b/builtin/branch.c
index 355f9ef5d..62c311478 100644
--- a/builtin/branch.c
+++ b/builtin/branch.c
@@ -773,7 +773,7 @@ int cmd_branch(int argc, const char **argv, const char *prefix)
 			die(_("the '--set-upstream' option is no longer supported. Please use '--track' or '--set-upstream-to' instead."));
 
 		create_branch(argv[0], (argc == 2) ? argv[1] : head,
-			      force, reflog, 0, quiet, track);
+			      force, 0, reflog, quiet, track);
 
 	} else
 		usage_with_options(builtin_branch_usage, options);
diff --git a/builtin/checkout.c b/builtin/checkout.c
index 5c202b7af..4ef7a47e1 100644
--- a/builtin/checkout.c
+++ b/builtin/checkout.c
@@ -641,8 +641,8 @@ static void update_refs_for_switch(const struct checkout_opts *opts,
 		else
 			create_branch(opts->new_branch, new->name,
 				      opts->new_branch_force ? 1 : 0,
-				      opts->new_branch_log,
 				      opts->new_branch_force ? 1 : 0,
+				      opts->new_branch_log,
 				      opts->quiet,
 				      opts->track);
 		new->name = opts->new_branch;
-- 
2.14.1.935.ge2b2bcd8a

[RFC PATCH v2 3/5] branch: cleanup branch name validation

[Kaartic Sivaraam]

The function that validates a new branch name was clumsy because,

  1. It did more than just validating the branch name.

  2. Despite it's name, it is more often than not used to validate
     existing branch names through the 'force' and 'attr_only'
     parameters (whose names by the way weren't communicative).

  3. The 'attr_only' parameter should have been "true" only when
     callers like to update some attribute of the branch and "false"
     when they were updating where the branch points to. It was misused
     by callers by setting it to "true" (to skip tests) even though they
     were force updating where the current branch was pointing to!

     This is an example of spoiling code clarity by making the caller
     rely on how the function is implemented thus making it hard to
     modify/maintain.

This makes it unclear what the function does at all and would confuse
the people who would ever want to it for the first time.

So, refactor it into a function that validates whether the branch could
be created. This doesn't bear the uncommunicative 'new'. Further replace
the 'force' parameter with a 'shouldnt_exist' parameter which specifies
that a another branch with the given branch name should not (IOW, it's
just the opposite of 'force') Also replace  the 'attr_only' with
'clobber_head_ok' which is a more communicative way of saying "If
another branch could exist, it's OK if it is the current branch".

Separate the validation of an existing branch (partly) into another function.
This (at last!) addresses the NEEDSWORK that was added in fa7993767
(branch --set-upstream: regression fix, 2011-09-16)

This refactor has only one functional change. It enforces strictly that
an existing branch should be updated only with the 'force' switch. So,
it's no more possible to do,

        $ git branch -m master master

(which doesn't seem that useful). This strongly enforces the following
statement of the 'git branch' documentation,

        "If <newbranch> exists, -M must be used to force the
         rename to happen."

Signed-off-by: Kaartic Sivaraam <kaarticsivaraam91196@gmail.com>
---
 branch.c           | 41 ++++++++++++++++++++++++++++++-----------
 branch.h           | 25 +++++++++++++------------
 builtin/branch.c   |  2 +-
 builtin/checkout.c |  4 ++--
 t/t3200-branch.sh  |  4 ++++
 5 files changed, 50 insertions(+), 26 deletions(-)

diff --git a/branch.c b/branch.c
index 0ea105b55..db2abeb7e 100644
--- a/branch.c
+++ b/branch.c
@@ -178,18 +178,19 @@ int read_branch_desc(struct strbuf *buf, const char *branch_name)
 	return 0;
 }
 
-int validate_new_branchname(const char *name, struct strbuf *ref,
-			    int force, int attr_only)
+int validate_branch_creation(const char *name, struct strbuf *ref,
+			     int shouldnt_exist, int clobber_head_ok)
 {
 	if (strbuf_check_branch_ref(ref, name))
 		die(_("'%s' is not a valid branch name."), name);
 
 	if (!ref_exists(ref->buf))
 		return 0;
-	else if (!force && !attr_only)
+
+	if (shouldnt_exist)
 		die(_("A branch named '%s' already exists."), ref->buf + strlen("refs/heads/"));
 
-	if (!attr_only) {
+	if (!clobber_head_ok) {
 		const char *head;
 		struct object_id oid;
 
@@ -197,9 +198,29 @@ int validate_new_branchname(const char *name, struct strbuf *ref,
 		if (!is_bare_repository() && head && !strcmp(head, ref->buf))
 			die(_("Cannot force update the current branch."));
 	}
+
 	return 1;
 }
 
+/*
+ * Validates whether the branch with the given name exists, returning the
+ * interpreted ref in ref.
+ *
+ * This method is invoked if the caller merely wants to know if it is OK
+ * to change some attribute for the named branch (e.g. tracking upstream).
+ *
+ */
+static void validate_existing_branch(const char *name, struct strbuf *ref)
+{
+	if (strbuf_check_branch_ref(ref, name))
+		die(_("'%s' is not a valid branch name."), name);
+
+	if (ref_exists(ref->buf))
+		return;
+	else
+		die(_("branch '%s' doesn't exist"), name);
+}
+
 static int check_tracking_branch(struct remote *remote, void *cb_data)
 {
 	char *tracking_branch = cb_data;
@@ -243,13 +264,11 @@ void create_branch(const char *name, const char *start_name,
 	if (track == BRANCH_TRACK_EXPLICIT || track == BRANCH_TRACK_OVERRIDE)
 		explicit_tracking = 1;
 
-	if (validate_new_branchname(name, &ref, force,
-				    track == BRANCH_TRACK_OVERRIDE ||
-				    clobber_head_ok)) {
-		if (!force)
-			dont_change_ref = 1;
-		else
-			forcing = 1;
+	if (track == BRANCH_TRACK_OVERRIDE) {
+		validate_existing_branch(name, &ref);
+		dont_change_ref = 1;
+	} else {
+		forcing = validate_branch_creation(name, &ref, !force, clobber_head_ok);
 	}
 
 	real_ref = NULL;
diff --git a/branch.h b/branch.h
index a6740bb9f..a6dde552c 100644
--- a/branch.h
+++ b/branch.h
@@ -28,22 +28,23 @@ void create_branch(const char *name, const char *start_name,
 		   int reflog, int quiet, enum branch_track track);
 
 /*
- * Validates that the requested branch may be created, returning the
- * interpreted ref in ref, force indicates whether (non-head) branches
- * may be overwritten. A non-zero return value indicates that the force
- * parameter was non-zero and the branch already exists.
+ * Validates whether the branch with the given name may be updated (created, renamed etc.,)
+ * with respect to the given conditions.
  *
- * Contrary to all of the above, when attr_only is 1, the caller is
- * not interested in verifying if it is Ok to update the named
- * branch to point at a potentially different commit. It is merely
- * asking if it is OK to change some attribute for the named branch
- * (e.g. tracking upstream).
+ *   - name is the new branch name
  *
- * NEEDSWORK: This needs to be split into two separate functions in the
- * longer run for sanity.
+ *   - ref contains the interpreted ref for the given name
+ *
+ *   - shouldnt_exist indicates that another branch with the given name
+ *     should not exist
+ *
+ *   - clobber_head_ok allows another branch with given branch name to be
+ *     the currently checkout branch; with 'shouldnt_exist', it has no effect.
+ *
+ * A non-zero return value indicates that a branch already exists and can be force updated.
  *
  */
-int validate_new_branchname(const char *name, struct strbuf *ref, int force, int attr_only);
+int validate_branch_creation(const char *name, struct strbuf *ref, int shouldnt_exist, int clobber_head_ok);
 
 /*
  * Remove information about the state of working on the current
diff --git a/builtin/branch.c b/builtin/branch.c
index 62c311478..aa2f36519 100644
--- a/builtin/branch.c
+++ b/builtin/branch.c
@@ -483,7 +483,7 @@ static void rename_branch(const char *oldname, const char *newname, int force)
 	 */
 	clobber_head_ok = !strcmp(oldname, newname);
 
-	validate_new_branchname(newname, &newref, force, clobber_head_ok);
+	validate_branch_creation(newname, &newref, !force, clobber_head_ok);
 
 	reject_rebase_or_bisect_branch(oldref.buf);
 
diff --git a/builtin/checkout.c b/builtin/checkout.c
index 4ef7a47e1..fcbbbb1fa 100644
--- a/builtin/checkout.c
+++ b/builtin/checkout.c
@@ -1283,8 +1283,8 @@ int cmd_checkout(int argc, const char **argv, const char *prefix)
 		struct strbuf buf = STRBUF_INIT;
 
 		opts.branch_exists =
-			validate_new_branchname(opts.new_branch, &buf,
-						!!opts.new_branch_force,
+			validate_branch_creation(opts.new_branch, &buf,
+						!opts.new_branch_force,
 						!!opts.new_branch_force);
 
 		strbuf_release(&buf);
diff --git a/t/t3200-branch.sh b/t/t3200-branch.sh
index d97164997..ec85cd959 100755
--- a/t/t3200-branch.sh
+++ b/t/t3200-branch.sh
@@ -137,6 +137,10 @@ test_expect_success 'git branch -m -f o/q o/p should work when o/p exists' '
 	git branch -m -f o/q o/p
 '
 
+test_expect_success 'git branch -m o/o o/o should fail when o/o exists' '
+	test_must_fail git branch -m o/o o/o
+'
+
 test_expect_success 'git branch -m q r/q should fail when r exists' '
 	git branch q &&
 	git branch r &&
-- 
2.14.1.935.ge2b2bcd8a

[RFC PATCH v2 4/5] branch: introduce dont_fail parameter for create validation

[Kaartic Sivaraam]

This parameter allows the branch create validation function to
optionally return a flag specifying the reason for failure, when
requested. This allows the caller to know why it was about to die.
This allows more useful error messages to be given to the user when
trying to rename a branch.

The flags are specified in the form of an enum and values for success
flags have been assigned explicitly to clearly express that certain
callers rely those values and they cannot be arbitrary.

Only the logic has been added but no caller has been made to use it, yet.
So, no functional changes.

Signed-off-by: Kaartic Sivaraam <kaarticsivaraam91196@gmail.com>
---
 branch.c           | 32 ++++++++++++++++++++++----------
 branch.h           | 23 +++++++++++++++++++++--
 builtin/branch.c   |  2 +-
 builtin/checkout.c |  2 +-
 4 files changed, 45 insertions(+), 14 deletions(-)

diff --git a/branch.c b/branch.c
index db2abeb7e..83305ded6 100644
--- a/branch.c
+++ b/branch.c
@@ -179,27 +179,39 @@ int read_branch_desc(struct strbuf *buf, const char *branch_name)
 }
 
 int validate_branch_creation(const char *name, struct strbuf *ref,
-			     int shouldnt_exist, int clobber_head_ok)
+			     int shouldnt_exist, int clobber_head_ok, unsigned dont_fail)
 {
-	if (strbuf_check_branch_ref(ref, name))
-		die(_("'%s' is not a valid branch name."), name);
+	if (strbuf_check_branch_ref(ref, name)) {
+		if (dont_fail)
+			return INVALID_BRANCH_NAME;
+		else
+			die(_("'%s' is not a valid branch name."), name);
+	}
 
 	if (!ref_exists(ref->buf))
-		return 0;
+		return VALID_BRANCH_NAME;
 
-	if (shouldnt_exist)
-		die(_("A branch named '%s' already exists."), ref->buf + strlen("refs/heads/"));
+	if (shouldnt_exist) {
+		if (dont_fail)
+			return BRANCH_EXISTS;
+		else
+			die(_("A branch named '%s' already exists."), ref->buf + strlen("refs/heads/"));
+	}
 
 	if (!clobber_head_ok) {
 		const char *head;
 		struct object_id oid;
 
 		head = resolve_ref_unsafe("HEAD", 0, oid.hash, NULL);
-		if (!is_bare_repository() && head && !strcmp(head, ref->buf))
-			die(_("Cannot force update the current branch."));
+		if (!is_bare_repository() && head && !strcmp(head, ref->buf)) {
+			if (dont_fail)
+				return CANNOT_FORCE_UPDATE_CURRENT_BRANCH;
+			else
+				die(_("Cannot force update the current branch."));
+		}
 	}
 
-	return 1;
+	return FORCE_UPDATING_BRANCH;
 }
 
 /*
@@ -268,7 +280,7 @@ void create_branch(const char *name, const char *start_name,
 		validate_existing_branch(name, &ref);
 		dont_change_ref = 1;
 	} else {
-		forcing = validate_branch_creation(name, &ref, !force, clobber_head_ok);
+		forcing = validate_branch_creation(name, &ref, !force, clobber_head_ok, 0);
 	}
 
 	real_ref = NULL;
diff --git a/branch.h b/branch.h
index a6dde552c..4b68a789d 100644
--- a/branch.h
+++ b/branch.h
@@ -27,6 +27,16 @@ void create_branch(const char *name, const char *start_name,
 		   int force, int clobber_head_ok,
 		   int reflog, int quiet, enum branch_track track);
 
+enum branch_validation_result {
+	/* Flags that say it's NOT OK to update */
+	BRANCH_EXISTS = -3,
+	CANNOT_FORCE_UPDATE_CURRENT_BRANCH,
+	INVALID_BRANCH_NAME,
+	/* Flags that say it's OK to update */
+	VALID_BRANCH_NAME = 0,
+	FORCE_UPDATING_BRANCH = 1
+};
+
 /*
  * Validates whether the branch with the given name may be updated (created, renamed etc.,)
  * with respect to the given conditions.
@@ -41,10 +51,19 @@ void create_branch(const char *name, const char *start_name,
  *   - clobber_head_ok allows another branch with given branch name to be
  *     the currently checkout branch; with 'shouldnt_exist', it has no effect.
  *
- * A non-zero return value indicates that a branch already exists and can be force updated.
+ * The return values have the following meaning,
+ *
+ *   - If dont_fail is 0, the function dies in case of failure and returns flags of
+ *     'validate_result' that indicate that it's OK to update the branch. The positive
+ *     non-zero flag implies that the branch can be force updated.
+ *
+ *   - If dont_fail is 1, the function doesn't die in case of failure but returns flags
+ *     of 'validate_result' that specify the reason for failure. The behaviour in case of
+ *     success is same as above.
  *
  */
-int validate_branch_creation(const char *name, struct strbuf *ref, int shouldnt_exist, int clobber_head_ok);
+int validate_branch_creation(const char *name, struct strbuf *ref,
+			     int shouldnt_exist, int clobber_head_ok, unsigned dont_fail);
 
 /*
  * Remove information about the state of working on the current
diff --git a/builtin/branch.c b/builtin/branch.c
index aa2f36519..25e3a2f29 100644
--- a/builtin/branch.c
+++ b/builtin/branch.c
@@ -483,7 +483,7 @@ static void rename_branch(const char *oldname, const char *newname, int force)
 	 */
 	clobber_head_ok = !strcmp(oldname, newname);
 
-	validate_branch_creation(newname, &newref, !force, clobber_head_ok);
+	validate_branch_creation(newname, &newref, !force, clobber_head_ok, 0);
 
 	reject_rebase_or_bisect_branch(oldref.buf);
 
diff --git a/builtin/checkout.c b/builtin/checkout.c
index fcbbbb1fa..e9d636c66 100644
--- a/builtin/checkout.c
+++ b/builtin/checkout.c
@@ -1285,7 +1285,7 @@ int cmd_checkout(int argc, const char **argv, const char *prefix)
 		opts.branch_exists =
 			validate_branch_creation(opts.new_branch, &buf,
 						!opts.new_branch_force,
-						!!opts.new_branch_force);
+						!!opts.new_branch_force, 0);
 
 		strbuf_release(&buf);
 	}
-- 
2.14.1.935.ge2b2bcd8a

[RFC PATCH v2 5/5] builtin/branch: give more useful error messages when renaming

[Kaartic Sivaraam]

When trying to rename an inexistent branch to with a name of a branch
that already exists the rename failed specifying the new branch name
exists rather than specifying that the branch trying to be renamed
doesn't exist.

    $ git branch -m tset master
    fatal: A branch named 'master' already exists.

It's conventional to report that 'tset' doesn't exist rather than
reporting that 'master' exists, the same way the 'mv' command does.

    (hypothetical)
    $ git branch -m tset master
    fatal: branch 'tset' doesn't exist.

That has the problem that the error about an existing branch is shown
only after the user corrects the error about inexistent branch.

    $ git branch -m test master
    fatal: A branch named 'master' already exists.

This isn't useful either because the user would have corrected this error in
a single go if he had been told this alongside the first error. So, give
more useful error messages by giving errors about old branch name and new
branch name at the same time. This is possible as the branch validation
function now returns the reason it was about to die, when requested.

    $ git branch -m tset master
    fatal: branch 'tset' doesn't exist, and branch 'master' already exists

Note: Thanks to the strbuf API that made it possible to easily construct
the composite error message strings!

Signed-off-by: Kaartic Sivaraam <kaarticsivaraam91196@gmail.com>
---
 builtin/branch.c | 41 +++++++++++++++++++++++++++++++++++------
 1 file changed, 35 insertions(+), 6 deletions(-)

diff --git a/builtin/branch.c b/builtin/branch.c
index 25e3a2f29..0c2017bee 100644
--- a/builtin/branch.c
+++ b/builtin/branch.c
@@ -456,25 +456,49 @@ static void reject_rebase_or_bisect_branch(const char *target)
 	free_worktrees(worktrees);
 }
 
+static void get_error_msg(struct strbuf* error_msg, const char* oldname, unsigned old_branch_exists,
+			  const char* newname, int new_branch_validation_result)
+{
+	const char* connector_string = _(", and ");
+
+	if (!old_branch_exists) {
+		strbuf_addf(error_msg, _("branch '%s' doesn't exist"), oldname);
+	}
+
+	switch (new_branch_validation_result) {
+		case BRANCH_EXISTS:
+			strbuf_addf(error_msg, "%s", (!old_branch_exists) ? connector_string : "");
+			strbuf_addf(error_msg,_("branch '%s' already exists"), newname);
+			break;
+		case CANNOT_FORCE_UPDATE_CURRENT_BRANCH:
+			strbuf_addf(error_msg, "%s", (!old_branch_exists) ? connector_string : "");
+			strbuf_addstr(error_msg, _("cannot force update the current branch"));
+			break;
+		case INVALID_BRANCH_NAME:
+			strbuf_addf(error_msg, "%s", (!old_branch_exists) ? connector_string : "");
+			strbuf_addf(error_msg, _("branch name '%s' is invalid"), newname);
+			break;
+	}
+}
+
 static void rename_branch(const char *oldname, const char *newname, int force)
 {
 	struct strbuf oldref = STRBUF_INIT, newref = STRBUF_INIT, logmsg = STRBUF_INIT;
 	struct strbuf oldsection = STRBUF_INIT, newsection = STRBUF_INIT;
 	int recovery = 0;
 	int clobber_head_ok;
+	struct strbuf error_msg = STRBUF_INIT, empty = STRBUF_INIT;
 
 	if (!oldname)
 		die(_("cannot rename the current branch while not on any."));
 
-	if (strbuf_check_branch_ref(&oldref, oldname)) {
+	if (strbuf_check_branch_ref(&oldref, oldname) && ref_exists(oldref.buf))
+	{
 		/*
 		 * Bad name --- this could be an attempt to rename a
 		 * ref that we used to allow to be created by accident.
 		 */
-		if (ref_exists(oldref.buf))
-			recovery = 1;
-		else
-			die(_("Invalid branch name: '%s'"), oldname);
+		recovery = 1;
 	}
 
 	/*
@@ -483,7 +507,10 @@ static void rename_branch(const char *oldname, const char *newname, int force)
 	 */
 	clobber_head_ok = !strcmp(oldname, newname);
 
-	validate_branch_creation(newname, &newref, !force, clobber_head_ok, 0);
+	get_error_msg(&error_msg, oldname, ref_exists(oldref.buf),
+			newname, validate_branch_creation(newname, &newref, !force, clobber_head_ok, 1));
+	if (strbuf_cmp(&error_msg, &empty))
+		die("%s", error_msg.buf);
 
 	reject_rebase_or_bisect_branch(oldref.buf);
 
@@ -509,6 +536,8 @@ static void rename_branch(const char *oldname, const char *newname, int force)
 		die(_("Branch is renamed, but update of config-file failed"));
 	strbuf_release(&oldsection);
 	strbuf_release(&newsection);
+	strbuf_release(&error_msg);
+	strbuf_release(&empty);
 }
 
 static GIT_PATH_FUNC(edit_description, "EDIT_DESCRIPTION")
-- 
2.14.1.935.ge2b2bcd8a

Re: [RFC PATCH v2 0/5] Give more useful error messages when renaming a branch

[Kaartic Sivaraam]

What happened to the v2 of the patch? Has this not received attention
or is there anything that's not done correctly?

-- 
Kaartic

Re: [RFC PATCH v2 0/5] Give more useful error messages when renaming a branch

[Stefan Beller]

On Fri, Oct 20, 2017 at 12:09 AM, Kaartic Sivaraam
<kaartic.sivaraam@gmail.com> wrote:
> What happened to the v2 of the patch? Has this not received attention
> or is there anything that's not done correctly?
>

I just checked origin/pu as well as the latest cooking email
https://public-inbox.org/git/xmqqr2tzith7.fsf@gitster.mtv.corp.google.com/
and could not find your series.

Sorry for dropping the ball as a reviewer, I'll take a look.

Thanks for pinging,
Stefan

Re: [RFC PATCH v2 1/5] branch: improve documentation and naming of certain parameters

[Stefan Beller]

On Mon, Sep 25, 2017 at 1:20 AM, Kaartic Sivaraam
<kaartic.sivaraam@gmail.com> wrote:
> Documentation for a certain function was incomplete as it didn't say
> what certain parameters were used for. Further a parameter name wasn't
> very communicative.
>
> So, add missing documentation for the sake of completeness and easy
> reference. Also, rename the concerned parameter to make it's name more
> communicative.
>
> Signed-off-by: Kaartic Sivaraam <kaarticsivaraam91196@gmail.com>

Up to here ( including the subject line), I have no idea you're talking about
'create_branch'. Maybe

    branch: improve documentation and naming of parameters for create_branch

    The documentation for 'create_branch' was incomplete ...

The patch itself looks great!

Thanks,
Stefan

Re: [RFC PATCH v2 2/5] branch: re-order function arguments to group related arguments

[Stefan Beller]

On Mon, Sep 25, 2017 at 1:20 AM, Kaartic Sivaraam
<kaartic.sivaraam@gmail.com> wrote:
> The ad-hoc patches to add new arguments to a function when needed
> resulted in the related arguments not being close to each other.
> This misleads the person reading the code to believe that there isn't
> much relation between those arguments while it's not the case.
>
> So, re-order the arguments to keep the related arguments close to each
> other.

Thanks for taking a lot at the code quality in detail.

In my currently checked out version of Git, there are two occurrences
of create_branch in builtin/branch.c, this patch converts only one occurrence.

(So you'd need to convert that second one, too. Oh wait; it is converted
implicitly as the arguments are both '0':
    create_branch(branch->name, new_upstream, 0, 0, 0, \
        quiet, BRANCH_TRACK_OVERRIDE);
)

This leads to the generic problem of this patch: Assume there are other
contributors that write patches. They may introduce new calls to
`create_branch`, but using the order of parameters as they may
be unaware of this patch and they'd test without this patch.

As the signature of the function call doesn't change the compiler
doesn't assist us in finding such a potential race between patches.

I am not aware of any other patches in flight, so we *might* be fine
with this patch. But hope is rarely a good strategy.

Can we change the function signature (the name or another order
of arguments that also makes sense, or making one of the
parameters an enum) such that a potential race can be detected
easier?

Thanks,
Stefan

Re: [RFC PATCH v2 1/5] branch: improve documentation and naming of certain parameters

[Eric Sunshine]

On Mon, Sep 25, 2017 at 1:20 AM, Kaartic Sivaraam
<kaartic.sivaraam@gmail.com> wrote:
> Documentation for a certain function was incomplete as it didn't say
> what certain parameters were used for. Further a parameter name wasn't
> very communicative.
>
> So, add missing documentation for the sake of completeness and easy
> reference. Also, rename the concerned parameter to make it's name more

s/it's/its/

> communicative.
>
> Signed-off-by: Kaartic Sivaraam <kaarticsivaraam91196@gmail.com>

Re: [RFC PATCH v2 1/5] branch: improve documentation and naming of certain parameters

[Kaartic Sivaraam]

On Fri, 2017-10-20 at 14:33 -0700, Stefan Beller wrote:
> Up to here ( including the subject line), I have no idea you're talking about
> 'create_branch'. Maybe
> 

That's because I didn't want to be explicit.

>     branch: improve documentation and naming of parameters for create_branch
> 
>     The documentation for 'create_branch' was incomplete ...
> 

Sounds good, will use it.

-- 
Kaartic

Re: [RFC PATCH v2 1/5] branch: improve documentation and naming of certain parameters

[Kaartic Sivaraam]

On Fri, 2017-10-20 at 17:51 -0400, Eric Sunshine wrote:
> On Mon, Sep 25, 2017 at 1:20 AM, Kaartic Sivaraam
> <kaartic.sivaraam@gmail.com> wrote:
> > Documentation for a certain function was incomplete as it didn't say
> > what certain parameters were used for. Further a parameter name wasn't
> > very communicative.
> > 
> > So, add missing documentation for the sake of completeness and easy
> > reference. Also, rename the concerned parameter to make it's name more
> 
> s/it's/its/
> 

Thanks!

-- 
Kaartic

Re: [RFC PATCH v2 2/5] branch: re-order function arguments to group related arguments

[Kaartic Sivaraam]

On Fri, 2017-10-20 at 14:50 -0700, Stefan Beller wrote:
> On Mon, Sep 25, 2017 at 1:20 AM, Kaartic Sivaraam
> <kaartic.sivaraam@gmail.com> wrote:
> > The ad-hoc patches to add new arguments to a function when needed
> > resulted in the related arguments not being close to each other.
> > This misleads the person reading the code to believe that there isn't
> > much relation between those arguments while it's not the case.
> > 
> > So, re-order the arguments to keep the related arguments close to each
> > other.
> 
> Thanks for taking a lot at the code quality in detail.
> 
> In my currently checked out version of Git, there are two occurrences
> of create_branch in builtin/branch.c, this patch converts only one occurrence.
> 
> (So you'd need to convert that second one, too. Oh wait; it is converted
> implicitly as the arguments are both '0':
>     create_branch(branch->name, new_upstream, 0, 0, 0, \
>         quiet, BRANCH_TRACK_OVERRIDE);
> )
> 
> This leads to the generic problem of this patch: Assume there are other
> contributors that write patches. They may introduce new calls to
> `create_branch`, but using the order of parameters as they may
> be unaware of this patch and they'd test without this patch.
> 
> As the signature of the function call doesn't change the compiler
> doesn't assist us in finding such a potential race between patches.
> 
> I am not aware of any other patches in flight, so we *might* be fine
> with this patch. But hope is rarely a good strategy.
> 
> Can we change the function signature (the name or another order
> of arguments that also makes sense, or making one of the
> parameters an enum) such that a potential race can be detected
> easier?
> 

I don't have a great interest in keeping this patch in case it might
conflict with other patches. Anyways, I guess we could avoid the issue
by making the last 'enum' parameter as the third parameter. It pretty
well changes the order by moving the flag-like parameters to the last
but it doesn't change the signature very strongly as you can pass
integers in the place of enums. (I guess that also obviates the
suggestion of making one parameter an enum)

So, the only way around is to rename the function which is something I
wouldn't like to do myself unless other people like the idea. So,
should I drop this patch or should I rename the function?


-- 
Kaartic

Re: [RFC PATCH v2 2/5] branch: re-order function arguments to group related arguments

[Stefan Beller]

On Fri, Oct 20, 2017 at 7:56 PM, Kaartic Sivaraam
<kaartic.sivaraam@gmail.com> wrote:
> On Fri, 2017-10-20 at 14:50 -0700, Stefan Beller wrote:
>> On Mon, Sep 25, 2017 at 1:20 AM, Kaartic Sivaraam
>> <kaartic.sivaraam@gmail.com> wrote:
>> > The ad-hoc patches to add new arguments to a function when needed
>> > resulted in the related arguments not being close to each other.
>> > This misleads the person reading the code to believe that there isn't
>> > much relation between those arguments while it's not the case.
>> >
>> > So, re-order the arguments to keep the related arguments close to each
>> > other.
>>
>> Thanks for taking a lot at the code quality in detail.
>>
>> In my currently checked out version of Git, there are two occurrences
>> of create_branch in builtin/branch.c, this patch converts only one occurrence.
>>
>> (So you'd need to convert that second one, too. Oh wait; it is converted
>> implicitly as the arguments are both '0':
>>     create_branch(branch->name, new_upstream, 0, 0, 0, \
>>         quiet, BRANCH_TRACK_OVERRIDE);
>> )
>>
>> This leads to the generic problem of this patch: Assume there are other
>> contributors that write patches. They may introduce new calls to
>> `create_branch`, but using the order of parameters as they may
>> be unaware of this patch and they'd test without this patch.
>>
>> As the signature of the function call doesn't change the compiler
>> doesn't assist us in finding such a potential race between patches.
>>
>> I am not aware of any other patches in flight, so we *might* be fine
>> with this patch. But hope is rarely a good strategy.
>>
>> Can we change the function signature (the name or another order
>> of arguments that also makes sense, or making one of the
>> parameters an enum) such that a potential race can be detected
>> easier?
>>
>
> I don't have a great interest in keeping this patch in case it might
> conflict with other patches. Anyways, I guess we could avoid the issue
> by making the last 'enum' parameter as the third parameter. It pretty
> well changes the order by moving the flag-like parameters to the last
> but it doesn't change the signature very strongly as you can pass
> integers in the place of enums. (I guess that also obviates the
> suggestion of making one parameter an enum)
>
> So, the only way around is to rename the function which is something I
> wouldn't like to do myself unless other people like the idea. So,
> should I drop this patch or should I rename the function?

Well let's keep the patch and closely watch next/pu to see if there might
topics that conflict, then. I do really like these small fixes to make the
code more readable. e.g.

  $ git log --oneline origin/master..origin/pu  -G create_branch

Re: [RFC PATCH v2 5/5] builtin/branch: give more useful error messages when renaming

[Stefan Beller]

On Mon, Sep 25, 2017 at 1:20 AM, Kaartic Sivaraam
<kaartic.sivaraam@gmail.com> wrote:
>  builtin/branch.c | 41 +++++++++++++++++++++++++++++++++++------
>  1 file changed, 35 insertions(+), 6 deletions(-)

The code of 4 and 5 looks good to me, though a small nit below.

Thanks,
Stefan


> +static void get_error_msg(struct strbuf* error_msg, const char* oldname, unsigned old_branch_exists,
> +                         const char* newname, int new_branch_validation_result)

nit here and in the return of validate_branch_creation:
It would be clearer if this is not just 'int', but actually spelling
out that it is the enum.

Re: [RFC PATCH v2 5/5] builtin/branch: give more useful error messages when renaming

[Kaartic Sivaraam]

On Mon, 2017-10-23 at 12:44 -0700, Stefan Beller wrote:
> +static void get_error_msg(struct strbuf* error_msg, const char* oldname, unsigned old_branch_exists,
> > +                         const char* newname, int new_branch_validation_result)
> 
> nit here and in the return of validate_branch_creation:
> It would be clearer if this is not just 'int', but actually spelling
> out that it is the enum.

Thanks. That's a good suggestion. I'll fix it while dropping [PATCH
3/5] that cleans up the 'validate_new_branchname' function as there's
already another series that refactored the same function and got merged
to 'next',

https://public-inbox.org/git/20171013051132.3973-1-gitster@pobox.com/


-- 
Kaartic

[RFC PATCH v3 0/4] give more useful error messages while renaming branch

[Kaartic Sivaraam]

In builtin/branch, the error messages weren't handled directly by the branch
renaming function and was left to the other function. Though this avoids
redundancy this gave unclear error messages in some cases. So, make builtin/branch
give more useful error messages.

Changes in v3:

	Incorporated suggestions from v2 to improve code and commit message. To
	be more precise about the code part,

	In 2/4 slightly re-ordered the parameters to move the flag parameters to
	the end.

	In 3/4, changed the return type of the branchname validation functions to
	be the enum (whose values they return) as suggested by Stefan.

	Dropped the PATCH 3/5 of v2 as there was another series[1] that did the
	refactor and got merged to 'next'. I have now re-rolled the series over
	'next' [pointing at 273055501 (Sync with master, 2017-10-24)].
 
	This has made the code in 3/4 a little clumsy (at least to me) as I
	tried to achieve to achieve what the previous patches did with the new
	validate*_branchname functionS. Let me know, if it looks too bad.

So this could go on top of 'next' without any conflicts but in case I
missed something, let me know. The series could be found in my fork[2].


Any feedback welcome.

Thanks,
Kaartic

[1] : https://public-inbox.org/git/20171013051132.3973-1-gitster@pobox.com

[2] : https://github.com/sivaraam/git/tree/work/branch-revamp


Kaartic Sivaraam (4):
  branch: improve documentation and naming of 'create_branch()'
  branch: re-order function arguments to group related arguments
  branch: introduce dont_fail parameter for branchname validation
  builtin/branch: give more useful error messages when renaming

 branch.c           | 63 ++++++++++++++++++++++++++++++------------------------
 branch.h           | 57 ++++++++++++++++++++++++++++++++++++++----------
 builtin/branch.c   | 49 ++++++++++++++++++++++++++++++++++--------
 builtin/checkout.c | 11 +++++-----
 4 files changed, 127 insertions(+), 53 deletions(-)

-- 
2.15.0.rc2.401.g3db9995f9

[RFC PATCH v3 1/4] branch: improve documentation and naming of 'create_branch()'

[Kaartic Sivaraam]

From: Kaartic Sivaraam <kaarticsivaraam91196@gmail.com>

The documentation for 'create_branch()' was incomplete as it didn't say
what certain parameters were used for. Further a parameter name wasn't
very communicative.

So, add missing documentation for the sake of completeness and easy
reference. Also, rename the concerned parameter to make its name more
communicative.

Signed-off-by: Kaartic Sivaraam <kaarticsivaraam91196@gmail.com>
---
 branch.c | 4 ++--
 branch.h | 7 ++++++-
 2 files changed, 8 insertions(+), 3 deletions(-)

diff --git a/branch.c b/branch.c
index fe1e1c367..ea6e2b359 100644
--- a/branch.c
+++ b/branch.c
@@ -244,7 +244,7 @@ N_("\n"
 "\"git push -u\" to set the upstream config as you push.");
 
 void create_branch(const char *name, const char *start_name,
-		   int force, int reflog, int clobber_head,
+		   int force, int reflog, int clobber_head_ok,
 		   int quiet, enum branch_track track)
 {
 	struct commit *commit;
@@ -258,7 +258,7 @@ void create_branch(const char *name, const char *start_name,
 	if (track == BRANCH_TRACK_EXPLICIT || track == BRANCH_TRACK_OVERRIDE)
 		explicit_tracking = 1;
 
-	if ((track == BRANCH_TRACK_OVERRIDE || clobber_head)
+	if ((track == BRANCH_TRACK_OVERRIDE || clobber_head_ok)
 	    ? validate_branchname(name, &ref)
 	    : validate_new_branchname(name, &ref, force)) {
 		if (!force)
diff --git a/branch.h b/branch.h
index be5e5d130..1512b78d1 100644
--- a/branch.h
+++ b/branch.h
@@ -15,12 +15,17 @@
  *
  *   - reflog creates a reflog for the branch
  *
+ *   - clobber_head_ok allows the currently checked out (hence existing)
+ *     branch to be overwritten; without 'force', it has no effect.
+ *
+ *   - quiet suppresses tracking information
+ *
  *   - track causes the new branch to be configured to merge the remote branch
  *     that start_name is a tracking branch for (if any).
  */
 void create_branch(const char *name, const char *start_name,
 		   int force, int reflog,
-		   int clobber_head, int quiet, enum branch_track track);
+		   int clobber_head_ok, int quiet, enum branch_track track);
 
 /*
  * Check if 'name' can be a valid name for a branch; die otherwise.
-- 
2.15.0.461.gf957c703b.dirty

[RFC PATCH v3 2/4] branch: re-order function arguments to group related arguments

[Kaartic Sivaraam]

From: Kaartic Sivaraam <kaarticsivaraam91196@gmail.com>

The ad-hoc patches to add new arguments to a function when needed
resulted in the related arguments not being close to each other.
This misleads the person reading the code to believe that there isn't
much relation between those arguments while it's not the case.

So, re-order the arguments to keep the related arguments close to each
other.

Signed-off-by: Kaartic Sivaraam <kaarticsivaraam91196@gmail.com>
---
 branch.c           |  4 ++--
 branch.h           | 14 +++++++-------
 builtin/branch.c   |  4 ++--
 builtin/checkout.c |  6 +++---
 4 files changed, 14 insertions(+), 14 deletions(-)

diff --git a/branch.c b/branch.c
index ea6e2b359..7c8093041 100644
--- a/branch.c
+++ b/branch.c
@@ -244,8 +244,8 @@ N_("\n"
 "\"git push -u\" to set the upstream config as you push.");
 
 void create_branch(const char *name, const char *start_name,
-		   int force, int reflog, int clobber_head_ok,
-		   int quiet, enum branch_track track)
+		   enum branch_track track, int force, int clobber_head_ok,
+		   int reflog, int quiet)
 {
 	struct commit *commit;
 	struct object_id oid;
diff --git a/branch.h b/branch.h
index 1512b78d1..85052628b 100644
--- a/branch.h
+++ b/branch.h
@@ -11,21 +11,21 @@
  *   - start_name is the name of the existing branch that the new branch should
  *     start from
  *
- *   - force enables overwriting an existing (non-head) branch
+ *   - track causes the new branch to be configured to merge the remote branch
+ *     that start_name is a tracking branch for (if any).
  *
- *   - reflog creates a reflog for the branch
+ *   - force enables overwriting an existing (non-head) branch
  *
  *   - clobber_head_ok allows the currently checked out (hence existing)
  *     branch to be overwritten; without 'force', it has no effect.
  *
- *   - quiet suppresses tracking information
+ *   - reflog creates a reflog for the branch
  *
- *   - track causes the new branch to be configured to merge the remote branch
- *     that start_name is a tracking branch for (if any).
+ *   - quiet suppresses tracking information
  */
 void create_branch(const char *name, const char *start_name,
-		   int force, int reflog,
-		   int clobber_head_ok, int quiet, enum branch_track track);
+		   enum branch_track track, int force, int clobber_head_ok,
+		   int reflog, int quiet);
 
 /*
  * Check if 'name' can be a valid name for a branch; die otherwise.
diff --git a/builtin/branch.c b/builtin/branch.c
index 5be40b384..df06ac968 100644
--- a/builtin/branch.c
+++ b/builtin/branch.c
@@ -766,7 +766,7 @@ int cmd_branch(int argc, const char **argv, const char *prefix)
 		 * create_branch takes care of setting up the tracking
 		 * info and making sure new_upstream is correct
 		 */
-		create_branch(branch->name, new_upstream, 0, 0, 0, quiet, BRANCH_TRACK_OVERRIDE);
+		create_branch(branch->name, new_upstream, BRANCH_TRACK_OVERRIDE, 0, 0, 0, quiet);
 	} else if (unset_upstream) {
 		struct branch *branch = branch_get(argv[0]);
 		struct strbuf buf = STRBUF_INIT;
@@ -806,7 +806,7 @@ int cmd_branch(int argc, const char **argv, const char *prefix)
 			die(_("the '--set-upstream' option is no longer supported. Please use '--track' or '--set-upstream-to' instead."));
 
 		create_branch(argv[0], (argc == 2) ? argv[1] : head,
-			      force, reflog, 0, quiet, track);
+			      track, force, 0, reflog, quiet);
 
 	} else
 		usage_with_options(builtin_branch_usage, options);
diff --git a/builtin/checkout.c b/builtin/checkout.c
index 8546d630b..5c34a9a0d 100644
--- a/builtin/checkout.c
+++ b/builtin/checkout.c
@@ -639,11 +639,11 @@ static void update_refs_for_switch(const struct checkout_opts *opts,
 		}
 		else
 			create_branch(opts->new_branch, new->name,
+				      opts->track,
+				      opts->new_branch_force ? 1 : 0,
 				      opts->new_branch_force ? 1 : 0,
 				      opts->new_branch_log,
-				      opts->new_branch_force ? 1 : 0,
-				      opts->quiet,
-				      opts->track);
+				      opts->quiet);
 		new->name = opts->new_branch;
 		setup_branch_path(new);
 	}
-- 
2.15.0.461.gf957c703b.dirty

[RFC PATCH v3 3/4] branch: introduce dont_fail parameter for branchname validation

[Kaartic Sivaraam]

This parameter allows the branchname validation functions to
optionally return a flag specifying the reason for failure, when
requested. This allows the caller to know why it was about to die.
This allows more useful error messages to be given to the user when
trying to rename a branch.

The flags are specified in the form of an enum and values for success
flags have been assigned explicitly to clearly express that certain
callers rely on those values and they cannot be arbitrary.

Only the logic has been added but no caller has been made to use it, yet.
So, no functional changes.

Signed-off-by: Kaartic Sivaraam <kaarticsivaraam91196@gmail.com>
Signed-off-by: Kaartic Sivaraam <kaartic.sivaraam@gmail.com>
---
 branch.c           | 62 +++++++++++++++++++++++++++++++-----------------------
 branch.h           | 60 ++++++++++++++++++++++++++++++++++++++++++----------
 builtin/branch.c   |  4 ++--
 builtin/checkout.c |  5 +++--
 4 files changed, 90 insertions(+), 41 deletions(-)

diff --git a/branch.c b/branch.c
index 7c8093041..7db2e3296 100644
--- a/branch.c
+++ b/branch.c
@@ -178,41 +178,51 @@ int read_branch_desc(struct strbuf *buf, const char *branch_name)
 	return 0;
 }
 
-/*
- * Check if 'name' can be a valid name for a branch; die otherwise.
- * Return 1 if the named branch already exists; return 0 otherwise.
- * Fill ref with the full refname for the branch.
- */
-int validate_branchname(const char *name, struct strbuf *ref)
+enum branch_validation_result validate_branchname(const char *name, struct strbuf *ref, unsigned dont_fail)
 {
-	if (strbuf_check_branch_ref(ref, name))
-		die(_("'%s' is not a valid branch name."), name);
+	if (strbuf_check_branch_ref(ref, name)) {
+		if (dont_fail)
+			return INVALID_BRANCH_NAME;
+		else
+			die(_("'%s' is not a valid branch name."), name);
+	}
 
-	return ref_exists(ref->buf);
+	if(ref_exists(ref->buf))
+		return BRANCH_EXISTS;
+	else
+		return BRANCH_DOESNT_EXIST;
 }
 
-/*
- * Check if a branch 'name' can be created as a new branch; die otherwise.
- * 'force' can be used when it is OK for the named branch already exists.
- * Return 1 if the named branch already exists; return 0 otherwise.
- * Fill ref with the full refname for the branch.
- */
-int validate_new_branchname(const char *name, struct strbuf *ref, int force)
+enum branch_validation_result validate_new_branchname(const char *name, struct strbuf *ref, int force, unsigned dont_fail)
 {
 	const char *head;
 
-	if (!validate_branchname(name, ref))
-		return 0;
+	if(dont_fail) {
+		enum branch_validation_result res = validate_branchname(name, ref, 1);
+		if (res == INVALID_BRANCH_NAME || res == BRANCH_DOESNT_EXIST)
+				return res;
+	} else {
+		if(validate_branchname(name, ref, 0) == BRANCH_DOESNT_EXIST)
+			return BRANCH_DOESNT_EXIST;
+	}
 
-	if (!force)
-		die(_("A branch named '%s' already exists."),
-		    ref->buf + strlen("refs/heads/"));
+	if (!force) {
+		if (dont_fail)
+			return BRANCH_EXISTS_NO_FORCE;
+		else
+			die(_("A branch named '%s' already exists."),
+				ref->buf + strlen("refs/heads/"));
+	}
 
 	head = resolve_ref_unsafe("HEAD", 0, NULL, NULL);
-	if (!is_bare_repository() && head && !strcmp(head, ref->buf))
-		die(_("Cannot force update the current branch."));
+	if (!is_bare_repository() && head && !strcmp(head, ref->buf)) {
+		if (dont_fail)
+			return CANNOT_FORCE_UPDATE_CURRENT_BRANCH;
+		else
+			die(_("Cannot force update the current branch."));
+	}
 
-	return 1;
+	return BRANCH_EXISTS;
 }
 
 static int check_tracking_branch(struct remote *remote, void *cb_data)
@@ -259,8 +269,8 @@ void create_branch(const char *name, const char *start_name,
 		explicit_tracking = 1;
 
 	if ((track == BRANCH_TRACK_OVERRIDE || clobber_head_ok)
-	    ? validate_branchname(name, &ref)
-	    : validate_new_branchname(name, &ref, force)) {
+	    ? validate_branchname(name, &ref, 0)
+	    : validate_new_branchname(name, &ref, force, 0)) {
 		if (!force)
 			dont_change_ref = 1;
 		else
diff --git a/branch.h b/branch.h
index 85052628b..0c178ec5a 100644
--- a/branch.h
+++ b/branch.h
@@ -27,20 +27,58 @@ void create_branch(const char *name, const char *start_name,
 		   enum branch_track track, int force, int clobber_head_ok,
 		   int reflog, int quiet);
 
-/*
- * Check if 'name' can be a valid name for a branch; die otherwise.
- * Return 1 if the named branch already exists; return 0 otherwise.
- * Fill ref with the full refname for the branch.
- */
-extern int validate_branchname(const char *name, struct strbuf *ref);
+enum branch_validation_result {
+	/* Flags that convey that validation FAILED */
+	BRANCH_EXISTS_NO_FORCE = -3,
+	CANNOT_FORCE_UPDATE_CURRENT_BRANCH,
+	INVALID_BRANCH_NAME,
+	/* Flags that convey that validation SUCCEEDED */
+	BRANCH_DOESNT_EXIST = 0,
+	BRANCH_EXISTS = 1,
+};
 
 /*
- * Check if a branch 'name' can be created as a new branch; die otherwise.
- * 'force' can be used when it is OK for the named branch already exists.
- * Return 1 if the named branch already exists; return 0 otherwise.
- * Fill ref with the full refname for the branch.
+ * Check if 'name' can be a valid name for a branch; die otherwise.
+ *
+ *   - name is the new branch name
+ *
+ *   - ref is used to return the full refname for the branch
+ *
+ * The return values have the following meaning,
+ *
+ *   - If dont_fail is 0, the function dies in case of failure and returns flags of
+ *     'branch_validation_result' that indicate status of the given branch. The positive
+ *     non-zero flag implies that the branch exists.
+ *
+ *   - If dont_fail is 1, the function doesn't die in case of failure but returns flags
+ *     of 'branch_validaton_result' that specify the reason for failure. The behaviour in case of
+ *     success is same as above.
+ *
  */
-extern int validate_new_branchname(const char *name, struct strbuf *ref, int force);
+extern enum branch_validation_result validate_branchname(const char *name, struct strbuf *ref, unsigned dont_fail);
+
+/*
+ * Check if a branch 'name' can be created as a new branch.
+ *
+ *   - name is the new branch name
+ *
+ *   - ref is used to return the full refname for the branch
+ *
+ *   - force can be used when it is OK if the named branch already exists.
+ *     the currently checkout branch; with 'shouldnt_exist', it has no effect.
+ *
+ * The return values have the following meaning,
+ *
+ *   - If dont_fail is 0, the function dies in case of failure and returns flags of
+ *     'branch_validation_result' that indicate that convey status of given branch. The positive
+ *     non-zero flag implies that the branch can be force updated.
+ *
+ *   - If dont_fail is 1, the function doesn't die in case of failure but returns flags
+ *     of 'branch_validaton_result' that specify the reason for failure. The behaviour in case of
+ *     success is same as above.
+ *
+ */
+extern enum branch_validation_result validate_new_branchname(const char *name, struct strbuf *ref, int force, unsigned dont_fail);
 
 /*
  * Remove information about the state of working on the current
diff --git a/builtin/branch.c b/builtin/branch.c
index df06ac968..7018e5d75 100644
--- a/builtin/branch.c
+++ b/builtin/branch.c
@@ -487,9 +487,9 @@ static void copy_or_rename_branch(const char *oldname, const char *newname, int
 	 * cause the worktree to become inconsistent with HEAD, so allow it.
 	 */
 	if (!strcmp(oldname, newname))
-		validate_branchname(newname, &newref);
+		validate_branchname(newname, &newref, 0);
 	else
-		validate_new_branchname(newname, &newref, force);
+		validate_new_branchname(newname, &newref, force, 0);
 
 	reject_rebase_or_bisect_branch(oldref.buf);
 
diff --git a/builtin/checkout.c b/builtin/checkout.c
index 5c34a9a0d..4adab3814 100644
--- a/builtin/checkout.c
+++ b/builtin/checkout.c
@@ -1288,10 +1288,11 @@ int cmd_checkout(int argc, const char **argv, const char *prefix)
 		struct strbuf buf = STRBUF_INIT;
 
 		if (opts.new_branch_force)
-			opts.branch_exists = validate_branchname(opts.new_branch, &buf);
+			opts.branch_exists = validate_branchname(opts.new_branch, &buf, 0);
 		else
 			opts.branch_exists =
-				validate_new_branchname(opts.new_branch, &buf, 0);
+				validate_new_branchname(opts.new_branch, &buf, 0, 0);
+
 		strbuf_release(&buf);
 	}
 
-- 
2.15.0.461.gf957c703b.dirty

[RFC PATCH v3 4/4] builtin/branch: give more useful error messages when renaming

[Kaartic Sivaraam]

From: Kaartic Sivaraam <kaarticsivaraam91196@gmail.com>

When trying to rename an inexistent branch to with a name of a branch
that already exists the rename failed specifying the new branch name
exists rather than specifying that the branch trying to be renamed
doesn't exist.

    $ git branch -m tset master
    fatal: A branch named 'master' already exists.

It's conventional to report that 'tset' doesn't exist rather than
reporting that 'master' exists, the same way the 'mv' command does.

    (hypothetical)
    $ git branch -m tset master
    fatal: branch 'tset' doesn't exist.

That has the problem that the error about an existing branch is shown
only after the user corrects the error about inexistent branch.

    $ git branch -m test master
    fatal: A branch named 'master' already exists.

This isn't useful either because the user would have corrected this error in
a single go if he had been told this alongside the first error. So, give
more useful error messages by giving errors about old branch name and new
branch name at the same time. This is possible as the branch name validation
functions now return the reason they were about to die, when requested.

    $ git branch -m tset master
    fatal: branch 'tset' doesn't exist, and branch 'master' already exists

Note: Thanks to the strbuf API that made it possible to easily construct
the composite error message strings!

Signed-off-by: Kaartic Sivaraam <kaarticsivaraam91196@gmail.com>
---
 builtin/branch.c | 49 ++++++++++++++++++++++++++++++++++++++++++-------
 1 file changed, 42 insertions(+), 7 deletions(-)

diff --git a/builtin/branch.c b/builtin/branch.c
index 7018e5d75..c2bbf8c3d 100644
--- a/builtin/branch.c
+++ b/builtin/branch.c
@@ -458,11 +458,42 @@ static void reject_rebase_or_bisect_branch(const char *target)
 	free_worktrees(worktrees);
 }
 
+static void get_error_msg(struct strbuf* error_msg, const char* oldname, unsigned old_branch_exists,
+			  const char* newname, enum branch_validation_result res)
+{
+	const char* connector_string = _(", and ");
+
+	if (!old_branch_exists) {
+		strbuf_addf(error_msg, _("branch '%s' doesn't exist"), oldname);
+	}
+
+	switch (res) {
+		case BRANCH_EXISTS_NO_FORCE:
+			strbuf_addf(error_msg, "%s", (!old_branch_exists) ? connector_string : "");
+			strbuf_addf(error_msg,_("branch '%s' already exists"), newname);
+			break;
+		case CANNOT_FORCE_UPDATE_CURRENT_BRANCH:
+			strbuf_addf(error_msg, "%s", (!old_branch_exists) ? connector_string : "");
+			strbuf_addstr(error_msg, _("cannot force update the current branch"));
+			break;
+		case INVALID_BRANCH_NAME:
+			strbuf_addf(error_msg, "%s", (!old_branch_exists) ? connector_string : "");
+			strbuf_addf(error_msg, _("branch name '%s' is invalid"), newname);
+			break;
+		/* not necessary to handle success cases */
+		case BRANCH_EXISTS:
+		case BRANCH_DOESNT_EXIST:
+			break;
+	}
+}
+
 static void copy_or_rename_branch(const char *oldname, const char *newname, int copy, int force)
 {
 	struct strbuf oldref = STRBUF_INIT, newref = STRBUF_INIT, logmsg = STRBUF_INIT;
 	struct strbuf oldsection = STRBUF_INIT, newsection = STRBUF_INIT;
 	int recovery = 0;
+	struct strbuf error_msg = STRBUF_INIT, empty = STRBUF_INIT;
+	enum branch_validation_result res;
 
 	if (!oldname) {
 		if (copy)
@@ -471,15 +502,13 @@ static void copy_or_rename_branch(const char *oldname, const char *newname, int
 			die(_("cannot rename the current branch while not on any."));
 	}
 
-	if (strbuf_check_branch_ref(&oldref, oldname)) {
+	if (strbuf_check_branch_ref(&oldref, oldname) && ref_exists(oldref.buf))
+	{
 		/*
 		 * Bad name --- this could be an attempt to rename a
 		 * ref that we used to allow to be created by accident.
 		 */
-		if (ref_exists(oldref.buf))
-			recovery = 1;
-		else
-			die(_("Invalid branch name: '%s'"), oldname);
+		recovery = 1;
 	}
 
 	/*
@@ -487,9 +516,13 @@ static void copy_or_rename_branch(const char *oldname, const char *newname, int
 	 * cause the worktree to become inconsistent with HEAD, so allow it.
 	 */
 	if (!strcmp(oldname, newname))
-		validate_branchname(newname, &newref, 0);
+		res = validate_branchname(newname, &newref, 1);
 	else
-		validate_new_branchname(newname, &newref, force, 0);
+		res = validate_new_branchname(newname, &newref, force, 1);
+
+	get_error_msg(&error_msg, oldname, ref_exists(oldref.buf), newname, res);
+	if (strbuf_cmp(&error_msg, &empty))
+		die("%s", error_msg.buf);
 
 	reject_rebase_or_bisect_branch(oldref.buf);
 
@@ -530,6 +563,8 @@ static void copy_or_rename_branch(const char *oldname, const char *newname, int
 		die(_("Branch is copied, but update of config-file failed"));
 	strbuf_release(&oldsection);
 	strbuf_release(&newsection);
+	strbuf_release(&error_msg);
+	strbuf_release(&empty);
 }
 
 static GIT_PATH_FUNC(edit_description, "EDIT_DESCRIPTION")
-- 
2.15.0.461.gf957c703b.dirty

Re: [RFC PATCH v3 3/4] branch: introduce dont_fail parameter for branchname validation

[Kaartic Sivaraam]

On Thursday 02 November 2017 12:24 PM, Kaartic Sivaraam wrote:
> Signed-off-by: Kaartic Sivaraam <kaarticsivaraam91196@gmail.com>
> Signed-off-by: Kaartic Sivaraam <kaartic.sivaraam@gmail.com>

I just now saw this small glitch as a consequence of recently
changing my email address. I would prefer to keep the second one
but as the other patches have the first one it's better to keep
the first one for now.

But wait, it seems that this commit also has a different author
identity (the email adress part). If this is a big enough issue,
I'll fix that and send a v4 (possibly with any other suggested
changes) else I'll leave it as it is.

BTW, I added the Ccs to this mail which I forgot to do when
sending the patches, hope it's not an issue.

---
Kaartic

Re: [RFC PATCH v3 4/4] builtin/branch: give more useful error messages when renaming

[Eric Sunshine]

On Thu, Nov 2, 2017 at 2:54 AM, Kaartic Sivaraam
<kaartic.sivaraam@gmail.com> wrote:
> From: Kaartic Sivaraam <kaarticsivaraam91196@gmail.com>
>
> When trying to rename an inexistent branch to with a name of a branch
> that already exists the rename failed specifying the new branch name
> exists rather than specifying that the branch trying to be renamed
> doesn't exist.
>
>     $ git branch -m tset master
>     fatal: A branch named 'master' already exists.
>
> It's conventional to report that 'tset' doesn't exist rather than
> reporting that 'master' exists, the same way the 'mv' command does.
>
>     (hypothetical)
>     $ git branch -m tset master
>     fatal: branch 'tset' doesn't exist.
>
> That has the problem that the error about an existing branch is shown
> only after the user corrects the error about inexistent branch.
>
>     $ git branch -m test master
>     fatal: A branch named 'master' already exists.
>
> This isn't useful either because the user would have corrected this error in
> a single go if he had been told this alongside the first error. So, give
> more useful error messages by giving errors about old branch name and new
> branch name at the same time. This is possible as the branch name validation
> functions now return the reason they were about to die, when requested.
>
>     $ git branch -m tset master
>     fatal: branch 'tset' doesn't exist, and branch 'master' already exists

Nicely explained; easily understood.

> Note: Thanks to the strbuf API that made it possible to easily construct
> the composite error message strings!

This may be a problem. See below...

> Signed-off-by: Kaartic Sivaraam <kaarticsivaraam91196@gmail.com>
> ---
> diff --git a/builtin/branch.c b/builtin/branch.c
> +static void get_error_msg(struct strbuf* error_msg, const char* oldname, unsigned old_branch_exists,
> +                         const char* newname, enum branch_validation_result res)
> +{
> +       const char* connector_string = _(", and ");
> +
> +       if (!old_branch_exists) {
> +               strbuf_addf(error_msg, _("branch '%s' doesn't exist"), oldname);
> +       }
> +
> +       switch (res) {
> +               case BRANCH_EXISTS_NO_FORCE:
> +                       strbuf_addf(error_msg, "%s", (!old_branch_exists) ? connector_string : "");
> +                       strbuf_addf(error_msg,_("branch '%s' already exists"), newname);
> +                       break;
> +               case CANNOT_FORCE_UPDATE_CURRENT_BRANCH:
> +                       strbuf_addf(error_msg, "%s", (!old_branch_exists) ? connector_string : "");
> +                       strbuf_addstr(error_msg, _("cannot force update the current branch"));
> +                       break;
> +               case INVALID_BRANCH_NAME:
> +                       strbuf_addf(error_msg, "%s", (!old_branch_exists) ? connector_string : "");
> +                       strbuf_addf(error_msg, _("branch name '%s' is invalid"), newname);
> +                       break;
> +               /* not necessary to handle success cases */
> +               case BRANCH_EXISTS:
> +               case BRANCH_DOESNT_EXIST:
> +                       break;
> +       }
> +}

Translators can correct me, but this smells like "sentence lego"[1],
which we'd like to avoid. Translators lack full context when presented
with bits and pieces of a sentence like this, thus the translation may
be of poor quality; it may even be entirely incorrect since they don't
necessarily know how you will be composing the various pieces.

You _might_ be able to able to resolve this by dropping "and" from:

    "foo is moo, and bar is boo"

to turn the error messages into independent clauses:

    "foo is moo; bar is boo"

but I'm no translator, and even that may fail the lego sniff test.

A sure-fire way to avoid lego construction would be simply to emit
each messages on its own line:

    fatal: branch 'tset' doesn't exist
    fatal: branch 'master' already exists

(though, you might consider that too ugly).

[1]: http://www.gnu.org/software/gettext/manual/gettext.html#Preparing-Strings

Re: [RFC PATCH v3 3/4] branch: introduce dont_fail parameter for branchname validation

[Stefan Beller]

On Thu, Nov 2, 2017 at 1:39 AM, Kaartic Sivaraam
<kaartic.sivaraam@gmail.com> wrote:
> On Thursday 02 November 2017 12:24 PM, Kaartic Sivaraam wrote:
>>
>> Signed-off-by: Kaartic Sivaraam <kaarticsivaraam91196@gmail.com>
>> Signed-off-by: Kaartic Sivaraam <kaartic.sivaraam@gmail.com>
>
>
> I just now saw this small glitch as a consequence of recently
> changing my email address. I would prefer to keep the second one
> but as the other patches have the first one it's better to keep
> the first one for now.

If you prefer one of them, you may have incentive to
add an entry into .mailmap file, otherwise I'd kindly ask you
to. :) (c.f. `git log --no-merges -- .mailmap`)

> But wait, it seems that this commit also has a different author
> identity (the email adress part). If this is a big enough issue,
> I'll fix that and send a v4 (possibly with any other suggested
> changes) else I'll leave it as it is.
>
> BTW, I added the Ccs to this mail which I forgot to do when
> sending the patches, hope it's not an issue.

Re: [RFC PATCH v3 4/4] builtin/branch: give more useful error messages when renaming

[Kaartic Sivaraam]

On Thursday 02 November 2017 07:51 PM, Eric Sunshine wrote:
> 
> Nicely explained; easily understood.
>

Good to hear that.


> 
> Translators can correct me, but this smells like "sentence lego"[1],
> which we'd like to avoid. Translators lack full context when presented
> with bits and pieces of a sentence like this, thus the translation may
> be of poor quality; it may even be entirely incorrect since they don't
> necessarily know how you will be composing the various pieces.
> 
> You _might_ be able to able to resolve this by dropping "and" from:
> 
>      "foo is moo, and bar is boo"
> 
> to turn the error messages into independent clauses:
> 
>      "foo is moo; bar is boo"
> > but I'm no translator, and even that may fail the lego sniff test.
> 
Though I can't be very sure that the one you suggested will pass the 
"lego sniff test", its better than the "and" I used. Further, my 
instinct says it wouldn't qualify as sentence lego (it's just a ";").


> A sure-fire way to avoid lego construction would be simply to emit
> each messages on its own line:
> 
>      fatal: branch 'tset' doesn't exist
>      fatal: branch 'master' already exists
> 
> (though, you might consider that too ugly).
>

Though it might not look that ugly, I don't know how you could make 
'git' die() twice (or am I missing something)! Of course we could use 
'error()' to report the errors and then 'die()' with a message like 
"Branch rename failed" but I find that to be a little too verbose and 
further using the connector ";" instead of "and" does seem to reduce the 
possibilities for the above program fragment to pass the "lego sniff test".

---
Kaartic

Re: [RFC PATCH v3 3/4] branch: introduce dont_fail parameter for branchname validation

[Kaartic Sivaraam]

On Friday 03 November 2017 12:12 AM, Stefan Beller wrote:
> On Thu, Nov 2, 2017 at 1:39 AM, Kaartic Sivaraam
> <kaartic.sivaraam@gmail.com> wrote:
>> On Thursday 02 November 2017 12:24 PM, Kaartic Sivaraam wrote:
>>>
>>> Signed-off-by: Kaartic Sivaraam <kaarticsivaraam91196@gmail.com>
>>> Signed-off-by: Kaartic Sivaraam <kaartic.sivaraam@gmail.com>
>>
>>
>> I just now saw this small glitch as a consequence of recently
>> changing my email address. I would prefer to keep the second one
>> but as the other patches have the first one it's better to keep
>> the first one for now.
> 
> If you prefer one of them, you may have incentive to
> add an entry into .mailmap file, otherwise I'd kindly ask you
> to. :) (c.f. `git log --no-merges -- .mailmap`)
> 

Sure, I'll do that. My intuition says this doesn't remove the duplicated 
  sign-off line. Anyways, there's for sure a v4 that's going to update 
the connector string in [4/4] and another update. I'll be careful to 
address these issues in v4.

---
Kaartic

Re: [RFC PATCH v3 2/4] branch: re-order function arguments to group related arguments

[Junio C Hamano]

Kaartic Sivaraam <kaartic.sivaraam@gmail.com> writes:

> From: Kaartic Sivaraam <kaarticsivaraam91196@gmail.com>
>
> The ad-hoc patches to add new arguments to a function when needed
> resulted in the related arguments not being close to each other.
> This misleads the person reading the code to believe that there isn't
> much relation between those arguments while it's not the case.

I do not get what this wants to say.  "I am sending this ad-hoc
patch that scrambles the order of parameters for no real reason" is
certainly not how you are selling this step.

> So, re-order the arguments to keep the related arguments close to each
> other.

This sentence (without "So,", obviously, because I do not get the
previous paragraph) I do understand and agree with as a goal.

I think the only two things that should be kept together are "force"
and "clobber_head_ok" because the previous 1/4 changed the meaning
of "clobber_head" to "it is OK if I am renaming the currently
checked-out branch", i.e. closer to what "force" means.

I certainly would not mind the order used in the result of this
patch (in other words, if somebody posted a patch to add
create_branch() function to the codebase that lacked it, with its
parameters listed in the order this patch uses, I wouldn't
complain), but it would have equally been OK if "reflog" and "force"
were swapped without making any other change this patch makes.

I dunno.

> Signed-off-by: Kaartic Sivaraam <kaarticsivaraam91196@gmail.com>
> ---
>  branch.c           |  4 ++--
>  branch.h           | 14 +++++++-------
>  builtin/branch.c   |  4 ++--
>  builtin/checkout.c |  6 +++---
>  4 files changed, 14 insertions(+), 14 deletions(-)
>
> diff --git a/branch.c b/branch.c
> index ea6e2b359..7c8093041 100644
> --- a/branch.c
> +++ b/branch.c
> @@ -244,8 +244,8 @@ N_("\n"
>  "\"git push -u\" to set the upstream config as you push.");
>  
>  void create_branch(const char *name, const char *start_name,
> -		   int force, int reflog, int clobber_head_ok,
> -		   int quiet, enum branch_track track)
> +		   enum branch_track track, int force, int clobber_head_ok,
> +		   int reflog, int quiet)
>  {
>  	struct commit *commit;
>  	struct object_id oid;
> diff --git a/branch.h b/branch.h
> index 1512b78d1..85052628b 100644
> --- a/branch.h
> +++ b/branch.h
> @@ -11,21 +11,21 @@
>   *   - start_name is the name of the existing branch that the new branch should
>   *     start from
>   *
> - *   - force enables overwriting an existing (non-head) branch
> + *   - track causes the new branch to be configured to merge the remote branch
> + *     that start_name is a tracking branch for (if any).
>   *
> - *   - reflog creates a reflog for the branch
> + *   - force enables overwriting an existing (non-head) branch
>   *
>   *   - clobber_head_ok allows the currently checked out (hence existing)
>   *     branch to be overwritten; without 'force', it has no effect.
>   *
> - *   - quiet suppresses tracking information
> + *   - reflog creates a reflog for the branch
>   *
> - *   - track causes the new branch to be configured to merge the remote branch
> - *     that start_name is a tracking branch for (if any).
> + *   - quiet suppresses tracking information
>   */
>  void create_branch(const char *name, const char *start_name,
> -		   int force, int reflog,
> -		   int clobber_head_ok, int quiet, enum branch_track track);
> +		   enum branch_track track, int force, int clobber_head_ok,
> +		   int reflog, int quiet);
>  
>  /*
>   * Check if 'name' can be a valid name for a branch; die otherwise.
> diff --git a/builtin/branch.c b/builtin/branch.c
> index 5be40b384..df06ac968 100644
> --- a/builtin/branch.c
> +++ b/builtin/branch.c
> @@ -766,7 +766,7 @@ int cmd_branch(int argc, const char **argv, const char *prefix)
>  		 * create_branch takes care of setting up the tracking
>  		 * info and making sure new_upstream is correct
>  		 */
> -		create_branch(branch->name, new_upstream, 0, 0, 0, quiet, BRANCH_TRACK_OVERRIDE);
> +		create_branch(branch->name, new_upstream, BRANCH_TRACK_OVERRIDE, 0, 0, 0, quiet);
>  	} else if (unset_upstream) {
>  		struct branch *branch = branch_get(argv[0]);
>  		struct strbuf buf = STRBUF_INIT;
> @@ -806,7 +806,7 @@ int cmd_branch(int argc, const char **argv, const char *prefix)
>  			die(_("the '--set-upstream' option is no longer supported. Please use '--track' or '--set-upstream-to' instead."));
>  
>  		create_branch(argv[0], (argc == 2) ? argv[1] : head,
> -			      force, reflog, 0, quiet, track);
> +			      track, force, 0, reflog, quiet);
>  
>  	} else
>  		usage_with_options(builtin_branch_usage, options);
> diff --git a/builtin/checkout.c b/builtin/checkout.c
> index 8546d630b..5c34a9a0d 100644
> --- a/builtin/checkout.c
> +++ b/builtin/checkout.c
> @@ -639,11 +639,11 @@ static void update_refs_for_switch(const struct checkout_opts *opts,
>  		}
>  		else
>  			create_branch(opts->new_branch, new->name,
> +				      opts->track,
> +				      opts->new_branch_force ? 1 : 0,
>  				      opts->new_branch_force ? 1 : 0,
>  				      opts->new_branch_log,
> -				      opts->new_branch_force ? 1 : 0,
> -				      opts->quiet,
> -				      opts->track);
> +				      opts->quiet);
>  		new->name = opts->new_branch;
>  		setup_branch_path(new);
>  	}

Re: [RFC PATCH v3 3/4] branch: introduce dont_fail parameter for branchname validation

[Junio C Hamano]

Kaartic Sivaraam <kaartic.sivaraam@gmail.com> writes:

> This parameter allows the branchname validation functions to
> optionally return a flag specifying the reason for failure, when
> requested. This allows the caller to know why it was about to die.
> This allows more useful error messages to be given to the user when
> trying to rename a branch.
>
> The flags are specified in the form of an enum and values for success
> flags have been assigned explicitly to clearly express that certain
> callers rely on those values and they cannot be arbitrary.
>
> Only the logic has been added but no caller has been made to use it, yet.
> So, no functional changes.

This step makes sense, and nicely done.

We usually use the word "gently" to when we enhance an operation
that used to always die on failure.  When there are tons of callsite
to the original operation F(), we introduce F_gently() variant and
do something like

	F(...)
	{
		if (F_gently(...))
			die(...);
	}

so that the callers do not have to change.  If there aren't that
many, it is OK to change the function signature of F() to tell it
not to die without adding a new F_gently() function, which is the
approach more appropriate for this change.  The extra parameter used
for that purpose should be called "gently", perhaps.

> +	if(ref_exists(ref->buf))
> +		return BRANCH_EXISTS;
> +	else
> +		return BRANCH_DOESNT_EXIST;

Always have SP between "if" (and other keyword like "while") and its
condition.

For this one, however, this might be easier to follow:

	return ref_exists(ref->buf) ? BRANCH_EXISTS : BRANCH_DOESNT_EXIST;

The names of the enum values may need further thought.  They must
clearly convey two things, in addition to what kind of status they
represent; the current names only convey the status.  From the names
of these values, it must be clear that they are part of the same
enum (e.g. by sharing a common prefix), and also from the names of
these values, it must be clear which ones are error conditions and
which are not, without knowing their actual values.  A reader cannot
immediately tell from "BRANCH_EXISTS" if that is a good thing or
not.

Other than that, looks fairly cleanly done.  I like what this step
wants to achieve.

Thanks.

Re: [RFC PATCH v3 4/4] builtin/branch: give more useful error messages when renaming

[Junio C Hamano]

Kaartic Sivaraam <kaartic.sivaraam@gmail.com> writes:

> diff --git a/builtin/branch.c b/builtin/branch.c
> index 7018e5d75..c2bbf8c3d 100644
> --- a/builtin/branch.c
> +++ b/builtin/branch.c
> @@ -458,11 +458,42 @@ static void reject_rebase_or_bisect_branch(const char *target)
>  	free_worktrees(worktrees);
>  }
>  
> +static void get_error_msg(struct strbuf* error_msg, const char* oldname, unsigned old_branch_exists,
> +			  const char* newname, enum branch_validation_result res)
> +{
> +	const char* connector_string = _(", and ");
> +
> +	if (!old_branch_exists) {
> +		strbuf_addf(error_msg, _("branch '%s' doesn't exist"), oldname);
> +	}

No {} around a single statement block of "if", especially when there
is no "else" that has multi-statement block that needs {}.

> +	switch (res) {
> +		case BRANCH_EXISTS_NO_FORCE:
> +			strbuf_addf(error_msg, "%s", (!old_branch_exists) ? connector_string : "");
> +			strbuf_addf(error_msg,_("branch '%s' already exists"), newname);
> +			break;

The case arms and their statements are indented by one level too much.
The lines are getting overlong.  Find a good place to split, e.g.

    		strbuf_addf(error_msg, "%s",
			!old_branch_exists ? connector_string : "");

Leave a single SP after each "," in an arguments list.

As Eric pointed out, this certainly smells like a sentence lego that
we would be better off without.

>  static void copy_or_rename_branch(const char *oldname, const char *newname, int copy, int force)
>  {
>  	struct strbuf oldref = STRBUF_INIT, newref = STRBUF_INIT, logmsg = STRBUF_INIT;
>  	struct strbuf oldsection = STRBUF_INIT, newsection = STRBUF_INIT;
>  	int recovery = 0;
> +	struct strbuf error_msg = STRBUF_INIT, empty = STRBUF_INIT;
> +	enum branch_validation_result res;
>  
>  	if (!oldname) {
>  		if (copy)
> @@ -471,15 +502,13 @@ static void copy_or_rename_branch(const char *oldname, const char *newname, int
>  			die(_("cannot rename the current branch while not on any."));
>  	}
>  
> -	if (strbuf_check_branch_ref(&oldref, oldname)) {
> +	if (strbuf_check_branch_ref(&oldref, oldname) && ref_exists(oldref.buf))
> +	{

Opening brace { that begins a block comes at the end of the line
that closes the condition of "if"; if you found that your line is
overlong, perhaps do it like so instead:

	if (strbuf_check_branch_ref(&oldref, oldname) &&
	    ref_exists(oldref.buf)) {

Re: [RFC PATCH v3 2/4] branch: re-order function arguments to group related arguments

[Kaartic Sivaraam]

On Mon, 2017-11-06 at 11:06 +0900, Junio C Hamano wrote:
> Kaartic Sivaraam <kaartic.sivaraam@gmail.com> writes:
> 
> > From: Kaartic Sivaraam <kaarticsivaraam91196@gmail.com>
> > 
> > The ad-hoc patches to add new arguments to a function when needed
> > resulted in the related arguments not being close to each other.
> > This misleads the person reading the code to believe that there isn't
> > much relation between those arguments while it's not the case.
> 
> I do not get what this wants to say.  "I am sending this ad-hoc
> patch that scrambles the order of parameters for no real reason" is
> certainly not how you are selling this step.
> 
> > So, re-order the arguments to keep the related arguments close to each
> > other.
> 
> This sentence (without "So,", obviously, because I do not get the
> previous paragraph) I do understand and agree with as a goal.
> 

I've tried to improve it, does the following paragraph sound clear
enough?

    branch: group related arguments of create_branch()
        
    New arguments were added to create_branch() whenever the need
    arised and they were added to tail of the argument list. This
    resulted in the related arguments not being close to each other.
    This misleads the person reading the code to believe that
    there isn't much relation between those arguments while it is
    not the case.
        
    So, re-order the arguments to keep the related arguments close
    to each other.


> I think the only two things that should be kept together are "force"
> and "clobber_head_ok" because the previous 1/4 changed the meaning
> of "clobber_head" to "it is OK if I am renaming the currently
> checked-out branch", i.e. closer to what "force" means.
> 
> I certainly would not mind the order used in the result of this
> patch (in other words, if somebody posted a patch to add
> create_branch() function to the codebase that lacked it, with its
> parameters listed in the order this patch uses, I wouldn't
> complain), but it would have equally been OK if "reflog" and "force"
> were swapped without making any other change this patch makes.
> 

Makes sense. The unwanted shuffling was a consequence of my attempt to
see if the signature of the function did change when the position of
the 'enum' was changed. It seems there isn't change in its signature as
it is possible to use integers for enums and vice versa due to liberal
checking for misuses.

I've changed the signature back to keep alone "force" and
"clobber_head_ok" together.


Thanks,
Kaartic

Re: [RFC PATCH v3 3/4] branch: introduce dont_fail parameter for branchname validation

[Kaartic Sivaraam]

On Mon, 2017-11-06 at 11:24 +0900, Junio C Hamano wrote:
> Kaartic Sivaraam <kaartic.sivaraam@gmail.com> writes:
> 
> We usually use the word "gently" to when we enhance an operation
> that used to always die on failure.  When there are tons of callsite
> to the original operation F(), we introduce F_gently() variant and
> do something like
> 
> 	F(...)
> 	{
> 		if (F_gently(...))
> 			die(...);
> 	}
> 
> so that the callers do not have to change.  If there aren't that
> many, it is OK to change the function signature of F() to tell it
> not to die without adding a new F_gently() function, which is the
> approach more appropriate for this change.  The extra parameter used
> for that purpose should be called "gently", perhaps.
> 

Good suggestion, wasn't aware of it before. Renamed it.


> > +	if(ref_exists(ref->buf))
> > +		return BRANCH_EXISTS;
> > +	else
> > +		return BRANCH_DOESNT_EXIST;
> 
> Always have SP between "if" (and other keyword like "while") and its
> condition.
>
> For this one, however, this might be easier to follow:
> 
> 	return ref_exists(ref->buf) ? BRANCH_EXISTS : BRANCH_DOESNT_EXIST;
> 

Done.


> The names of the enum values may need further thought.  They must
> clearly convey two things, in addition to what kind of status they
> represent; the current names only convey the status.  From the names
> of these values, it must be clear that they are part of the same
> enum (e.g. by sharing a common prefix), and also from the names of
> these values, it must be clear which ones are error conditions and
> which are not, without knowing their actual values.  A reader cannot
> immediately tell from "BRANCH_EXISTS" if that is a good thing or
> not.
> 

I've added the prefix of "VALIDATION_{FAIL,PASS}" as appropriate to the
enum values. This made the names to have the form,

    VALIDATION_(kind of status)_(reason)

This made the names a bit long but I couldn't come up with a better
prefix for now. Any suggestions are welcome.


Thanks for the detailed review!

---
Kaartic

Re: [RFC PATCH v3 4/4] builtin/branch: give more useful error messages when renaming

[Kaartic Sivaraam]

On Mon, 2017-11-06 at 11:30 +0900, Junio C Hamano wrote:
> Kaartic Sivaraam <kaartic.sivaraam@gmail.com> writes:
> 
> No {} around a single statement block of "if", especially when there
> is no "else" that has multi-statement block that needs {}.
> 

The code has changed a little since v3 so this if has been replaced
with a switch case.


> > +	switch (res) {
> > +		case BRANCH_EXISTS_NO_FORCE:
> > +			strbuf_addf(error_msg, "%s", (!old_branch_exists) ? connector_string : "");
> > +			strbuf_addf(error_msg,_("branch '%s' already exists"), newname);
> > +			break;
> 
> The case arms and their statements are indented by one level too much.
> The lines are getting overlong.  Find a good place to split, e.g.
> 
>     		strbuf_addf(error_msg, "%s",
> 			!old_branch_exists ? connector_string : "");
> 
> Leave a single SP after each "," in an arguments list.
> 

Fixed these.


> As Eric pointed out, this certainly smells like a sentence lego that
> we would be better off without.
> 

As stated in that mail,  I've replaced the connector " and " with "; "
as it seemed to be the most simple way to overcome the issue, at least
in my opinion. In case there's any better way to fix this let me know.


> >  static void copy_or_rename_branch(const char *oldname, const char *newname, int copy, int force)
> >  {
> >  	struct strbuf oldref = STRBUF_INIT, newref = STRBUF_INIT, logmsg = STRBUF_INIT;
> >  	struct strbuf oldsection = STRBUF_INIT, newsection = STRBUF_INIT;
> >  	int recovery = 0;
> > +	struct strbuf error_msg = STRBUF_INIT, empty = STRBUF_INIT;
> > +	enum branch_validation_result res;
> >  
> >  	if (!oldname) {
> >  		if (copy)
> > @@ -471,15 +502,13 @@ static void copy_or_rename_branch(const char *oldname, const char *newname, int
> >  			die(_("cannot rename the current branch while not on any."));
> >  	}
> >  
> > -	if (strbuf_check_branch_ref(&oldref, oldname)) {
> > +	if (strbuf_check_branch_ref(&oldref, oldname) && ref_exists(oldref.buf))
> > +	{
> 
> Opening brace { that begins a block comes at the end of the line
> that closes the condition of "if"; if you found that your line is
> overlong, perhaps do it like so instead:
> 
> 	if (strbuf_check_branch_ref(&oldref, oldname) &&
> 	    ref_exists(oldref.buf)) {

This part changed too. Anyways thanks for the detailed review :-)

-- 
Kaartic

Re: [RFC PATCH v3 4/4] builtin/branch: give more useful error messages when renaming

[Kevin Daudt]

On Thu, Nov 02, 2017 at 12:24:07PM +0530, Kaartic Sivaraam wrote:
> From: Kaartic Sivaraam <kaarticsivaraam91196@gmail.com>
> 
> When trying to rename an inexistent branch to with a name of a branch

This sentence does not read well. Probably s/with a/the/ helps.

> that already exists the rename failed specifying the new branch name
> exists rather than specifying that the branch trying to be renamed
> doesn't exist.
> 
> [..]
> 
> Note: Thanks to the strbuf API that made it possible to easily construct
> the composite error message strings!

I'm not sure this note adds a lot, since the strbuf API is not that new.

Kevin

Re: [RFC PATCH v3 4/4] builtin/branch: give more useful error messages when renaming

[Kaartic Sivaraam]

On Sunday 12 November 2017 11:53 PM, Kevin Daudt wrote:
> On Thu, Nov 02, 2017 at 12:24:07PM +0530, Kaartic Sivaraam wrote:
>> From: Kaartic Sivaraam <kaarticsivaraam91196@gmail.com>
>>
>> When trying to rename an inexistent branch to with a name of a branch
>
> This sentence does not read well. Probably s/with a/the/ helps.
>

Thanks. Seems I missed it somehow. Will fix it.

>> that already exists the rename failed specifying the new branch name
>> exists rather than specifying that the branch trying to be renamed
>> doesn't exist.
>>
>> [..]
>>
>> Note: Thanks to the strbuf API that made it possible to easily construct
>> the composite error message strings!
>
> I'm not sure this note adds a lot, since the strbuf API is not that new.
>

That was a little attribution I wanted make to the strbuf API as this 
was the first time I leveraged it to this extent and I was surprised by 
the way it made string manipulation easier in C. Just documented my 
excitation. In case it seems to be noise (?) which should removed, let 
me know.

---
Kaartic

Re: [RFC PATCH v3 2/4] branch: re-order function arguments to group related arguments

[Junio C Hamano]

Kaartic Sivaraam <kaartic.sivaraam@gmail.com> writes:

> I've tried to improve it, does the following paragraph sound clear
> enough?
>
>     branch: group related arguments of create_branch()
>         
>     New arguments were added to create_branch() whenever the need
>     arised and they were added to tail of the argument list. This
>     resulted in the related arguments not being close to each other.

OK, I understand what you wanted to say.  But I do not think that is
based on a true history.

 - f9a482e6 ("checkout: suppress tracking message with "-q"",
   2012-03-26) adds 'quiet' just after 'clobber_head', exactly
   because they are related, and leaves 'track' at the end.

 - 39bd6f72 ("Allow checkout -B <current-branch> to update the
   current branch", 2011-11-26) adds 'clobber_head' not at the end but
   before 'track', which is left at the end.  

 - c847f537 ("Detached HEAD (experimental)", 2007-01-01) split 'start'
   into 'start_name' and 'start_sha1' (the latter was laster removed)
   and this was not a mindless "add at the end", either.

 - 0746d19a ("git-branch, git-checkout: autosetup for remote branch
   tracking", 2007-03-08) did add track at the end, but that is
   justifiable, as it has no relation to any other parameter.

You could call 39bd6f72 somewhat questionable as 'clobber_head' is
related to 'force' more strongly than it is to 'reflog' [*1*], but
it is unfair to blame anything else having done a mindless "add at
the end".



[Footnote]

*1* I actually think the commit added 'clobber_head' because for the
    purpose of what the commit did, it closely was related to 'track',
    turning <force, reflog, track> into <force, reflog, clobber, track>.
    Arguably, it could have done <force, clobber, track, reflog> instead.

Re: [RFC PATCH v3 2/4] branch: re-order function arguments to group related arguments

[Kaartic Sivaraam]

On Mon, 2017-11-13 at 11:32 +0900, Junio C Hamano wrote:
> Kaartic Sivaraam <kaartic.sivaraam@gmail.com> writes:
> 
> > I've tried to improve it, does the following paragraph sound clear
> > enough?
> > 
> >     branch: group related arguments of create_branch()
> >         
> >     New arguments were added to create_branch() whenever the need
> >     arised and they were added to tail of the argument list. This
> >     resulted in the related arguments not being close to each other.
> 
> OK, I understand what you wanted to say.  But I do not think that is
> based on a true history.
> 
>  - f9a482e6 ("checkout: suppress tracking message with "-q"",
>    2012-03-26) adds 'quiet' just after 'clobber_head', exactly
>    because they are related, and leaves 'track' at the end.
> 
>  - 39bd6f72 ("Allow checkout -B <current-branch> to update the
>    current branch", 2011-11-26) adds 'clobber_head' not at the end but
>    before 'track', which is left at the end.  
> 
>  - c847f537 ("Detached HEAD (experimental)", 2007-01-01) split 'start'
>    into 'start_name' and 'start_sha1' (the latter was laster removed)
>    and this was not a mindless "add at the end", either.
> 
>  - 0746d19a ("git-branch, git-checkout: autosetup for remote branch
>    tracking", 2007-03-08) did add track at the end, but that is
>    justifiable, as it has no relation to any other parameter.
> 

Seems I wasn't careful enough in noticing how the arguments were added.
I seemed to have overlooked the fact that 39bd6f72 added 'clobber_head'
"before" track which resulted in the vague commit message. Anyways,
thanks for taking the time to dig into this.


> You could call 39bd6f72 somewhat questionable as 'clobber_head' is
> related to 'force' more strongly than it is to 'reflog' [*1*], but
> it is unfair to blame anything else having done a mindless "add at
> the end".
> 

Yep, you're right. How does the following sound?

    branch: group related arguments of create_branch()
    
    39bd6f726 (Allow checkout -B <current-branch> to update the current
    branch, 2011-11-26) added 'clobber_head' (now, 'clobber_head_ok')
    "before" 'track' as 'track' was closely related 'clobber_head' for
    the purpose the commit wanted to achieve. Looking from the perspective
    of how the arguments are used it turns out that 'clobber_head' is
    more related to 'force' than it is to 'track'.
    
    So, re-order the arguments to keep the related arguments close
    to each other.
    
-- 
Kaartic

Re: [RFC PATCH v3 4/4] builtin/branch: give more useful error messages when renaming

[Kevin Daudt]

On Mon, Nov 13, 2017 at 08:01:12AM +0530, Kaartic Sivaraam wrote:
> On Sunday 12 November 2017 11:53 PM, Kevin Daudt wrote:
> > On Thu, Nov 02, 2017 at 12:24:07PM +0530, Kaartic Sivaraam wrote:
> > > From: Kaartic Sivaraam <kaarticsivaraam91196@gmail.com>
> > > 
> > > When trying to rename an inexistent branch to with a name of a branch
> > 
> > This sentence does not read well. Probably s/with a/the/ helps.
> > 
> 
> Thanks. Seems I missed it somehow. Will fix it.
> 
> > > that already exists the rename failed specifying the new branch name
> > > exists rather than specifying that the branch trying to be renamed
> > > doesn't exist.
> > > 
> > > [..]
> > > 
> > > Note: Thanks to the strbuf API that made it possible to easily construct
> > > the composite error message strings!
> > 
> > I'm not sure this note adds a lot, since the strbuf API is not that new.
> > 
> 
> That was a little attribution I wanted make to the strbuf API as this was
> the first time I leveraged it to this extent and I was surprised by the way
> it made string manipulation easier in C. Just documented my excitation. In
> case it seems to be noise (?) which should removed, let me know.

I guess that would fit better below the the ---

Re: [RFC PATCH v3 4/4] builtin/branch: give more useful error messages when renaming

[Kaartic Sivaraam]

On Monday 13 November 2017 05:00 PM, Kevin Daudt wrote:
> On Mon, Nov 13, 2017 at 08:01:12AM +0530, Kaartic Sivaraam wrote:
>> That was a little attribution I wanted make to the strbuf API as this was
>> the first time I leveraged it to this extent and I was surprised by the way
>> it made string manipulation easier in C. Just documented my excitation. In
>> case it seems to be noise (?) which should removed, let me know.
>
> I guess that would fit better below the the ---
>

That's a nice point. Thanks. (Why didn't I think of it before)


---
Kaartic

[PATCH 0/4] cleanups surrounding branch

[Kaartic Sivaraam]

On the process of making 'git' give more useful error messages
when trying to rename a branch[0], I found a few things that could
be cleaned up. After noticing that the cleanup commits exceeded
the commits that are related to the series, I thought it would
be better to separate the cleanups into an independent series
to keep that topic focused on improving the error messages.

1/4 and 2/4 were part of that series until v3. The others are new
cleanups.

This series goes on top of 'master' and can be found in my fork
as branch 'work/branch-cleanups'[1].

Note: 1/4 might possibly have some conflicts with jc/branch-name-sanity

Footnotes:

[0]: cf. <20171102065407.25404-1-kaartic.sivaraam@gmail.com>

[1]: https://github.com/sivaraam/git/tree/work/branch-cleanups


Kaartic Sivaraam (4):
  branch: improve documentation and naming of create_branch() parameters
  branch: group related arguments of create_branch()
  branch: update warning message shown when copying a misnamed branch
  builtin/branch: strip refs/heads/ using skip_prefix

 branch.c           |  4 ++--
 branch.h           | 10 ++++++++--
 builtin/branch.c   | 20 +++++++++++++-------
 builtin/checkout.c |  2 +-
 4 files changed, 24 insertions(+), 12 deletions(-)

-- 
2.15.0.291.g0d8980c5d

[PATCH 1/4] branch: improve documentation and naming of create_branch() parameters

[Kaartic Sivaraam]

The documentation for 'create_branch()' was incomplete as it didn't say
what certain parameters were used for. Further a parameter name wasn't
very communicative.

So, add missing documentation for the sake of completeness and easy
reference. Also, rename the concerned parameter to make its name more
communicative.

Signed-off-by: Kaartic Sivaraam <kaartic.sivaraam@gmail.com>
---
 branch.c | 4 ++--
 branch.h | 7 ++++++-
 2 files changed, 8 insertions(+), 3 deletions(-)

diff --git a/branch.c b/branch.c
index 62f7b0d8c..3e8d2f93f 100644
--- a/branch.c
+++ b/branch.c
@@ -228,7 +228,7 @@ N_("\n"
 "\"git push -u\" to set the upstream config as you push.");
 
 void create_branch(const char *name, const char *start_name,
-		   int force, int reflog, int clobber_head,
+		   int force, int reflog, int clobber_head_ok,
 		   int quiet, enum branch_track track)
 {
 	struct commit *commit;
@@ -244,7 +244,7 @@ void create_branch(const char *name, const char *start_name,
 
 	if (validate_new_branchname(name, &ref, force,
 				    track == BRANCH_TRACK_OVERRIDE ||
-				    clobber_head)) {
+				    clobber_head_ok)) {
 		if (!force)
 			dont_change_ref = 1;
 		else
diff --git a/branch.h b/branch.h
index b07788558..cb6411f84 100644
--- a/branch.h
+++ b/branch.h
@@ -15,12 +15,17 @@
  *
  *   - reflog creates a reflog for the branch
  *
+ *   - clobber_head_ok allows the currently checked out (hence existing)
+ *     branch to be overwritten; without 'force', it has no effect.
+ *
+ *   - quiet suppresses tracking information
+ *
  *   - track causes the new branch to be configured to merge the remote branch
  *     that start_name is a tracking branch for (if any).
  */
 void create_branch(const char *name, const char *start_name,
 		   int force, int reflog,
-		   int clobber_head, int quiet, enum branch_track track);
+		   int clobber_head_ok, int quiet, enum branch_track track);
 
 /*
  * Validates that the requested branch may be created, returning the
-- 
2.15.0.291.g0d8980c5d

[PATCH 2/4] branch: group related arguments of create_branch()

[Kaartic Sivaraam]

39bd6f726 (Allow checkout -B <current-branch> to update the current
branch, 2011-11-26) added 'clobber_head' (now, 'clobber_head_ok')
"before" 'track' as 'track' was closely related 'clobber_head' for
the purpose the commit wanted to achieve. Looking from the perspective
of how the arguments are used it turns out that 'clobber_head' is
more related to 'force' than it is to 'track'.

So, re-order the arguments to keep the related arguments close
to each other.

Signed-off-by: Kaartic Sivaraam <kaartic.sivaraam@gmail.com>
---
 branch.c           | 2 +-
 branch.h           | 9 +++++----
 builtin/branch.c   | 2 +-
 builtin/checkout.c | 2 +-
 4 files changed, 8 insertions(+), 7 deletions(-)

diff --git a/branch.c b/branch.c
index 3e8d2f93f..bd607ae97 100644
--- a/branch.c
+++ b/branch.c
@@ -228,7 +228,7 @@ N_("\n"
 "\"git push -u\" to set the upstream config as you push.");
 
 void create_branch(const char *name, const char *start_name,
-		   int force, int reflog, int clobber_head_ok,
+		   int force, int clobber_head_ok, int reflog,
 		   int quiet, enum branch_track track)
 {
 	struct commit *commit;
diff --git a/branch.h b/branch.h
index cb6411f84..f66536a10 100644
--- a/branch.h
+++ b/branch.h
@@ -13,19 +13,20 @@
  *
  *   - force enables overwriting an existing (non-head) branch
  *
- *   - reflog creates a reflog for the branch
- *
  *   - clobber_head_ok allows the currently checked out (hence existing)
  *     branch to be overwritten; without 'force', it has no effect.
  *
+ *   - reflog creates a reflog for the branch
+ *
  *   - quiet suppresses tracking information
  *
  *   - track causes the new branch to be configured to merge the remote branch
  *     that start_name is a tracking branch for (if any).
+ *
  */
 void create_branch(const char *name, const char *start_name,
-		   int force, int reflog,
-		   int clobber_head_ok, int quiet, enum branch_track track);
+		   int force, int clobber_head_ok,
+		   int reflog, int quiet, enum branch_track track);
 
 /*
  * Validates that the requested branch may be created, returning the
diff --git a/builtin/branch.c b/builtin/branch.c
index 33fd5fcfd..4edef5baa 100644
--- a/builtin/branch.c
+++ b/builtin/branch.c
@@ -806,7 +806,7 @@ int cmd_branch(int argc, const char **argv, const char *prefix)
 			die(_("the '--set-upstream' option is no longer supported. Please use '--track' or '--set-upstream-to' instead."));
 
 		create_branch(argv[0], (argc == 2) ? argv[1] : head,
-			      force, reflog, 0, quiet, track);
+			      force, 0, reflog, quiet, track);
 
 	} else
 		usage_with_options(builtin_branch_usage, options);
diff --git a/builtin/checkout.c b/builtin/checkout.c
index 7d8bcc383..6068f8d8c 100644
--- a/builtin/checkout.c
+++ b/builtin/checkout.c
@@ -640,8 +640,8 @@ static void update_refs_for_switch(const struct checkout_opts *opts,
 		else
 			create_branch(opts->new_branch, new->name,
 				      opts->new_branch_force ? 1 : 0,
-				      opts->new_branch_log,
 				      opts->new_branch_force ? 1 : 0,
+				      opts->new_branch_log,
 				      opts->quiet,
 				      opts->track);
 		new->name = opts->new_branch;
-- 
2.15.0.291.g0d8980c5d

[PATCH 3/4] branch: update warning message shown when copying a misnamed branch

[Kaartic Sivaraam]

When a user tries to rename a branch that has a "bad name" (e.g.,
starts with a '-') then we warn them that the misnamed branch has
been renamed "away". A similar message is shown when trying to create
a copy of a misnamed branch even though it doesn't remove the misnamed
branch. This is not correct and may confuse the user.

So, update the warning message shown to be more precise that only a copy
of the misnamed branch has been created. It's better to show the warning
message than not showing it at all as it makes the user aware of the
presence of a misnamed branch.

Signed-off-by: Kaartic Sivaraam <kaartic.sivaraam@gmail.com>
---
 builtin/branch.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/builtin/branch.c b/builtin/branch.c
index 4edef5baa..ca9d8abd0 100644
--- a/builtin/branch.c
+++ b/builtin/branch.c
@@ -507,7 +507,7 @@ static void copy_or_rename_branch(const char *oldname, const char *newname, int
 
 	if (recovery) {
 		if (copy)
-			warning(_("Copied a misnamed branch '%s' away"),
+			warning(_("Created a copy of a misnamed branch '%s'"),
 				oldref.buf + 11);
 		else
 			warning(_("Renamed a misnamed branch '%s' away"),
-- 
2.15.0.291.g0d8980c5d

[PATCH 4/4] builtin/branch: strip refs/heads/ using skip_prefix

[Kaartic Sivaraam]

Instead of hard-coding the offset strlen("refs/heads/") to skip
the prefix "refs/heads/" use the skip_prefix() function which
is more communicative and verifies that the string actually
starts with that prefix.

Though we don't check for the result of verification here as
it's (almost) always the case that the string does start
with "refs/heads", it's just better to avoid hard-coding and
be more communicative.

Signed-off-by: Kaartic Sivaraam <kaartic.sivaraam@gmail.com>
---
 builtin/branch.c | 16 +++++++++++-----
 1 file changed, 11 insertions(+), 5 deletions(-)

diff --git a/builtin/branch.c b/builtin/branch.c
index ca9d8abd0..8c546a958 100644
--- a/builtin/branch.c
+++ b/builtin/branch.c
@@ -462,6 +462,8 @@ static void copy_or_rename_branch(const char *oldname, const char *newname, int
 {
 	struct strbuf oldref = STRBUF_INIT, newref = STRBUF_INIT, logmsg = STRBUF_INIT;
 	struct strbuf oldsection = STRBUF_INIT, newsection = STRBUF_INIT;
+	const char *prefix_free_oldref = NULL;
+	const char *prefix_free_newref = NULL;
 	int recovery = 0;
 	int clobber_head_ok;
 
@@ -493,13 +495,17 @@ static void copy_or_rename_branch(const char *oldname, const char *newname, int
 
 	reject_rebase_or_bisect_branch(oldref.buf);
 
+	/* At this point it should be safe to believe that the refs have the
+	   prefix "refs/heads" */
+	skip_prefix(oldref.buf, "refs/heads/", &prefix_free_oldref);
+	skip_prefix(newref.buf, "refs/heads/", &prefix_free_newref);
+
 	if (copy)
 		strbuf_addf(&logmsg, "Branch: copied %s to %s",
 			    oldref.buf, newref.buf);
 	else
 		strbuf_addf(&logmsg, "Branch: renamed %s to %s",
 			    oldref.buf, newref.buf);
-
 	if (!copy && rename_ref(oldref.buf, newref.buf, logmsg.buf))
 		die(_("Branch rename failed"));
 	if (copy && copy_existing_ref(oldref.buf, newref.buf, logmsg.buf))
@@ -508,10 +514,10 @@ static void copy_or_rename_branch(const char *oldname, const char *newname, int
 	if (recovery) {
 		if (copy)
 			warning(_("Created a copy of a misnamed branch '%s'"),
-				oldref.buf + 11);
+				prefix_free_oldref);
 		else
 			warning(_("Renamed a misnamed branch '%s' away"),
-				oldref.buf + 11);
+				prefix_free_oldref);
 	}
 
 	if (!copy &&
@@ -520,9 +526,9 @@ static void copy_or_rename_branch(const char *oldname, const char *newname, int
 
 	strbuf_release(&logmsg);
 
-	strbuf_addf(&oldsection, "branch.%s", oldref.buf + 11);
+	strbuf_addf(&oldsection, "branch.%s", prefix_free_oldref);
 	strbuf_release(&oldref);
-	strbuf_addf(&newsection, "branch.%s", newref.buf + 11);
+	strbuf_addf(&newsection, "branch.%s", prefix_free_newref);
 	strbuf_release(&newref);
 	if (!copy && git_config_rename_section(oldsection.buf, newsection.buf) < 0)
 		die(_("Branch is renamed, but update of config-file failed"));
-- 
2.15.0.291.g0d8980c5d

Re: [PATCH 4/4] builtin/branch: strip refs/heads/ using skip_prefix

[Eric Sunshine]

On Sat, Nov 18, 2017 at 12:26 PM, Kaartic Sivaraam
<kaartic.sivaraam@gmail.com> wrote:
> Instead of hard-coding the offset strlen("refs/heads/") to skip
> the prefix "refs/heads/" use the skip_prefix() function which
> is more communicative and verifies that the string actually
> starts with that prefix.
>
> Though we don't check for the result of verification here as
> it's (almost) always the case that the string does start
> with "refs/heads", it's just better to avoid hard-coding and
> be more communicative.
>
> Signed-off-by: Kaartic Sivaraam <kaartic.sivaraam@gmail.com>
> ---
> diff --git a/builtin/branch.c b/builtin/branch.c
> @@ -462,6 +462,8 @@ static void copy_or_rename_branch(const char *oldname, const char *newname, int
>  {
>         struct strbuf oldref = STRBUF_INIT, newref = STRBUF_INIT, logmsg = STRBUF_INIT;
>         struct strbuf oldsection = STRBUF_INIT, newsection = STRBUF_INIT;
> +       const char *prefix_free_oldref = NULL;
> +       const char *prefix_free_newref = NULL;

A bit of a mouthful. Perhaps name these 'oldname' and 'newname' or something?

Re: [PATCH 4/4] builtin/branch: strip refs/heads/ using skip_prefix

[Kaartic Sivaraam]

On Sunday 19 November 2017 06:34 AM, Eric Sunshine wrote:
> On Sat, Nov 18, 2017 at 12:26 PM, Kaartic Sivaraam
> <kaartic.sivaraam@gmail.com> wrote:
>> diff --git a/builtin/branch.c b/builtin/branch.c
>> @@ -462,6 +462,8 @@ static void copy_or_rename_branch(const char *oldname, const char *newname, int
>>   {
>>          struct strbuf oldref = STRBUF_INIT, newref = STRBUF_INIT, logmsg = STRBUF_INIT;
>>          struct strbuf oldsection = STRBUF_INIT, newsection = STRBUF_INIT;
>> +       const char *prefix_free_oldref = NULL;
>> +       const char *prefix_free_newref = NULL;
> 
> A bit of a mouthful.
> 

Quite possibly.


 > Perhaps name these 'oldname' and 'newname' or something?

How about the following ?

1) "interpreted_oldname" and "interpreted_newname" or

2) "stripped_oldref" and "stripped_newref"

I couldn't come up with better names for now.


---
Kaartic

Re: [PATCH 4/4] builtin/branch: strip refs/heads/ using skip_prefix

[Eric Sunshine]

On Sun, Nov 19, 2017 at 12:21 PM, Kaartic Sivaraam
<kaartic.sivaraam@gmail.com> wrote:
> On Sunday 19 November 2017 06:34 AM, Eric Sunshine wrote:
>> On Sat, Nov 18, 2017 at 12:26 PM, Kaartic Sivaraam
>> <kaartic.sivaraam@gmail.com> wrote:
>>>
>>> diff --git a/builtin/branch.c b/builtin/branch.c
>>> @@ -462,6 +462,8 @@ static void copy_or_rename_branch(const char
>>> *oldname, const char *newname, int
>>>   {
>>>          struct strbuf oldref = STRBUF_INIT, newref = STRBUF_INIT, logmsg
>>> = STRBUF_INIT;
>>>          struct strbuf oldsection = STRBUF_INIT, newsection =
>>> STRBUF_INIT;
>>> +       const char *prefix_free_oldref = NULL;
>>> +       const char *prefix_free_newref = NULL;
>>
>> A bit of a mouthful.
>> Perhaps name these 'oldname' and 'newname' or something?
>
> How about the following ?
>
> 1) "interpreted_oldname" and "interpreted_newname" or
>
> 2) "stripped_oldref" and "stripped_newref"
>
> I couldn't come up with better names for now.

Sorry, I didn't look closely enough at the context to see that
'oldname' and 'newname' were already used as function arguments.

Perhaps call them 'oldref_bare' and 'newref_bare' or something. It not
that important (though, shorter may be preferable). Aside from the
names being rather long, what I didn't mention originally (because I
had edited it out of my earlier response) was that having "free" in
the names made me think that the values needed to be passed to free()
by the end of the function. It's probably not worth a re-roll,
though...

[PATCH v4 4/4] builtin/branch: strip refs/heads/ using skip_prefix

[Kaartic Sivaraam]

Instead of hard-coding the offset strlen("refs/heads/") to skip
the prefix "refs/heads/" use the skip_prefix() function which
is more communicative and verifies that the string actually
starts with that prefix.

Signed-off-by: Kaartic Sivaraam <kaartic.sivaraam@gmail.com>
---
 v2 and v3 of this patch got detached to a different thread due
 to a small mistake I made, sorry. You can find it at

 https://public-inbox.org/git/20171121141852.551-1-kaartic.sivaraam@gmail.com/

 I've brought v4 back to this thread to bring back the continuity. I guess
 this series gets stabilised with this patch.

 Changes in v4 from v1:

  - updated commit message

  - removed superfluous comment

  - updated variable names

  - checked for the errors pointed out by skip_prefix

 builtin/branch.c | 15 +++++++++++----
 1 file changed, 11 insertions(+), 4 deletions(-)

diff --git a/builtin/branch.c b/builtin/branch.c
index ca9d8abd0..b2f5e4a0c 100644
--- a/builtin/branch.c
+++ b/builtin/branch.c
@@ -462,6 +462,8 @@ static void copy_or_rename_branch(const char *oldname, const char *newname, int
 {
 	struct strbuf oldref = STRBUF_INIT, newref = STRBUF_INIT, logmsg = STRBUF_INIT;
 	struct strbuf oldsection = STRBUF_INIT, newsection = STRBUF_INIT;
+	const char *interpreted_oldname = NULL;
+	const char *interpreted_newname = NULL;
 	int recovery = 0;
 	int clobber_head_ok;
 
@@ -493,6 +495,11 @@ static void copy_or_rename_branch(const char *oldname, const char *newname, int
 
 	reject_rebase_or_bisect_branch(oldref.buf);
 
+	if (!skip_prefix(oldref.buf, "refs/heads/", &interpreted_oldname) ||
+	    !skip_prefix(newref.buf, "refs/heads/", &interpreted_newname)) {
+		die("BUG: expected prefix missing for refs")
+	}
+
 	if (copy)
 		strbuf_addf(&logmsg, "Branch: copied %s to %s",
 			    oldref.buf, newref.buf);
@@ -508,10 +515,10 @@ static void copy_or_rename_branch(const char *oldname, const char *newname, int
 	if (recovery) {
 		if (copy)
 			warning(_("Created a copy of a misnamed branch '%s'"),
-				oldref.buf + 11);
+				interpreted_oldname);
 		else
 			warning(_("Renamed a misnamed branch '%s' away"),
-				oldref.buf + 11);
+				interpreted_oldname);
 	}
 
 	if (!copy &&
@@ -520,9 +527,9 @@ static void copy_or_rename_branch(const char *oldname, const char *newname, int
 
 	strbuf_release(&logmsg);
 
-	strbuf_addf(&oldsection, "branch.%s", oldref.buf + 11);
+	strbuf_addf(&oldsection, "branch.%s", interpreted_oldname);
 	strbuf_release(&oldref);
-	strbuf_addf(&newsection, "branch.%s", newref.buf + 11);
+	strbuf_addf(&newsection, "branch.%s", interpreted_newname);
 	strbuf_release(&newref);
 	if (!copy && git_config_rename_section(oldsection.buf, newsection.buf) < 0)
 		die(_("Branch is renamed, but update of config-file failed"));
-- 
2.15.0.531.g2ccb3012c

[PATCH v5 4/4] builtin/branch: strip refs/heads/ using skip_prefix

[Kaartic Sivaraam]

Instead of hard-coding the offset strlen("refs/heads/") to skip
the prefix "refs/heads/" use the skip_prefix() function which
is more communicative and verifies that the string actually
starts with that prefix.

Signed-off-by: Kaartic Sivaraam <kaartic.sivaraam@gmail.com>
---
Sorry, missed a ';' in v4.

The surprising thing I discovered in the TravisCI build for v4
was that apart from the 'Documentation' build the 'Static Analysis'
build passed, with the following output,

-- <snip>
$ ci/run-static-analysis.sh
GIT_VERSION = 2.13.1.1972.g6ced3f745
     SPATCH contrib/coccinelle/array.cocci
     SPATCH result: contrib/coccinelle/array.cocci.patch
     SPATCH contrib/coccinelle/free.cocci
     SPATCH contrib/coccinelle/object_id.cocci
     SPATCH contrib/coccinelle/qsort.cocci
     SPATCH contrib/coccinelle/strbuf.cocci
     SPATCH result: contrib/coccinelle/strbuf.cocci.patch
     SPATCH contrib/coccinelle/swap.cocci
     SPATCH contrib/coccinelle/xstrdup_or_null.cocci

The command "ci/run-static-analysis.sh" exited with 0.
-- <snip> --

+Cc: SZEDER
I guess static analysis tools make an assumption that the source
code is syntactically valid for them to work correctly. So, I guess
we should at least make sure the code 'compiles' before running
the static analysis tool even though we don't build it completely.
I'm not sure if it's a bad thing to run the static analysis on code
that isn't syntactically valid, though.


 builtin/branch.c | 15 +++++++++++----
 1 file changed, 11 insertions(+), 4 deletions(-)

diff --git a/builtin/branch.c b/builtin/branch.c
index ca9d8abd0..196d5fe9b 100644
--- a/builtin/branch.c
+++ b/builtin/branch.c
@@ -462,6 +462,8 @@ static void copy_or_rename_branch(const char *oldname, const char *newname, int
 {
 	struct strbuf oldref = STRBUF_INIT, newref = STRBUF_INIT, logmsg = STRBUF_INIT;
 	struct strbuf oldsection = STRBUF_INIT, newsection = STRBUF_INIT;
+	const char *interpreted_oldname = NULL;
+	const char *interpreted_newname = NULL;
 	int recovery = 0;
 	int clobber_head_ok;
 
@@ -493,6 +495,11 @@ static void copy_or_rename_branch(const char *oldname, const char *newname, int
 
 	reject_rebase_or_bisect_branch(oldref.buf);
 
+	if (!skip_prefix(oldref.buf, "refs/heads/", &interpreted_oldname) ||
+	    !skip_prefix(newref.buf, "refs/heads/", &interpreted_newname)) {
+		die("BUG: expected prefix missing for refs");
+	}
+
 	if (copy)
 		strbuf_addf(&logmsg, "Branch: copied %s to %s",
 			    oldref.buf, newref.buf);
@@ -508,10 +515,10 @@ static void copy_or_rename_branch(const char *oldname, const char *newname, int
 	if (recovery) {
 		if (copy)
 			warning(_("Created a copy of a misnamed branch '%s'"),
-				oldref.buf + 11);
+				interpreted_oldname);
 		else
 			warning(_("Renamed a misnamed branch '%s' away"),
-				oldref.buf + 11);
+				interpreted_oldname);
 	}
 
 	if (!copy &&
@@ -520,9 +527,9 @@ static void copy_or_rename_branch(const char *oldname, const char *newname, int
 
 	strbuf_release(&logmsg);
 
-	strbuf_addf(&oldsection, "branch.%s", oldref.buf + 11);
+	strbuf_addf(&oldsection, "branch.%s", interpreted_oldname);
 	strbuf_release(&oldref);
-	strbuf_addf(&newsection, "branch.%s", newref.buf + 11);
+	strbuf_addf(&newsection, "branch.%s", interpreted_newname);
 	strbuf_release(&newref);
 	if (!copy && git_config_rename_section(oldsection.buf, newsection.buf) < 0)
 		die(_("Branch is renamed, but update of config-file failed"));
-- 
2.15.0.531.g2ccb3012c

Re: [PATCH v5 4/4] builtin/branch: strip refs/heads/ using skip_prefix

[SZEDER Gábor]

On Fri, Dec 1, 2017 at 6:59 AM, Kaartic Sivaraam
<kaartic.sivaraam@gmail.com> wrote:
> Sorry, missed a ';' in v4.
>
> The surprising thing I discovered in the TravisCI build for v4
> was that apart from the 'Documentation' build the 'Static Analysis'
> build passed, with the following output,
>
> -- <snip>
> $ ci/run-static-analysis.sh
> GIT_VERSION = 2.13.1.1972.g6ced3f745
>      SPATCH contrib/coccinelle/array.cocci
>      SPATCH result: contrib/coccinelle/array.cocci.patch
>      SPATCH contrib/coccinelle/free.cocci
>      SPATCH contrib/coccinelle/object_id.cocci
>      SPATCH contrib/coccinelle/qsort.cocci
>      SPATCH contrib/coccinelle/strbuf.cocci
>      SPATCH result: contrib/coccinelle/strbuf.cocci.patch
>      SPATCH contrib/coccinelle/swap.cocci
>      SPATCH contrib/coccinelle/xstrdup_or_null.cocci
>
> The command "ci/run-static-analysis.sh" exited with 0.

Perhaps Coccinelle should have errored out, or perhaps its 0 exit code
means "I didn't find any code matching any of the semantic patches that
required transformation".

> I guess static analysis tools make an assumption that the source
> code is syntactically valid for them to work correctly. So, I guess
> we should at least make sure the code 'compiles' before running
> the static analysis tool even though we don't build it completely.
> I'm not sure if it's a bad thing to run the static analysis on code
> that isn't syntactically valid, though.

Travis CI already runs 6 build jobs compiling Git.  And that is in
addition to the one that you should have run yourself before even
thinking about submitting v4 ;)  That's plenty to catch errors like
these.  And if any of those builds fail because Git can't be built or
because of a test failure, then Coccinelle's success doesn't matter at
all, because the commit is toast anyway.


Gábor

Re: [PATCH v5 4/4] builtin/branch: strip refs/heads/ using skip_prefix

[Junio C Hamano]

SZEDER Gábor <szeder.dev@gmail.com> writes:

> On Fri, Dec 1, 2017 at 6:59 AM, Kaartic Sivaraam
> <kaartic.sivaraam@gmail.com> wrote:
>> Sorry, missed a ';' in v4.
>>
>> The surprising thing I discovered in the TravisCI build for v4
>> was that apart from the 'Documentation' build the 'Static Analysis'
>> build passed, with the following output,
>>
>> -- <snip>
>> $ ci/run-static-analysis.sh
>> GIT_VERSION = 2.13.1.1972.g6ced3f745
>>      SPATCH contrib/coccinelle/array.cocci
>>      SPATCH result: contrib/coccinelle/array.cocci.patch
>>      SPATCH contrib/coccinelle/free.cocci
>>      SPATCH contrib/coccinelle/object_id.cocci
>>      SPATCH contrib/coccinelle/qsort.cocci
>>      SPATCH contrib/coccinelle/strbuf.cocci
>>      SPATCH result: contrib/coccinelle/strbuf.cocci.patch
>>      SPATCH contrib/coccinelle/swap.cocci
>>      SPATCH contrib/coccinelle/xstrdup_or_null.cocci
>>
>> The command "ci/run-static-analysis.sh" exited with 0.
>
> Perhaps Coccinelle should have errored out, or perhaps its 0 exit code
> means "I didn't find any code matching any of the semantic patches that
> required transformation".
>
>> I guess static analysis tools make an assumption that the source
>> code is syntactically valid for them to work correctly. So, I guess
>> we should at least make sure the code 'compiles' before running
>> the static analysis tool even though we don't build it completely.
>> I'm not sure if it's a bad thing to run the static analysis on code
>> that isn't syntactically valid, though.
>
> Travis CI already runs 6 build jobs compiling Git.  And that is in
> addition to the one that you should have run yourself before even
> thinking about submitting v4 ;)  That's plenty to catch errors like
> these.  And if any of those builds fail because Git can't be built or
> because of a test failure, then Coccinelle's success doesn't matter at
> all, because the commit is toast anyway.

Somehow this fell underneath my radar horizon.  I see v4 and v5 of
4/4 but do not seem to find 1-3/4.  Is this meant to be a standalone
patch, or am I expected to already have 1-3 that we already are
committed to take?

Thanks.

Re: [PATCH v5 4/4] builtin/branch: strip refs/heads/ using skip_prefix

[Junio C Hamano]

Junio C Hamano <gitster@pobox.com> writes:

> SZEDER Gábor <szeder.dev@gmail.com> writes:
>
>> On Fri, Dec 1, 2017 at 6:59 AM, Kaartic Sivaraam
>> <kaartic.sivaraam@gmail.com> wrote:
>>> Sorry, missed a ';' in v4.
>>>
>>> The surprising thing I discovered in the TravisCI build for v4
>>> was that apart from the 'Documentation' build the 'Static Analysis'
>>> build passed, with the following output,
>>>
>>> -- <snip>
>>> $ ci/run-static-analysis.sh
>>> GIT_VERSION = 2.13.1.1972.g6ced3f745
>>>      SPATCH contrib/coccinelle/array.cocci
>>>      SPATCH result: contrib/coccinelle/array.cocci.patch
>>>      SPATCH contrib/coccinelle/free.cocci
>>>      SPATCH contrib/coccinelle/object_id.cocci
>>>      SPATCH contrib/coccinelle/qsort.cocci
>>>      SPATCH contrib/coccinelle/strbuf.cocci
>>>      SPATCH result: contrib/coccinelle/strbuf.cocci.patch
>>>      SPATCH contrib/coccinelle/swap.cocci
>>>      SPATCH contrib/coccinelle/xstrdup_or_null.cocci
>>>
>>> The command "ci/run-static-analysis.sh" exited with 0.
>>
>> Perhaps Coccinelle should have errored out, or perhaps its 0 exit code
>> means "I didn't find any code matching any of the semantic patches that
>> required transformation".
>>
>>> I guess static analysis tools make an assumption that the source
>>> code is syntactically valid for them to work correctly. So, I guess
>>> we should at least make sure the code 'compiles' before running
>>> the static analysis tool even though we don't build it completely.
>>> I'm not sure if it's a bad thing to run the static analysis on code
>>> that isn't syntactically valid, though.
>>
>> Travis CI already runs 6 build jobs compiling Git.  And that is in
>> addition to the one that you should have run yourself before even
>> thinking about submitting v4 ;)  That's plenty to catch errors like
>> these.  And if any of those builds fail because Git can't be built or
>> because of a test failure, then Coccinelle's success doesn't matter at
>> all, because the commit is toast anyway.
>
> Somehow this fell underneath my radar horizon.  I see v4 and v5 of
> 4/4 but do not seem to find 1-3/4.  Is this meant to be a standalone
> patch, or am I expected to already have 1-3 that we already are
> committed to take?

Ah, I am guessing that this would apply on top of 1-3/4 in the
thread with <20171118172648.17918-1-kaartic.sivaraam@gmail.com>

The base of the series seems to predate 16169285 ("Merge branch
'jc/branch-name-sanity'", 2017-11-28), so let me see how it looks by
applying those three plus this one on top of 'master' before that
point.

Re: [PATCH v5 4/4] builtin/branch: strip refs/heads/ using skip_prefix

[Kaartic Sivaraam]

On Friday 08 December 2017 04:44 AM, Junio C Hamano wrote:
> Junio C Hamano <gitster@pobox.com> writes:
>>
>> Somehow this fell underneath my radar horizon.  I see v4 and v5 of
>> 4/4 but do not seem to find 1-3/4.  Is this meant to be a standalone
>> patch, or am I expected to already have 1-3 that we already are
>> committed to take?
> 
> Ah, I am guessing that this would apply on top of 1-3/4 in the
> thread with <20171118172648.17918-1-kaartic.sivaraam@gmail.com>
> 

You guessed right; at the right time. I was about to ask why this got 
"out of your radar" in reply to your recent "What's cooking" email :-)


> The base of the series seems to predate 16169285 ("Merge branch
> 'jc/branch-name-sanity'", 2017-11-28), so let me see how it looks by
> applying those three plus this one on top of 'master' before that
> point.
> 

Let me know if this has terrible conflicts so that I can rebase the 
series on top of 'master'.


Thanks,
Kaartic

[PATCH v4 0/3] give more useful error messages while renaming branch (reboot)

[Kaartic Sivaraam]

It's been a long time since the v3 of the patch. So, it's worth restating
the reason behind this patch.

From v1 of this patch,

     In builtin/branch, the error messages weren't handled directly by the branch
     renaming function and was left to the other function. Though this avoids
     redundancy this gave unclear error messages in some cases. So, make
     builtin/branch give more useful error messages.

Changes since v3:

 - Handled more error related to old branch name.

 - Incorporated changes suggested in v3 which include using ';' as a sentence
   connector instead 'and'.

 - Error messages use the interpreted branch names (without the (refs/heads/ part).

The unrelated cleanup patches which were in the previous versions have
since been submitted as a separate series and have been merged into
the codebase.

The first two patches are related to the topic of this patch. The 3rd one
is a little typo fix that I noticed on the way.

This patch was based off 'master' and has been rebased to incorporate
the new changes to 'master'. So, it generally should apply cleanly on
'master'. Let me know if it doesn't.

The sample input/output cases for this patch are as follows,

	$ git branch
	* master
	  foo
	  bar

Before patch,

	# Case 1: Trying to rename non-existent branch
	$ git branch -m hypothet no_such_branch
	error: refname refs/heads/hypothet not found
	fatal: Branch rename failed

	# Case 2: Trying to rename non-existent branch to an existing one
	$ git branch -m hypothet master
	fatal: A branch named 'master' already exists.

	# Case 3: Trying to force update current branch
	$ git branch -M foo master
	fatal: Cannot force update the current branch.

	# Case 4: Trying to force rename an in-existent branch with an invalid name
	$ git branch -M hypothet ?123
	fatal: '?123' is not a valid branch name.

After patch,

	# Case 1: Trying to rename non-existent branch
	$ git branch -m hypothet no_such_branch
	fatal: branch 'hypothet' doesn't exist

	# Case 2: Trying to rename non-existent branch to an existing one
	$ git branch -m hypothet master
	fatal: branch 'hypothet' doesn't exist; branch 'master' already exists

	# Case 3: Trying to force update current branch
	$ git branch -M foo master
	fatal: cannot force update the current branch

	# Case 4: Trying to force rename an in-existent branch with an invalid name
	$ git branch -M hypothet ?123
	fatal: branch 'hypothet' doesn't exist; new branch name '?123' is invalid


Note: Thanks to the strbuf API that made it possible to easily
construct the composite error message strings!

Kaartic Sivaraam (3):
  branch: introduce dont_fail parameter for branchname validation
  builtin/branch: give more useful error messages when renaming
  t/t3200: fix a typo in a test description

 branch.c           |  59 +++++++++++++-----------
 branch.h           |  61 ++++++++++++++++++++-----
 builtin/branch.c   | 111 ++++++++++++++++++++++++++++++++++++++-------
 builtin/checkout.c |   5 +-
 t/t3200-branch.sh  |   2 +-
 5 files changed, 181 insertions(+), 57 deletions(-)

-- 
2.16.1.291.g4437f3f13

[PATCH v4 1/3] branch: introduce dont_fail parameter for branchname validation

[Kaartic Sivaraam]

This parameter allows the branchname validation functions to
optionally return a flag specifying the reason for failure, when
requested. This allows the caller to know why it was about to die.
This allows more useful error messages to be given to the user when
trying to rename a branch.

The flags are specified in the form of an enum and values for success
flags have been assigned explicitly to clearly express that certain
callers rely on those values and they cannot be arbitrary.

Only the logic has been added but no caller has been made to use
it, yet. So, no functional changes.

Signed-off-by: Kaartic Sivaraam <kaartic.sivaraam@gmail.com>
---
 branch.c           | 59 ++++++++++++++++++++++++--------------------
 branch.h           | 61 +++++++++++++++++++++++++++++++++++++---------
 builtin/branch.c   |  4 +--
 builtin/checkout.c |  5 ++--
 4 files changed, 88 insertions(+), 41 deletions(-)

diff --git a/branch.c b/branch.c
index 2672054f0..0eeb8403e 100644
--- a/branch.c
+++ b/branch.c
@@ -178,41 +178,48 @@ int read_branch_desc(struct strbuf *buf, const char *branch_name)
 	return 0;
 }
 
-/*
- * Check if 'name' can be a valid name for a branch; die otherwise.
- * Return 1 if the named branch already exists; return 0 otherwise.
- * Fill ref with the full refname for the branch.
- */
-int validate_branchname(const char *name, struct strbuf *ref)
+enum branch_validation_result validate_branchname(const char *name, struct strbuf *ref, unsigned gently)
 {
-	if (strbuf_check_branch_ref(ref, name))
-		die(_("'%s' is not a valid branch name."), name);
+	if (strbuf_check_branch_ref(ref, name)) {
+		if (gently)
+			return VALIDATION_FATAL_INVALID_BRANCH_NAME;
+		else
+			die(_("'%s' is not a valid branch name."), name);
+	}
 
-	return ref_exists(ref->buf);
+	return ref_exists(ref->buf) ? VALIDATION_PASS_BRANCH_EXISTS : VALIDATION_PASS_BRANCH_DOESNT_EXIST;
 }
 
-/*
- * Check if a branch 'name' can be created as a new branch; die otherwise.
- * 'force' can be used when it is OK for the named branch already exists.
- * Return 1 if the named branch already exists; return 0 otherwise.
- * Fill ref with the full refname for the branch.
- */
-int validate_new_branchname(const char *name, struct strbuf *ref, int force)
+enum branch_validation_result validate_new_branchname(const char *name, struct strbuf *ref, int force, unsigned gently)
 {
 	const char *head;
 
-	if (!validate_branchname(name, ref))
-		return 0;
+	if (gently) {
+		enum branch_validation_result res = validate_branchname(name, ref, 1);
+		if (res == VALIDATION_FATAL_INVALID_BRANCH_NAME || res == VALIDATION_PASS_BRANCH_DOESNT_EXIST)
+				return res;
+	} else {
+		if (validate_branchname(name, ref, 0) == VALIDATION_PASS_BRANCH_DOESNT_EXIST)
+			return VALIDATION_PASS_BRANCH_DOESNT_EXIST;
+	}
 
-	if (!force)
-		die(_("A branch named '%s' already exists."),
-		    ref->buf + strlen("refs/heads/"));
+	if (!force) {
+		if (gently)
+			return VALIDATION_FATAL_BRANCH_EXISTS_NO_FORCE;
+		else
+			die(_("A branch named '%s' already exists."),
+				ref->buf + strlen("refs/heads/"));
+	}
 
 	head = resolve_ref_unsafe("HEAD", 0, NULL, NULL);
-	if (!is_bare_repository() && head && !strcmp(head, ref->buf))
-		die(_("Cannot force update the current branch."));
+	if (!is_bare_repository() && head && !strcmp(head, ref->buf)) {
+		if (gently)
+			return VALIDATION_FATAL_CANNOT_FORCE_UPDATE_CURRENT_BRANCH;
+		else
+			die(_("Cannot force update the current branch."));
+	}
 
-	return 1;
+	return VALIDATION_WARN_BRANCH_EXISTS;
 }
 
 static int check_tracking_branch(struct remote *remote, void *cb_data)
@@ -259,8 +266,8 @@ void create_branch(const char *name, const char *start_name,
 		explicit_tracking = 1;
 
 	if ((track == BRANCH_TRACK_OVERRIDE || clobber_head_ok)
-	    ? validate_branchname(name, &ref)
-	    : validate_new_branchname(name, &ref, force)) {
+	    ? validate_branchname(name, &ref, 0)
+	    : validate_new_branchname(name, &ref, force, 0)) {
 		if (!force)
 			dont_change_ref = 1;
 		else
diff --git a/branch.h b/branch.h
index 473d0a93e..ee5f1c0e7 100644
--- a/branch.h
+++ b/branch.h
@@ -28,20 +28,59 @@ void create_branch(const char *name, const char *start_name,
 		   int force, int clobber_head_ok,
 		   int reflog, int quiet, enum branch_track track);
 
-/*
- * Check if 'name' can be a valid name for a branch; die otherwise.
- * Return 1 if the named branch already exists; return 0 otherwise.
- * Fill ref with the full refname for the branch.
- */
-extern int validate_branchname(const char *name, struct strbuf *ref);
+enum branch_validation_result {
+	/* Flags that convey there are fatal errors */
+	VALIDATION_FATAL_BRANCH_EXISTS_NO_FORCE = -3,
+	VALIDATION_FATAL_CANNOT_FORCE_UPDATE_CURRENT_BRANCH,
+	VALIDATION_FATAL_INVALID_BRANCH_NAME,
+	/* Flags that convey there are no fatal errors */
+	VALIDATION_PASS_BRANCH_DOESNT_EXIST = 0,
+	VALIDATION_PASS_BRANCH_EXISTS = 1,
+	VALIDATION_WARN_BRANCH_EXISTS = 2
+};
 
 /*
- * Check if a branch 'name' can be created as a new branch; die otherwise.
- * 'force' can be used when it is OK for the named branch already exists.
- * Return 1 if the named branch already exists; return 0 otherwise.
- * Fill ref with the full refname for the branch.
+ * Check if 'name' can be a valid name for a branch; die otherwise.
+ *
+ *   - name is the new branch name
+ *
+ *   - ref is used to return the full refname for the branch
+ *
+ * The return values have the following meaning,
+ *
+ *   - If 'gently' is 0, the function dies in case of a fatal error and returns
+ *     flags of 'branch_validation_result' that indicate nonfatal cases, otherwise.
+ *     The positive non-zero flag implies that the branch exists.
+ *
+ *   - If 'gently' is 1, the function doesn't die in case of a fatal error but returns
+ *     flags of 'branch_validaton_result' that identify the fatal error. The behaviour
+ *     in case of success is same as above.
+ *
  */
-extern int validate_new_branchname(const char *name, struct strbuf *ref, int force);
+extern enum branch_validation_result validate_branchname(const char *name, struct strbuf *ref, unsigned gently);
+
+/*
+ * Check if a branch 'name' can be created as a new branch.
+ *
+ *   - name is the new branch name
+ *
+ *   - ref is used to return the full refname for the branch
+ *
+ *   - force can be used when it is OK if the named branch already exists.
+ *     the currently checkout branch; with 'shouldnt_exist', it has no effect.
+ *
+ * The return values have the following meaning,
+ *
+ *   - If 'gently' is 0, the function dies in case of a fatal error and returns
+ *     flags of 'branch_validation_result' that indicate nonfatal cases, otherwise.
+ *     The positive non-zero flag implies that the branch can be force updated.
+ *
+ *   - If 'gently' is 1, the function doesn't die in case of a fatal error but returns
+ *     flags of 'branch_validaton_result' that identify the fatal error. The behaviour
+ *     in case of success is same as above.
+ *
+ */
+extern enum branch_validation_result validate_new_branchname(const char *name, struct strbuf *ref, int force, unsigned gently);
 
 /*
  * Remove information about the state of working on the current
diff --git a/builtin/branch.c b/builtin/branch.c
index 8dcc2ed05..5412aa78f 100644
--- a/builtin/branch.c
+++ b/builtin/branch.c
@@ -489,9 +489,9 @@ static void copy_or_rename_branch(const char *oldname, const char *newname, int
 	 * cause the worktree to become inconsistent with HEAD, so allow it.
 	 */
 	if (!strcmp(oldname, newname))
-		validate_branchname(newname, &newref);
+		validate_branchname(newname, &newref, 0);
 	else
-		validate_new_branchname(newname, &newref, force);
+		validate_new_branchname(newname, &newref, force, 0);
 
 	reject_rebase_or_bisect_branch(oldref.buf);
 
diff --git a/builtin/checkout.c b/builtin/checkout.c
index 8f4dfb104..c16455ff0 100644
--- a/builtin/checkout.c
+++ b/builtin/checkout.c
@@ -1243,10 +1243,11 @@ int cmd_checkout(int argc, const char **argv, const char *prefix)
 		struct strbuf buf = STRBUF_INIT;
 
 		if (opts.new_branch_force)
-			opts.branch_exists = validate_branchname(opts.new_branch, &buf);
+			opts.branch_exists = validate_branchname(opts.new_branch, &buf, 0);
 		else
 			opts.branch_exists =
-				validate_new_branchname(opts.new_branch, &buf, 0);
+				validate_new_branchname(opts.new_branch, &buf, 0, 0);
+
 		strbuf_release(&buf);
 	}
 
-- 
2.16.1.291.g4437f3f13

[PATCH v4 2/3] builtin/branch: give more useful error messages when renaming

[Kaartic Sivaraam]

When trying to rename an "inexistent" branch name to a branch name
that "already exists" the rename failed stating that the new branch
name exists rather than stating that the branch trying to be renamed
doesn't exist.

    $ git branch -m tset master
    fatal: A branch named 'master' already exists.

It's conventional to report that 'tset' doesn't exist rather than
reporting that 'master' exists, the same way the 'mv' command does.

    (hypothetical)
    $ git branch -m tset master
    fatal: branch 'tset' doesn't exist.

That has the problem that the error about an existing branch is shown
only after the user corrects the error about inexistent branch.

    $ git branch -m test master
    fatal: A branch named 'master' already exists.

This isn't useful either because the user would have corrected this
error in a single go if he had been told this alongside the first
error. So, give more useful error messages by giving errors about old
branch name and new branch name at the same time. This is possible as
the branch name validation functions now return the reason they were
about to die, when requested.

    $ git branch -m tset master
    fatal: branch 'tset' doesn't exist; branch 'master' already exists

Signed-off-by: Kaartic Sivaraam <kaartic.sivaraam@gmail.com>
---
 builtin/branch.c | 111 +++++++++++++++++++++++++++++++++++++++--------
 1 file changed, 94 insertions(+), 17 deletions(-)

diff --git a/builtin/branch.c b/builtin/branch.c
index 5412aa78f..ab78a7f45 100644
--- a/builtin/branch.c
+++ b/builtin/branch.c
@@ -55,6 +55,13 @@ enum color_branch {
 	BRANCH_COLOR_UPSTREAM = 5
 };
 
+enum old_branch_validation_result {
+	VALIDATION_1_FATAL_OLD_BRANCH_DOESNT_EXIST = -2,
+	VALIDATION_1_FATAL_INVALID_OLD_BRANCH_NAME = -1,
+	VALIDATION_1_PASS_OLD_BRANCH_EXISTS = 0,
+	VALIDATION_1_WARN_BAD_OLD_BRANCH_NAME = 1
+};
+
 static struct string_list output = STRING_LIST_INIT_DUP;
 static unsigned int colopts;
 
@@ -458,13 +465,86 @@ static void reject_rebase_or_bisect_branch(const char *target)
 	free_worktrees(worktrees);
 }
 
+static void get_error_msg(struct strbuf* error_msg,
+			  const char* oldname, enum old_branch_validation_result old_branch_name_res,
+			  const char* newname, enum branch_validation_result new_branch_name_res)
+{
+	const char* connector_string = "; ";
+	unsigned append_connector = 0;
+
+	switch (old_branch_name_res) {
+	case VALIDATION_1_FATAL_INVALID_OLD_BRANCH_NAME:
+		strbuf_addf(error_msg,
+			    _("old branch name '%s' is invalid"), oldname);
+		append_connector = 1;
+		break;
+	case VALIDATION_1_FATAL_OLD_BRANCH_DOESNT_EXIST:
+		strbuf_addf(error_msg,
+			    _("branch '%s' doesn't exist"), oldname);
+		append_connector = 1;
+		break;
+
+	/* not necessary to handle nonfatal cases */
+	case VALIDATION_1_PASS_OLD_BRANCH_EXISTS:
+	case VALIDATION_1_WARN_BAD_OLD_BRANCH_NAME:
+		break;
+	}
+
+	switch (new_branch_name_res) {
+	case VALIDATION_FATAL_BRANCH_EXISTS_NO_FORCE:
+		strbuf_addf(error_msg, "%s",
+			    (append_connector) ? connector_string : "");
+		strbuf_addf(error_msg,
+			    _("branch '%s' already exists"), newname);
+		break;
+	case VALIDATION_FATAL_CANNOT_FORCE_UPDATE_CURRENT_BRANCH:
+		strbuf_addf(error_msg, "%s",
+			    (append_connector) ? connector_string : "");
+		strbuf_addstr(error_msg,
+				_("cannot force update the current branch"));
+		break;
+	case VALIDATION_FATAL_INVALID_BRANCH_NAME:
+		strbuf_addf(error_msg, "%s",
+			    (append_connector) ? connector_string : "");
+		strbuf_addf(error_msg,
+			    _("new branch name '%s' is invalid"), newname);
+		break;
+
+	/* not necessary to handle nonfatal cases */
+	case VALIDATION_PASS_BRANCH_DOESNT_EXIST:
+	case VALIDATION_PASS_BRANCH_EXISTS:
+	case VALIDATION_WARN_BRANCH_EXISTS:
+		break;
+	}
+}
+
+/* Validate the old branch name and return the result */
+static enum old_branch_validation_result validate_old_branchname (const char* name, struct strbuf *oldref) {
+	int bad_ref = strbuf_check_branch_ref(oldref, name);
+	int branch_exists = ref_exists(oldref->buf);
+
+	if (bad_ref) {
+		if(branch_exists)
+			return VALIDATION_1_WARN_BAD_OLD_BRANCH_NAME;
+		else
+			return VALIDATION_1_FATAL_INVALID_OLD_BRANCH_NAME;
+	}
+
+	if (branch_exists)
+		return VALIDATION_1_PASS_OLD_BRANCH_EXISTS;
+	else
+		return VALIDATION_1_FATAL_OLD_BRANCH_DOESNT_EXIST;
+}
+
 static void copy_or_rename_branch(const char *oldname, const char *newname, int copy, int force)
 {
 	struct strbuf oldref = STRBUF_INIT, newref = STRBUF_INIT, logmsg = STRBUF_INIT;
 	struct strbuf oldsection = STRBUF_INIT, newsection = STRBUF_INIT;
 	const char *interpreted_oldname = NULL;
 	const char *interpreted_newname = NULL;
-	int recovery = 0;
+	struct strbuf error_msg = STRBUF_INIT, empty = STRBUF_INIT;
+	enum branch_validation_result new_branch_name_res;
+	enum old_branch_validation_result old_branch_name_res;
 
 	if (!oldname) {
 		if (copy)
@@ -473,33 +553,28 @@ static void copy_or_rename_branch(const char *oldname, const char *newname, int
 			die(_("cannot rename the current branch while not on any."));
 	}
 
-	if (strbuf_check_branch_ref(&oldref, oldname)) {
-		/*
-		 * Bad name --- this could be an attempt to rename a
-		 * ref that we used to allow to be created by accident.
-		 */
-		if (ref_exists(oldref.buf))
-			recovery = 1;
-		else
-			die(_("Invalid branch name: '%s'"), oldname);
-	}
-
+	old_branch_name_res = validate_old_branchname(oldname, &oldref);
 	/*
 	 * A command like "git branch -M currentbranch currentbranch" cannot
 	 * cause the worktree to become inconsistent with HEAD, so allow it.
 	 */
 	if (!strcmp(oldname, newname))
-		validate_branchname(newname, &newref, 0);
+		new_branch_name_res = validate_branchname(newname, &newref, 1);
 	else
-		validate_new_branchname(newname, &newref, force, 0);
-
-	reject_rebase_or_bisect_branch(oldref.buf);
+		new_branch_name_res = validate_new_branchname(newname, &newref, force, 1);
 
 	if (!skip_prefix(oldref.buf, "refs/heads/", &interpreted_oldname) ||
 	    !skip_prefix(newref.buf, "refs/heads/", &interpreted_newname)) {
 		die("BUG: expected prefix missing for refs");
 	}
 
+	get_error_msg(&error_msg, interpreted_oldname, old_branch_name_res,
+				  interpreted_newname, new_branch_name_res);
+	if (strbuf_cmp(&error_msg, &empty))
+		die("%s", error_msg.buf);
+
+	reject_rebase_or_bisect_branch(oldref.buf);
+
 	if (copy)
 		strbuf_addf(&logmsg, "Branch: copied %s to %s",
 			    oldref.buf, newref.buf);
@@ -512,7 +587,7 @@ static void copy_or_rename_branch(const char *oldname, const char *newname, int
 	if (copy && copy_existing_ref(oldref.buf, newref.buf, logmsg.buf))
 		die(_("Branch copy failed"));
 
-	if (recovery) {
+	if (old_branch_name_res == VALIDATION_1_WARN_BAD_OLD_BRANCH_NAME) {
 		if (copy)
 			warning(_("Created a copy of a misnamed branch '%s'"),
 				interpreted_oldname);
@@ -537,6 +612,8 @@ static void copy_or_rename_branch(const char *oldname, const char *newname, int
 		die(_("Branch is copied, but update of config-file failed"));
 	strbuf_release(&oldsection);
 	strbuf_release(&newsection);
+	strbuf_release(&error_msg);
+	strbuf_release(&empty);
 }
 
 static GIT_PATH_FUNC(edit_description, "EDIT_DESCRIPTION")
-- 
2.16.1.291.g4437f3f13

[PATCH v4 3/3] t/t3200: fix a typo in a test description

[Kaartic Sivaraam]

Signed-off-by: Kaartic Sivaraam <kaartic.sivaraam@gmail.com>
---
 t/t3200-branch.sh | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/t/t3200-branch.sh b/t/t3200-branch.sh
index 503a88d02..6c0b7ea4a 100755
--- a/t/t3200-branch.sh
+++ b/t/t3200-branch.sh
@@ -528,7 +528,7 @@ test_expect_success 'git branch -c -f o/q o/p should work when o/p exists' '
 	git branch -c -f o/q o/p
 '
 
-test_expect_success 'git branch -c qq rr/qq should fail when r exists' '
+test_expect_success 'git branch -c qq rr/qq should fail when rr exists' '
 	git branch qq &&
 	git branch rr &&
 	test_must_fail git branch -c qq rr/qq
-- 
2.16.1.291.g4437f3f13

Re: [PATCH v4 1/3] branch: introduce dont_fail parameter for branchname validation

[Junio C Hamano]

Kaartic Sivaraam <kaartic.sivaraam@gmail.com> writes:

> This parameter allows the branchname validation functions to
> optionally return a flag specifying the reason for failure, when
> requested. This allows the caller to know why it was about to die.
> This allows more useful error messages to be given to the user when
> trying to rename a branch.
>
> The flags are specified in the form of an enum and values for success
> flags have been assigned explicitly to clearly express that certain
> callers rely on those values and they cannot be arbitrary.
>
> Only the logic has been added but no caller has been made to use
> it, yet. So, no functional changes.
>
> Signed-off-by: Kaartic Sivaraam <kaartic.sivaraam@gmail.com>
> ---

So... I am not finding dont_fail that was mentioned on the title
anywhere else in the patch.  Such lack of attention to detail is
a bit off-putting.

The change itself overall looks OK.  One minor thing that made me
wonder was this bit:

> +enum branch_validation_result {
> +	/* Flags that convey there are fatal errors */
> +	VALIDATION_FATAL_BRANCH_EXISTS_NO_FORCE = -3,
> +	VALIDATION_FATAL_CANNOT_FORCE_UPDATE_CURRENT_BRANCH,
> +	VALIDATION_FATAL_INVALID_BRANCH_NAME,
> +	/* Flags that convey there are no fatal errors */
> +	VALIDATION_PASS_BRANCH_DOESNT_EXIST = 0,
> +	VALIDATION_PASS_BRANCH_EXISTS = 1,
> +	VALIDATION_WARN_BRANCH_EXISTS = 2
> +};

where adding new error types will force us to touch _two_ lines
(i.e. either you add a new error before NO_FORCE with value -4 and
then remove the "= -3" from NO_FORCE, or you add a new error after
INVALID, and update NO_FORCE to -4), which can easily be screwed up
by a careless developer.  The current code is not wrong per-se, but
I wonder if it can be made less error prone.

Re: [PATCH v4 2/3] builtin/branch: give more useful error messages when renaming

[Junio C Hamano]

Kaartic Sivaraam <kaartic.sivaraam@gmail.com> writes:

> +static void get_error_msg(struct strbuf* error_msg,
> +			  const char* oldname, enum old_branch_validation_result old_branch_name_res,
> +			  const char* newname, enum branch_validation_result new_branch_name_res)
> +{
> +	const char* connector_string = "; ";
> +	unsigned append_connector = 0;
> +
> +	switch (old_branch_name_res) {
> +	case VALIDATION_1_FATAL_INVALID_OLD_BRANCH_NAME:
> +		strbuf_addf(error_msg,
> +			    _("old branch name '%s' is invalid"), oldname);
> +		append_connector = 1;
> +		break;
> +	case VALIDATION_1_FATAL_OLD_BRANCH_DOESNT_EXIST:
> +		strbuf_addf(error_msg,
> +			    _("branch '%s' doesn't exist"), oldname);
> +		append_connector = 1;
> +		break;
> +
> +	/* not necessary to handle nonfatal cases */
> +	case VALIDATION_1_PASS_OLD_BRANCH_EXISTS:
> +	case VALIDATION_1_WARN_BAD_OLD_BRANCH_NAME:
> +		break;
> +	}
> +
> +	switch (new_branch_name_res) {
> +	case VALIDATION_FATAL_BRANCH_EXISTS_NO_FORCE:
> +		strbuf_addf(error_msg, "%s",
> +			    (append_connector) ? connector_string : "");
> +		strbuf_addf(error_msg,
> +			    _("branch '%s' already exists"), newname);
> +		break;
> +	case VALIDATION_FATAL_CANNOT_FORCE_UPDATE_CURRENT_BRANCH:
> +		strbuf_addf(error_msg, "%s",
> +			    (append_connector) ? connector_string : "");
> +		strbuf_addstr(error_msg,
> +				_("cannot force update the current branch"));
> +		break;
> +	case VALIDATION_FATAL_INVALID_BRANCH_NAME:
> +		strbuf_addf(error_msg, "%s",
> +			    (append_connector) ? connector_string : "");
> +		strbuf_addf(error_msg,
> +			    _("new branch name '%s' is invalid"), newname);
> +		break;
> +
> +	/* not necessary to handle nonfatal cases */
> +	case VALIDATION_PASS_BRANCH_DOESNT_EXIST:
> +	case VALIDATION_PASS_BRANCH_EXISTS:
> +	case VALIDATION_WARN_BRANCH_EXISTS:
> +		break;
> +	}
> +}

Quite honestly, I am not sure if this amount of new code that
results in sentence lego is really worth it.  Is it so wrong for
"branch -m tset master" to complain that master already exists so no
branch can be renamed to it?

Re: [PATCH v4 3/3] t/t3200: fix a typo in a test description

[Junio C Hamano]

Kaartic Sivaraam <kaartic.sivaraam@gmail.com> writes:

> Signed-off-by: Kaartic Sivaraam <kaartic.sivaraam@gmail.com>
> ---
>  t/t3200-branch.sh | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)

Thanks.  It is very nice to see unrelated issues nearby found while
working on something else.  Will queue.

>
> diff --git a/t/t3200-branch.sh b/t/t3200-branch.sh
> index 503a88d02..6c0b7ea4a 100755
> --- a/t/t3200-branch.sh
> +++ b/t/t3200-branch.sh
> @@ -528,7 +528,7 @@ test_expect_success 'git branch -c -f o/q o/p should work when o/p exists' '
>  	git branch -c -f o/q o/p
>  '
>  
> -test_expect_success 'git branch -c qq rr/qq should fail when r exists' '
> +test_expect_success 'git branch -c qq rr/qq should fail when rr exists' '
>  	git branch qq &&
>  	git branch rr &&
>  	test_must_fail git branch -c qq rr/qq

Re: [PATCH v4 1/3] branch: introduce dont_fail parameter for branchname validation

[Kaartic Sivaraam]

[-- Attachment #1.1: Type: text/plain, Size: 2815 bytes --]

On Friday 16 March 2018 01:57 AM, Junio C Hamano wrote:
> Kaartic Sivaraam <kaartic.sivaraam@gmail.com> writes:
> 
> So... I am not finding dont_fail that was mentioned on the title
> anywhere else in the patch.  Such lack of attention to detail is
> a bit off-putting.
> 

I'm absolutely sorry x-<

I should have forgotten to update the commit subject during one of the
old rebases in which I renamed the parameter from 'dont_fail' to 'gently'.

I shouldn't have assumed that the commit messages of the old series held
in the reboot too. I should have re-read them "completely" and double
checked it. :-(


>> +enum branch_validation_result {
>> +	/* Flags that convey there are fatal errors */
>> +	VALIDATION_FATAL_BRANCH_EXISTS_NO_FORCE = -3,
>> +	VALIDATION_FATAL_CANNOT_FORCE_UPDATE_CURRENT_BRANCH,
>> +	VALIDATION_FATAL_INVALID_BRANCH_NAME,
>> +	/* Flags that convey there are no fatal errors */
>> +	VALIDATION_PASS_BRANCH_DOESNT_EXIST = 0,
>> +	VALIDATION_PASS_BRANCH_EXISTS = 1,
>> +	VALIDATION_WARN_BRANCH_EXISTS = 2
>> +};
> 
> where adding new error types will force us to touch _two_ lines
> (i.e. either you add a new error before NO_FORCE with value -4 and
> then remove the "= -3" from NO_FORCE, or you add a new error after
> INVALID, and update NO_FORCE to -4), which can easily be screwed up
> by a careless developer.  The current code is not wrong per-se, but
> I wonder if it can be made less error prone.
> 

At the top of my head I could think of 2 ways to get around this,

	- Assigning the actual value to every single entry in the enum.

	  This should solve the issue as a any new entry that would be
	  added is expected to go "with a value". The compiler would
	  warn you in the case of duplicate values. The drawback is: it
	  might be a little restrictive and a little ugly. It would also
	  likely cause maintenance issues if the number of values in the
	  enum get bigger.

	  (Of course this doesn't hold if, the careless programmer
	   shatters "consistency" and adds an entry without a value to
	   the enum and that change gets merged into the codebase ;-) )

	- Using non-negative values for both errors and non-errors.

	  This might make it hard to distinguish errors from non-errors
	  but this would avoid errors completely without much issues,
	  otherwise.

I might prefer the former as I find the possibility of the requirement
to distinguish the errors from non-errors to be high when compared with
the possibility of the requirement to add more new entries to the enum.

Any other ideas/suggestions ?

-- 

Kaartic

QUOTE:

“The most valuable person on any team is the person who makes everyone
else on the team more valuable, not the person who knows the most.”

      - Joel Spolsky


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 870 bytes --]

Re: [PATCH v4 2/3] builtin/branch: give more useful error messages when renaming

[Kaartic Sivaraam]

[-- Attachment #1.1: Type: text/plain, Size: 1141 bytes --]

On Friday 16 March 2018 02:03 AM, Junio C Hamano wrote:
> Quite honestly, I am not sure if this amount of new code that
> results in sentence lego is really worth it.

Speaking specifically about the new code for the sentence lego: I
currently lack knowledge of a better way to achieve the same outcome the
new code does. Let me know if there is a better way.


> Is it so wrong for
> "branch -m tset master" to complain that master already exists so no
> branch can be renamed to it?
>

Speaking in general about the patch itself: though I still find the fact
that "the error about an inexistent source branch seconds the error
about an existing destination branch" to be a little unintuitive, I
actually went on to reboot this after a long time as this also seems to
bring consistency in the error messages related to moving a branch. It
seems that the commit message requires an update as it currently seems
to be misleading as it currently doesn't specify the motivation completely.

That said, I won't be against dropping the patch if it seems to be
adding less value at the cost of more code.

-- 
Kaartic


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 870 bytes --]