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

git_new_branch.py

 #!/usr/bin/env python
 # Copyright 2014 The Chromium Authors. All rights reserved.
 # 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
 
 import subprocess2
 
 from git_common import run, root, set_config, get_or_create_merge_base, tags
 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()
   g.add_argument('--upstream-current', '--upstream_current',
                  action='store_true',
                  help='set upstream branch to current branch.')
   g.add_argument('--upstream', metavar='REF', default=root(),
                  help='upstream branch (or tag) to track.')
   g.add_argument('--lkgr', action='store_const', const='lkgr', dest='upstream',
                  help='set basis ref for new branch to lkgr.')
@@ skipping 22 matching lines @@
   sys.stderr.write('Switched to branch %s.\n' % opts.branch_name)
   return 0
 
 
 if __name__ == '__main__':  # pragma: no cover
   try:
     sys.exit(main(sys.argv[1:]))
   except KeyboardInterrupt:
     sys.stderr.write('interrupted\n')
     sys.exit(1)