commands: document the "common" class attribute

Switch it to uppercase to make it clear it's a constant, and add
documentation so its usage is clear.

Change-Id: I6d281a66a90b5908b3131585c9945e88cfe815ea
Reviewed-on: https://gerrit-review.googlesource.com/c/git-repo/+/309322
Reviewed-by: Raman Tenneti <rtenneti@google.com>
Tested-by: Mike Frysinger <vapier@google.com>

28 files changed, 33 insertions, 29 deletions

diff --git a/command.py b/command.py
index 9b1220dc..8e930299 100644
--- a/command.py
+++ b/command.py
@@ -43,11 +43,15 @@ class Command(object):
   """Base class for any command line action in repo.
   """
 
-  common = False
   event_log = EventLog()
   manifest = None
   _optparse = None
 
+  # Whether this command is a "common" one, i.e. whether the user would commonly
+  # use it or it's a more uncommon command.  This is used by the help command to
+  # show short-vs-full summaries.
+  COMMON = False
+
   # Whether this command supports running in parallel.  If greater than 0,
   # it is the number of parallel jobs to default to.
   PARALLEL_JOBS = None
diff --git a/subcmds/abandon.py b/subcmds/abandon.py
index c7c127d6..85d85f5a 100644
--- a/subcmds/abandon.py
+++ b/subcmds/abandon.py
@@ -23,7 +23,7 @@ from progress import Progress
 
 
 class Abandon(Command):
-  common = True
+  COMMON = True
   helpSummary = "Permanently abandon a development branch"
   helpUsage = """
 %prog [--all | <branchname>] [<project>...]
diff --git a/subcmds/branches.py b/subcmds/branches.py
index 2dc102bb..6d975ed4 100644
--- a/subcmds/branches.py
+++ b/subcmds/branches.py
@@ -62,7 +62,7 @@ class BranchInfo(object):
 
 
 class Branches(Command):
-  common = True
+  COMMON = True
   helpSummary = "View current topic branches"
   helpUsage = """
 %prog [<project>...]
diff --git a/subcmds/checkout.py b/subcmds/checkout.py
index 4d8009b1..9b429489 100644
--- a/subcmds/checkout.py
+++ b/subcmds/checkout.py
@@ -20,7 +20,7 @@ from progress import Progress
 
 
 class Checkout(Command):
-  common = True
+  COMMON = True
   helpSummary = "Checkout a branch for development"
   helpUsage = """
 %prog <branchname> [<project>...]
diff --git a/subcmds/cherry_pick.py b/subcmds/cherry_pick.py
index fc4998c3..7bd858bf 100644
--- a/subcmds/cherry_pick.py
+++ b/subcmds/cherry_pick.py
@@ -21,7 +21,7 @@ CHANGE_ID_RE = re.compile(r'^\s*Change-Id: I([0-9a-f]{40})\s*$')
 
 
 class CherryPick(Command):
-  common = True
+  COMMON = True
   helpSummary = "Cherry-pick a change."
   helpUsage = """
 %prog <sha1>
diff --git a/subcmds/diff.py b/subcmds/diff.py
index b400ccfd..00a7ec29 100644
--- a/subcmds/diff.py
+++ b/subcmds/diff.py
@@ -19,7 +19,7 @@ from command import DEFAULT_LOCAL_JOBS, PagedCommand
 
 
 class Diff(PagedCommand):
-  common = True
+  COMMON = True
   helpSummary = "Show changes between commit and working tree"
   helpUsage = """
 %prog [<project>...]
diff --git a/subcmds/diffmanifests.py b/subcmds/diffmanifests.py
index 6f23b345..f6cc30a2 100644
--- a/subcmds/diffmanifests.py
+++ b/subcmds/diffmanifests.py
@@ -31,7 +31,7 @@ class Diffmanifests(PagedCommand):
   deeper level.
   """
 
-  common = True
+  COMMON = True
   helpSummary = "Manifest diff utility"
   helpUsage = """%prog manifest1.xml [manifest2.xml] [options]"""
 
diff --git a/subcmds/download.py b/subcmds/download.py
index 81d997e0..523f25e0 100644
--- a/subcmds/download.py
+++ b/subcmds/download.py
@@ -22,7 +22,7 @@ CHANGE_RE = re.compile(r'^([1-9][0-9]*)(?:[/\.-]([1-9][0-9]*))?$')
 
 
 class Download(Command):
-  common = True
+  COMMON = True
   helpSummary = "Download and checkout a change"
   helpUsage = """
 %prog {[project] change[/patchset]}...
diff --git a/subcmds/forall.py b/subcmds/forall.py
index 0cf3b6a6..7c1dea9e 100644
--- a/subcmds/forall.py
+++ b/subcmds/forall.py
@@ -41,7 +41,7 @@ class ForallColoring(Coloring):
 
 
 class Forall(Command, MirrorSafeCommand):
-  common = False
+  COMMON = False
   helpSummary = "Run a shell command in each project"
   helpUsage = """
 %prog [<project>...] -c <command> [<arg>...]
