Clarify how `new-branch` is different for --help

git_new_branch.py

Index: git_new_branch.py
diff --git a/git_new_branch.py b/git_new_branch.py
index 03b0fcc484bb1d3f6f693e734436ff3ee82e6ee9..1f94f688c0495c70fce5b40eda4d0111f63080ad 100755
--- a/git_new_branch.py
+++ b/git_new_branch.py
@@ -3,6 +3,11 @@
 # Use of this source code is governed by a BSD-style license that can be
 # found in the LICENSE file.
 
+"""
+Create new branch on top of upstream (origin/master). This is different
+from 'git branch`, which creates branch on top of current changeset.
+"""

[agable, 2016/04/12 16:11:17]

This description isn't strictly correct. In particular, you mean `git checkout`,
not `git branch`; and new-branch can create branches tracking the current one as
well with the -t flag. Also, we want to keep the description 1 line, to match
the others.

The best idea here is to crib the first line of the man page: "Create a new
branch with correct tracking information". Or if you want to be slightly more
descriptive, it could be "Create a new branch correctly tracking origin/master".

[anatoly techtonik, 2016/04/12 20:19:24]

Yes, I constantly forgot that `git branch` for removing branches, not creating
them. As for 1 line description `glient` help is more nicely formatted and
doesn't stick to this standard.

For me it is important to understand how is the command different from standard
git way of creating branches, so I'd wish that command line help reflected that.

"branch tracking" concept is rather confusing for people with CVS, SVN, HG
background, so I'd simplify this for people without understanding how git really
works.

[agable, 2016/04/13 16:41:55]

Yeah, I meant the other git-extensions, not gclient.
Note that all of these tools have big man pages, as does depot_tools itself.
`man depot_tools` and `git help new-branch` provide a lot more documentation. I
think it is appropriate in this case for the short doc to be a single line.
The point is that it isn't just "on top of". `git checkout -b foo` creates a
branch "on top of" the current branch. `git new-branch` creates a branch
*tracking* origin/master. This is an important distinction, and one that should
be pointed to in this help string.

+
 import argparse
 import sys
 
@@ -14,7 +19,8 @@ from git_common import hash_one
 
 def main(args):
   parser = argparse.ArgumentParser(
-    formatter_class=argparse.ArgumentDefaultsHelpFormatter
+    formatter_class=argparse.ArgumentDefaultsHelpFormatter,
+    description=__doc__,
   )
   parser.add_argument('branch_name')
   g = parser.add_mutually_exclusive_group()