github.com/graybobo/golang.org-package-offline-cache@v0.0.0-20200626051047-6608995c132f/x/review/git-codereview/doc.go (about)

     1  // Copyright 2014 The Go Authors. All rights reserved.
     2  // Use of this source code is governed by a BSD-style
     3  // license that can be found in the LICENSE file.
     4  
     5  /*
     6  Git-codereview manages the code review process for Git changes using a Gerrit
     7  server.
     8  
     9  The git-codereview tool manages "change branches" in the local git repository.
    10  Each such branch tracks a single commit, or "pending change",
    11  that is reviewed using a Gerrit server; the Gerrit remote must be
    12  named 'origin' in the local git repo.
    13  
    14  Modifications to the pending change are applied by amending the commit.
    15  This process implements the "single-commit feature branch" model.
    16  
    17  Once installed as git-codereview, the tool's commands are available through git
    18  either by running
    19  
    20  	git codereview <command>
    21  
    22  or, if aliases are installed, as
    23  
    24  	git <command>
    25  
    26  The review tool's command names do not conflict with any extant git commands.
    27  This document uses the first form for clarity but most users install these
    28  aliases in their .gitconfig file:
    29  
    30  	[alias]
    31  		change = codereview change
    32  		gofmt = codereview gofmt
    33  		mail = codereview mail
    34  		pending = codereview pending
    35  		rebase-work = codereview rebase-work
    36  		submit = codereview submit
    37  		sync = codereview sync
    38  
    39  All commands accept these global flags:
    40  
    41  The -v flag prints all commands that make changes.
    42  
    43  The -n flag prints all commands that would be run, but does not run them.
    44  
    45  Descriptions of each command follow.
    46  
    47  Branchpoint
    48  
    49  	git codereview branchpoint
    50  
    51  The branchpoint command prints the commit hash of the most recent change
    52  on the current branch that is shared with the Gerrit server. This is the point
    53  where local work branched from the published tree. The command is intended
    54  mainly for use in scripts. For example, "git diff $(git codereview branchpoint)"
    55  or "git log $(git codereview branchpoint)..HEAD".
    56  
    57  Change
    58  
    59  The change command creates and moves between Git branches and maintains the
    60  pending commits on work branches.
    61  
    62  	git codereview change [-a] [-q] [branchname]
    63  
    64  Given a branch name as an argument, the change command switches to the named
    65  branch, creating it if necessary. If the branch is created and there are staged
    66  changes, it will commit the changes to the branch, creating a new pending
    67  change.
    68  
    69  With no argument, the change command creates a new pending change from the
    70  staged changes in the current branch or, if there is already a pending change,
    71  amends that change.
    72  
    73  The -q option skips the editing of an extant pending change's commit message.
    74  
    75  The -a option automatically adds any unstaged changes in tracked files during
    76  commit; it is equivalent to the 'git commit' -a option.
    77  
    78  Gofmt
    79  
    80  The gofmt command applies the gofmt program to all files modified in the
    81  current work branch, both in the staging area (index) and the working tree
    82  (local directory).
    83  
    84  	git codereview gofmt [-l]
    85  
    86  The -l option causes the command to list the files that need reformatting but
    87  not reformat them. Otherwise, the gofmt command reformats modified files in
    88  place. That is, files in the staging area are reformatted in the staging area,
    89  and files in the working tree are reformatted in the working tree.
    90  
    91  Help
    92  
    93  The help command displays basic usage instructions.
    94  
    95  	git codereview help
    96  
    97  Hooks
    98  
    99  The hooks command installs the Git hooks to enforce code review conventions.
   100  
   101  	git codereview hooks
   102  
   103  The pre-commit hook checks that all Go code is formatted with gofmt and that
   104  the commit is not being made directly to the master branch.
   105  
   106  The commit-msg hook adds the Gerrit "Change-Id" line to the commit message if
   107  not present. It also checks that the message uses the convention established by
   108  the Go project that the first line has the form, pkg/path: summary.
   109  
   110  The hooks command will not overwrite an existing hook.
   111  If it is not installing hooks, use 'git codereview hooks -v' for details.
   112  This hook installation is also done at startup by all other git codereview
   113  commands, except 'help'.
   114  
   115  Hook-Invoke
   116  
   117  The hook-invoke command is an internal command that invokes the named Git hook.
   118  
   119  	git codereview hook-invoke <hook> [args]
   120  
   121  It is run by the shell scripts installed by the "git codereview hooks" command.
   122  
   123  Mail
   124  
   125  The mail command starts the code review process for the pending change.
   126  
   127  	git codereview mail [-f] [-r email] [-cc email]
   128  
   129  It pushes the pending change commit in the current branch to the Gerrit code
   130  review server and prints the URL for the change on the server.
   131  If the change already exists on the server, the mail command updates that
   132  change with a new changeset.
   133  
   134  The -r and -cc flags identify the email addresses of people to do the code
   135  review and to be CC'ed about the code review.
   136  Multiple addresses are given as a comma-separated list.
   137  
   138  An email address passed to -r or -cc can be shortened from name@domain to name.
   139  The mail command resolves such shortenings by reading the list of past reviewers
   140  from the git repository log to find email addresses of the form name@somedomain
   141  and then, in case of ambiguity, using the reviewer who appears most often.
   142  
   143  The mail command fails if there are staged changes that are not committed.
   144  The -f flag overrides this behavior.
   145  
   146  The mail command updates the tag <branchname>.mailed to refer to the
   147  commit that was most recently mailed, so running 'git diff <branchname>.mailed'
   148  shows diffs between what is on the Gerrit server and the current directory.
   149  
   150  Pending
   151  
   152  The pending command prints to standard output the status of all pending changes
   153  and staged, unstaged, and untracked files in the local repository.
   154  
   155  	git codereview pending [-l]
   156  
   157  The -l flag causes the command to use only locally available information.
   158  By default, it fetches recent commits and code review information from the
   159  Gerrit server.
   160  
   161  Rebase-work
   162  
   163  The rebase-work command runs git rebase in interactive mode over pending changes.
   164  It is shorthand for "git rebase -i $(git codereview branchpoint)".
   165  It differs from plain "git rebase -i" in that the latter will try to incorporate
   166  new commits from the origin branch during the rebase, and git rebase-work
   167  does not.
   168  
   169  Submit
   170  
   171  The submit command pushes the pending change to the Gerrit server and tells
   172  Gerrit to submit it to the master branch.
   173  
   174  	git codereview submit
   175  
   176  The command fails if there are modified files (staged or unstaged) that are not
   177  part of the pending change.
   178  
   179  After submitting the change, the change command tries to synchronize the
   180  current branch to the submitted commit, if it can do so cleanly.
   181  If not, it will prompt the user to run 'git codereview sync' manually.
   182  
   183  After a successful sync, the branch can be used to prepare a new change.
   184  
   185  Sync
   186  
   187  The sync command updates the local repository.
   188  
   189  	git codereview sync
   190  
   191  It fetches changes from the remote repository and merges changes from the
   192  upstream branch to the current branch, rebasing the pending change, if any,
   193  onto those changes.
   194  
   195  */
   196  package main