diff --git a/subcmds/gitc_delete.py b/subcmds/gitc_delete.py
index 54b956f7..df749469 100644
--- a/subcmds/gitc_delete.py
+++ b/subcmds/gitc_delete.py
@@ -19,7 +19,7 @@ import platform_utils
 
 
 class GitcDelete(Command, GitcClientCommand):
-  common = True
+  COMMON = True
   visible_everywhere = False
   helpSummary = "Delete a GITC Client."
   helpUsage = """
diff --git a/subcmds/gitc_init.py b/subcmds/gitc_init.py
index 23a4ebb6..e705b613 100644
--- a/subcmds/gitc_init.py
+++ b/subcmds/gitc_init.py
@@ -23,7 +23,7 @@ import wrapper
 
 
 class GitcInit(init.Init, GitcAvailableCommand):
-  common = True
+  COMMON = True
   helpSummary = "Initialize a GITC Client."
   helpUsage = """
 %prog [options] [client name]
diff --git a/subcmds/grep.py b/subcmds/grep.py
index 6cb1445a..8ac4ba14 100644
--- a/subcmds/grep.py
+++ b/subcmds/grep.py
@@ -29,7 +29,7 @@ class GrepColoring(Coloring):
 
 
 class Grep(PagedCommand):
-  common = True
+  COMMON = True
   helpSummary = "Print lines matching a pattern"
   helpUsage = """
 %prog {pattern | -e pattern} [<project>...]
diff --git a/subcmds/help.py b/subcmds/help.py
index 0989b999..821f6bf6 100644
--- a/subcmds/help.py
+++ b/subcmds/help.py
@@ -24,7 +24,7 @@ from wrapper import Wrapper
 
 
 class Help(PagedCommand, MirrorSafeCommand):
-  common = False
+  COMMON = False
   helpSummary = "Display detailed help on a command"
   helpUsage = """
 %prog [--all|command]
