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-2025 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