4cd7ab9a48c1756721d1aab33c9ae992a95038f6
[gerrvim.git] / doc / gerrvim.txt
1 *gerrvim.txt*  Gerrit review's comments preparation helper
2
3 OVERVIEW                                              *gerrvim-overview*
4
5 Gerrit (https://www.gerritcodereview.com/) code review system by default
6 has Web-based interface for creating comments for review. It requires to
7 be online, with enabled JavaScript. It does not play well with some
8 browsers that captures keystrokes. IT has no ability to change interface
9 to something more convenient and comfortable to work with.
10
11 Fortunately it has some API that provides ability to post bunch of
12 comments for review in JSON format and you can use it to publish
13 comments created with convenient offline tools.
14
15 Gerrvim is a free software (see |gerrvim-license|) collection of helper
16 utilities:
17
18 * Converter (gerrvim2json.pl) from simple plain text human readable and
19   editable |gerrvim-format| itself to JSON suitable to be send to Gerrit.
20 * Vim plugin to prepare that Gerrvim file by commenting the source code
21   added for review. It works together with Fugitive
22   (http://www.vim.org/scripts/script.php?script_id=2975).
23 * Simple gerrcommget.sh shell/Perl script that downloads
24   comments and converts them to Gerrvim file.
25
26 Gerrvim file is intended to be edited by human in any editor, in offline
27 mode, with the whole everything aggregated in it at once. It is
28 replacement for JavaScript online Web-based native Gerrite interface
29 when you need to publish comments for the source code and replies to
30 other one.
31
32 WORKFLOW                                              *gerrvim-workflow*
33
34 So you received a notify about review request. At first you need to
35 download that patch (this is only an example): >
36     % git fetch gerrit changes/92/92/1
37
38 Then you open this commit in Vim's Fugitive plugin: >
39     :Gedit FETCH_HEAD
40
41 You can navigate through the files and diffs in it. Read Fugitive
42 documentation for more information. For example you want to add a
43 comment about some lines in the patch. Open that file inside the commit,
44 select required lines, call code commenting (see |gerrvim-usage|), enter
45 the comments in newly appeared window, close it by pressing <CR>.
46
47 Repeat that step to add all the comments. They are aggregated in
48 temporary Gerrvim file (/tmp/gerrvim.txt by default).
49
50 When you finished with it, you can edit and correct Gerrvim file without
51 any Fugitive later. Possibly to add a comment for the whole review, not
52 related to any of the files.
53
54 At last you want to publish all your writings. Use converter to create
55 JSON from Gerrvim and send it directly to Gerrit. >
56     % gerrvim2json.pl /tmp/gerrvim.txt | ssh gerrit gerrit review --json
57
58 Soon you may receive notification about someone replied to your
59 comments. You can use gerrcommget.sh script to retrieve them and
60 save as a Gerrvim file: >
61     % gerrcommget.sh 92 1 > /tmp/gerrvim.txt
62
63 Be sure to precoconfigure |gerrvim-config| it and specify URL to your
64 Gerrit's REST-API, your username and password.
65
66 Edit that Gerrvim file and convert to JSON with sending to the server
67 again. It has slightly different headers and you comments will be
68 published as a reply to other ones.
69
70 INSTALLATION                                           *gerrvim-install*
71
72 * Install Fugitive plugin for the Vim
73 * Install Perl JSON (https://metacpan.org/pod/JSON) and Encode modules
74 * Copy plugin/gerrvim.vim to ~/.vim/plugin
75 * Optionally copy that readme to ~/.vim/doc/gerrvim.txt
76
77 CONFIGURATION                                           *gerrvim-config*
78
79 The only option for the Vim plugin is the placement of temporary file
80 with aggregated comments. By default it is /tmp/gerrvim.txt. You can
81 override it in your .vimrc: >
82     let g:gerrvim_file = "/another/path.txt"
83
84 Edit gerrcommget.sh and specify necessary GERRADDR (Gerrit's
85 server URL), GERRUSER (your username) and GERRPASS (password) variables.
86 You can override them anytime with environment variables.
87
88 PLUGIN USAGE                                             *gerrvim-usage*
89
90 * Open necessary commit using Fugitive (:Gedit) and file inside it
91 * Visually select a bunch of code lines you want to comment
92 * Press <Leader>cc (usually "\cc") or call :Gerrvim command
93   specifying the range
94 * You will see an additional small window with your code
95 * Add necessary comment message below -----END----- line
96 * Either press <CR> in normal mode, or save buffer and exit
97 * Comment window will be closed, saving your consolidated changes
98   in temporary file
99 * To wipe out all your comments either call :GerrvimClear or remove
100   that temporary file)
101
102 GERRVIM FILE FORMAT                                     *gerrvim-format*
103
104 Gerrvim's file includes blocks of text separated by BEGIN/END lines. >
105     Some main review message.
106     It can be multilined.
107
108     -----BEGIN 2c5405c8145e61b738953b4e Makefile 27 29-----
109     foo: bar
110         make -C some thing
111     -----END-----
112     You must replace make with $(MAKE).
113
114     And I could write it multiline too.
115
116
117     -----BEGIN 2c5405c8145e61b738953b4e Makefile 1 2-----
118     #/usr/bin/make
119     -----END-----
120     Remove that.
121
122     -----BEGIN R1a014df3_5b8de330 README 20 22-----
123     Vasyliy Pupkin:
124     I am not sure about that corrections. What do you think?
125     -----END-----
126     Seems you are right.
127
128 BEGIN line contains:
129
130 * Either commit's hash, or comment's id with "R" prefix. If R-prefixed
131   comment's id is specified, then you will be replying to it
132 * Path to the file inside source code tree
133 * Linenumber where comment begins
134 * Linenumber where comment ends
135
136 You are capable to comment either range of lines, or the single one.
137
138 Everything between BEGIN and END lines is just for convenience and won't
139 be published anywhere, it is cut.
140
141 The text between END and next BEGIN line is the comment itself. It can
142 be multilined. All empty lines at the end are removed.
143
144 Optional text before the very first BEGIN line will be review's main
145 message, not related to any file.
146
147 LICENCE                                                *gerrvim-license*
148
149 Copyright (C) 2015-2019 Sergey Matveev <stargrave@stargrave.org>
150
151 This program is free software: you can redistribute it and/or modify
152 it under the terms of the GNU General Public License as published by
153 the Free Software Foundation, version 3 of the License.
154
155 This program is distributed in the hope that it will be useful,
156 but WITHOUT ANY WARRANTY; without even the implied warranty of
157 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
158 GNU General Public License for more details.
159
160 You should have received a copy of the GNU General Public License
161 along with this program.  If not, see <http://www.gnu.org/licenses/>.
162
163  vim:filetype=help