@@ -73,7 +73,7 @@ Displays detailed usage information about a command.
 
     commandNames = list(sorted([name
                                 for name, command in all_commands.items()
-                                if command.common and gitc_supported(command)]))
+                                if command.COMMON and gitc_supported(command)]))
     self._PrintCommands(commandNames)
 
     print(
diff --git a/subcmds/info.py b/subcmds/info.py
index f7cf60fc..6c1246ef 100644
--- a/subcmds/info.py
+++ b/subcmds/info.py
@@ -25,7 +25,7 @@ class _Coloring(Coloring):
 
 
 class Info(PagedCommand):
-  common = True
+  COMMON = True
   helpSummary = "Get info on the manifest branch, current branch or unmerged branches"
   helpUsage = "%prog [-dl] [-o [-c]] [<project>...]"
 
diff --git a/subcmds/init.py b/subcmds/init.py
index 4182262e..750facba 100644
--- a/subcmds/init.py
+++ b/subcmds/init.py
@@ -31,7 +31,7 @@ from wrapper import Wrapper
 
 
 class Init(InteractiveCommand, MirrorSafeCommand):
-  common = True
+  COMMON = True
   helpSummary = "Initialize a repo client checkout in the current directory"
   helpUsage = """
 %prog [options] [manifest url]
diff --git a/subcmds/list.py b/subcmds/list.py
index 68bcd5e0..8d0c5640 100644
--- a/subcmds/list.py
+++ b/subcmds/list.py
@@ -16,7 +16,7 @@ from command import Command, MirrorSafeCommand
 
 
 class List(Command, MirrorSafeCommand):
-  common = True
+  COMMON = True
   helpSummary = "List projects and their associated directories"
   helpUsage = """
 %prog [-f] [<project>...]
diff --git a/subcmds/manifest.py b/subcmds/manifest.py
index 965c36e9..00587d8d 100644
--- a/subcmds/manifest.py
+++ b/subcmds/manifest.py
@@ -20,7 +20,7 @@ from command import PagedCommand
 
 
 class Manifest(PagedCommand):
-  common = False
+  COMMON = False
   helpSummary = "Manifest inspection utility"
   helpUsage = """
 %prog [-o {-|NAME.xml}] [-m MANIFEST.xml] [-r]
diff --git a/subcmds/overview.py b/subcmds/overview.py
index b28367be..63f5a79e 100644
--- a/subcmds/overview.py
+++ b/subcmds/overview.py
@@ -19,7 +19,7 @@ from command import PagedCommand
 
 
 class Overview(PagedCommand):
-  common = True
+  COMMON = True
   helpSummary = "Display overview of unmerged project branches"
   helpUsage = """
 %prog [--current-branch] [<project>...]
diff --git a/subcmds/prune.py b/subcmds/prune.py
index 236b647f..584ee7ed 100644
--- a/subcmds/prune.py
+++ b/subcmds/prune.py
@@ -19,7 +19,7 @@ from command import DEFAULT_LOCAL_JOBS, PagedCommand
 
 
 class Prune(PagedCommand):
-  common = True
+  COMMON = True
   helpSummary = "Prune (delete) already merged topics"
   helpUsage = """
 %prog [<project>...]
diff --git a/subcmds/rebase.py b/subcmds/rebase.py
index 9ce4ecb8..7c53eb7a 100644
--- a/subcmds/rebase.py
+++ b/subcmds/rebase.py
@@ -27,7 +27,7 @@ class RebaseColoring(Coloring):
 
 
 class Rebase(Command):
-  common = True
+  COMMON = True
   helpSummary = "Rebase local branches on upstream branch"
   helpUsage = """
 %prog {[<project>...] | -i <project>...}
diff --git a/subcmds/selfupdate.py b/subcmds/selfupdate.py
index 388881d9..282f518e 100644
--- a/subcmds/selfupdate.py
+++ b/subcmds/selfupdate.py
@@ -21,7 +21,7 @@ from subcmds.sync import _PostRepoFetch
 
 
 class Selfupdate(Command, MirrorSafeCommand):
-  common = False
+  COMMON = False
   helpSummary = "Update repo to the latest version"
   helpUsage = """
 %prog
diff --git a/subcmds/smartsync.py b/subcmds/smartsync.py
index c7d1d4d4..d91d59c6 100644
--- a/subcmds/smartsync.py
+++ b/subcmds/smartsync.py
@@ -16,7 +16,7 @@ from subcmds.sync import Sync
 
 
 class Smartsync(Sync):
-  common = True
+  COMMON = True
   helpSummary = "Update working tree to the latest known good revision"
   helpUsage = """
 %prog [<project>...]
diff --git a/subcmds/stage.py b/subcmds/stage.py
index ff0f1738..0389a4ff 100644
--- a/subcmds/stage.py
+++ b/subcmds/stage.py
@@ -28,7 +28,7 @@ class _ProjectList(Coloring):
 
 
 class Stage(InteractiveCommand):
-  common = True
+  COMMON = True
   helpSummary = "Stage file(s) for commit"
   helpUsage = """
 %prog -i [<project>...]
diff --git a/subcmds/start.py b/subcmds/start.py
index ff2bae56..2addaf2e 100644
--- a/subcmds/start.py
+++ b/subcmds/start.py
@@ -25,7 +25,7 @@ from project import SyncBuffer
 
 
 class Start(Command):
-  common = True
+  COMMON = True
   helpSummary = "Start a new branch for development"
   helpUsage = """
 %prog <newbranchname> [--all | <project>...]
diff --git a/subcmds/status.py b/subcmds/status.py
index 1b48dcea..5b669547 100644
--- a/subcmds/status.py
+++ b/subcmds/status.py
@@ -24,7 +24,7 @@ import platform_utils
 
 
 class Status(PagedCommand):
-  common = True
+  COMMON = True
   helpSummary = "Show the working tree status"
   helpUsage = """
 %prog [<project>...]
diff --git a/subcmds/sync.py b/subcmds/sync.py
index 67d9c115..b15d9477 100644
--- a/subcmds/sync.py
+++ b/subcmds/sync.py
@@ -66,7 +66,7 @@ _ONE_DAY_S = 24 * 60 * 60
 
 class Sync(Command, MirrorSafeCommand):
   jobs = 1
-  common = True
+  COMMON = True
   helpSummary = "Update working tree to the latest revision"
   helpUsage = """
 %prog [<project>...]
diff --git a/subcmds/upload.py b/subcmds/upload.py
index fc389e42..c48deab6 100644
--- a/subcmds/upload.py
+++ b/subcmds/upload.py
@@ -55,7 +55,7 @@ def _SplitEmails(values):
 
 
 class Upload(InteractiveCommand):
-  common = True
+  COMMON = True
   helpSummary = "Upload changes for code review"
   helpUsage = """
 %prog [--re --cc] [<project>]...
diff --git a/subcmds/version.py b/subcmds/version.py
index 1d9abb58..09b053ea 100644
--- a/subcmds/version.py
+++ b/subcmds/version.py
@@ -25,7 +25,7 @@ class Version(Command, MirrorSafeCommand):
   wrapper_version = None
   wrapper_path = None
 
-  common = False
+  COMMON = False
   helpSummary = "Display the version of repo"
   helpUsage = """
 %prog