1 .TH CODEREVIEW 1
2 .SH NAME
3 codereview \- review of submitted changes (experimental)
4 .SH SYNOPSIS
5 .B git
6 .B diff
7 .B HEAD
8 .I path ...
9 .PP
10 .B codereview
11 [
12 .B -v
13 ]
14 .B create
15 .I name
16 .PP
17 .B codereview
18 [
19 .B -v
20 ]
21 .B commit
22 .PP
23 .B codereview
24 [
25 .B -v
26 ]
27 .B upload
28 .PP
29 .B codereview
30 [
31 .B -v
32 ]
33 .B pending
34 .PP
35 .B codereview
36 [
37 .B -v
38 ]
39 .B sync
40 .SH DESCRIPTION
41 .I Codereview
42 manages the review and submission of changes to the Plan 9 from User Space project.
43 It must be used from within a Plan 9 from User Space tree
44 checked out via Git
45 (see
46 .IR git (1)).
47 .PP
48 A developer makes changes to a local copy of the tree,
49 reviews them by using
50 .I git
51 .I diff
52 .IR HEAD 
53 and then commits them to a ``feature branch''
54 using
55 .I codereview
56 .IR create .
57 Once a feature branch is created, files can still be edited, but they must then be
58 incorporated into the change by using
59 .I codereview
60 .IR commit .
61 .I Git
62 requires that changes be added to a ``staging area'' before the initial commit,
63 using commands such as
64 .I git
65 .I add
66 and
67 .I git
68 .IR rm .
69 The 
70 .I codereview
71 .I create
72 and
73 .I codereview
74 .I commit
75 commands
76 automatically move all local modifications to the staging area
77 as part of the commit,
78 using
79 .I git
80 .I commit
81 .IR -a .
82 .PP
83 If other changes have been committed since the feature branch was created,
84 .I codereview
85 .I sync
86 will update it to be based on the most recent copy of the repository.
87 .PP
88 When the code is ready for review,
89 .I codereview
90 .I upload
91 uploads the change to 
92 .HR https://plan9port-review.googlesource.com/
93 for review.
94 In order to upload, 
95 .I git
96 must have access to a 
97 .I $HOME/.netrc
98 that contains a password obtained from
99 .HR https://plan9port-review.googlesource.com/#/settings/http-password .
100 .PP
101 The most likely initial result of a code review is suggestions for
102 improving the code.
103 After making those changes, repeat the
104 .I codereview
105 .I commit
106 and 
107 .I codereview
108 .I upload
109 steps.
110 .PP
111 Once the code is ready, it will be submitted by the reviewer using the web interface.
112 At that point,
113 .I codereview
114 .I sync
115 .PP
116 The
117 .I codereview
118 .I pending
119 command lists the active feature branches.
120 .PP
121 All the
122 .I codereview
123 commands take a leading
124 .B -v
125 option, which causes them to print
126 .I git
127 commands being executed.
128 This can be useful for debugging
129 .IR codereview .
130 .PP
131 The
132 .I codereview
133 command depends on a 
134 .I git
135 ``commit hook''
136 script being in place to add
137 .L Change-Id
138 lines to the commit messages.
139 .I Codereview
140 installs the hook at startup, if necessary,
141 by adding a symbolic link from
142 .B $PLAN9/.git/hooks/commit-msg
143 to
144 .BR $PLAN9/lib/git/commit-msg.hook .
145 .SH SEE ALSO
146 .IR git (1),
147 .HR http://plan9port-review.googlesource.com/
148 .SH BUGS
149 .I Git
150 is too complicated to use.
151 The 
152 .I codereview
153 script helps, but a working understanding of
154 .I git
155 is still required.