pi_vimball.txt (11515B)
1 *pi_vimball.txt* For Vim version 9.2. Last change: 2026 Apr 16 2 3 ---------------- 4 Vimball Archiver 5 ---------------- 6 7 Author: Charles E. Campbell <NcampObell@SdrPchip.AorgM-NOSPAM> 8 (remove NOSPAM from Campbell's email first) 9 Copyright: (c) 2004-2015 by Charles E. Campbell *Vimball-copyright* 10 The VIM LICENSE (see |copyright|) applies to the files in this 11 package, including vimballPlugin.vim, vimball.vim, and pi_vimball.txt. 12 except use "vimball" instead of "VIM". Like anything else that's 13 free, vimball.vim and its associated files are provided *as is* and 14 comes with no warranty of any kind, either expressed or implied. No 15 guarantees of merchantability. No guarantees of suitability for any 16 purpose. By using this plugin, you agree that in no event will the 17 copyright holder be liable for any damages resulting from the use of 18 this software. Use at your own risk! 19 20 ============================================================================== 21 1. Contents *vba* *vimball* *vimball-contents* 22 23 1. Contents......................................: |vimball-contents| 24 2. Vimball Introduction..........................: |vimball-intro| 25 3. Vimball Manual................................: |vimball-manual| 26 MkVimball.....................................: |:MkVimball| 27 UseVimball....................................: |:UseVimball| 28 RmVimball.....................................: |:RmVimball| 29 4. Vimball History...............................: |vimball-history| 30 31 32 ============================================================================== 33 2. Vimball Introduction *vimball-intro* 34 35 Vimball is intended to make life simpler for users of plugins. All 36 a user needs to do with a vimball is: > 37 vim someplugin.vba 38 :so % 39 :q 40 < and the plugin and all its components will be installed into their 41 appropriate directories. Note that one doesn't need to be in any 42 particular directory when one does this. Plus, any help for the 43 plugin will also be automatically installed. 44 45 If a user has decided to use the AsNeeded plugin, vimball is smart 46 enough to put scripts nominally intended for .vim/plugin/ into 47 .vim/AsNeeded/ instead. 48 49 Removing a plugin that was installed with vimball is really easy: > 50 vim 51 :RmVimball someplugin 52 < This operation is not at all easy for zips and tarballs, for example. 53 54 Vimball examines the user's 'runtimepath' to determine where to put 55 the scripts. The first directory mentioned on the runtimepath is 56 usually used if possible. Use > 57 :echo &rtp 58 < to see that directory. 59 60 61 ============================================================================== 62 3. Vimball Manual *vimball-manual* 63 64 MAKING A VIMBALL *:MkVimball* 65 :[range]MkVimball[!] filename [path] 66 67 The range is composed of lines holding paths to files to be included 68 in your new vimball, omitting the portion of the paths that is 69 normally specified by the runtimepath ('rtp'). As an example: > 70 plugin/something.vim 71 doc/something.txt 72 < using > 73 :[range]MkVimball filename 74 < 75 on this range of lines will create a file called "filename.vba" which 76 can be used by Vimball.vim to re-create these files. If the 77 "filename.vba" file already exists, then MkVimball will issue a 78 warning and not create the file. Note that these paths are relative 79 to your .vim (vimfiles) directory, and the files should be in that 80 directory. The vimball plugin normally uses the first 'runtimepath' 81 directory that exists as a prefix; don't use absolute paths, unless 82 the user has specified such a path. 83 84 If you use the exclamation point (!), then MkVimball will create the 85 "filename.vba" file, overwriting it if it already exists. This 86 behavior resembles that for |:w|. 87 88 If you wish to force slashes into the filename, that can also be done 89 by using the exclamation mark (ie. :MkVimball! path/filename). 90 91 The tip at http://vim.wikia.com/wiki/Using_VimBall_with_%27Make%27 92 has a good idea on how to automate the production of vimballs using 93 make. 94 95 96 CONTROLLING THE VIMBALL EXTRACTION DIRECTORY *g:vimball_home* 97 98 You may override the use of the 'runtimepath' by specifying a 99 variable, g:vimball_home. 100 101 *vimball-extract* 102 vim filename.vba 103 104 Simply editing a Vimball will cause Vimball.vim to tell the user to 105 source the file to extract its contents. 106 107 Extraction will only proceed if the first line of a putative vimball 108 file holds the "Vimball Archiver by Charles E. Campbell" line. 109 110 LISTING FILES IN A VIMBALL *:VimballList* 111 112 :VimballList 113 114 This command will tell Vimball to list the files in the archive, along 115 with their lengths in lines. 116 117 MANUALLY INVOKING VIMBALL EXTRACTION *:UseVimball* 118 119 :UseVimball [path] 120 121 This command is contained within the vimball itself; it invokes the 122 vimball#Vimball() routine which is responsible for unpacking the 123 vimball. One may choose to execute it by hand instead of sourcing 124 the vimball; one may also choose to specify a path for the 125 installation, thereby overriding the automatic choice of the first 126 existing directory on the 'runtimepath'. 127 128 REMOVING A VIMBALL *:RmVimball* 129 130 :RmVimball vimballfile [path] 131 132 This command removes all files generated by the specified vimball 133 (but not any directories it may have made). One may choose a path 134 for de-installation, too (see 'runtimepath'); otherwise, the default 135 is the first existing directory on the 'runtimepath'. 136 To implement this, a file (.VimballRecord) is made in that directory 137 containing a record of what files need to be removed for all vimballs 138 used thus far. 139 140 PREVENTING LOADING 141 142 If for some reason you don't want to be able to extract plugins 143 using vimballs: you may prevent the loading of vimball.vim by 144 putting the following two variables in your <.vimrc>: > 145 146 let g:loaded_vimballPlugin= 1 147 let g:loaded_vimball = 1 148 < 149 WINDOWS *vimball-windows* 150 151 Many vimball files are compressed with gzip. Windows, unfortunately, 152 does not come provided with a tool to decompress gzip'ped files. 153 Fortunately, there are a number of tools available for Windows users 154 to un-gzip files: 155 > 156 Item Tool/Suite Free Website 157 ---- ---------- ---- ------- 158 7zip tool y http://www.7-zip.org/ 159 Winzip tool n http://www.winzip.com/downwz.htm 160 unxutils suite y http://unxutils.sourceforge.net/ 161 cygwin suite y http://www.cygwin.com/ 162 GnuWin32 suite y http://gnuwin32.sourceforge.net/ 163 MinGW suite y http://www.mingw.org/ 164 < 165 166 ============================================================================== 167 4. Vimball History *vimball-history* {{{1 168 169 unreleased: 170 Feb 28, 2025 * add support for bzip3 (#16755) 171 Apr 05, 2026 * Detect path traversal attacks 172 Apr 09, 2026 * Detect more path traversal attacks 173 Apr 16, 2026 * Block Windows drive letter paths 174 37 : Jul 18, 2014 * (by request of T. Miedema) added augroup around 175 the autocmds in vimballPlugin.vim 176 Jul 06, 2015 * there are two uses of tabc; changed to tabc! 177 34 : Sep 22, 2011 * "UseVimball path" now supports a non-full path by 178 prepending the current directory to it. 179 33 : Apr 02, 2011 * Gave priority to *.vmb over *.vba 180 * Changed silent! to sil! (shorter) 181 * Safed 'swf' setting (during vimball extraction, 182 its now turned off) 183 32 : May 19, 2010 * (Christian Brabrandt) :so someplugin.vba and 184 :so someplugin.vba.gz (and the other supported 185 compression types) now works 186 * (Jan Steffens) added support for xz compression 187 * fenc extraction was erroneously picking up the 188 end of the line number when no file encoding 189 was present. Fixed. 190 * By request, beginning the switchover from the vba 191 extension to vmb. Currently both are supported; 192 MkVimball, however, now will create *.vmb files. 193 Feb 11, 2011 * motoyakurotsu reported an error with vimball's 194 handling of zero-length files 195 Feb 18, 2016 * Changed =~ to =~# where appropriate 196 30 : Dec 08, 2008 * fnameescape() inserted to protect error 197 messaging using corrupted filenames from 198 causing problems 199 * RmVimball supports filenames that would 200 otherwise be considered to have "magic" 201 characters (ie. Abc[1].vba) 202 Feb 18, 2009 * s:Escape(), g:vimball_shq, and g:netrw_shq 203 removed (shellescape() used directly) 204 Oct 05, 2009 * (Nikolai Weibull) suggested that MkVimball 205 be allowed to use slashes in the filename. 206 26 : May 27, 2008 * g:vimball_mkdir usage installed. Makes the 207 $HOME/.vim (or $HOME\vimfiles) directory if 208 necessary. 209 May 30, 2008 * (tnx to Bill McCarthy) found and fixed a bug: 210 vimball wasn't updating plugins to AsNeeded/ 211 when it should 212 25 : Mar 24, 2008 * changed vimball#Vimball() to recognize doc/*.??x 213 files as help files, too. 214 Apr 18, 2008 * RmVimball command is now protected by saving and 215 restoring settings -- in particular, acd was 216 causing problems as reported by Zhang Shuhan 217 24 : Nov 15, 2007 * g:vimball_path_escape used by s:Path() to 218 prevent certain characters from causing trouble 219 (defunct: |fnameescape()| and |shellescape()| 220 now used instead) 221 22 : Mar 21, 2007 * uses setlocal instead of set during BufEnter 222 21 : Nov 27, 2006 * (tnx to Bill McCarthy) vimball had a header 223 handling problem and it now changes \s to /s 224 20 : Nov 20, 2006 * substitute() calls have all had the 'e' flag 225 removed. 226 18 : Aug 01, 2006 * vimballs now use folding to easily display their 227 contents. 228 * if a user has AsNeeded/somefile, then vimball 229 will extract plugin/somefile to the AsNeeded/ 230 directory 231 17 : Jun 28, 2006 * changes all \s to /s internally for Windows 232 16 : Jun 15, 2006 * A. Mechelynck's idea to allow users to specify 233 installation root paths implemented for 234 UseVimball, MkVimball, and RmVimball. 235 * RmVimball implemented 236 15 : Jun 13, 2006 * bugfix 237 14 : May 26, 2006 * bugfixes 238 13 : May 01, 2006 * exists("&acd") used to determine if the acd 239 option exists 240 12 : May 01, 2006 * bugfix - the 'acd' option is not always defined 241 11 : Apr 27, 2006 * VimballList would create missing subdirectories 242 that the vimball specified were needed. Fixed. 243 10 : Apr 27, 2006 * moved all setting saving/restoration to a pair of 244 functions. Included some more settings in them 245 which frequently cause trouble. 246 9 : Apr 26, 2006 * various changes to support Windows' predilection 247 for backslashes and spaces in file and directory 248 names. 249 7 : Apr 25, 2006 * bypasses foldenable 250 * uses more exe and less norm! (:yank :put etc) 251 * does better at insuring a "Press ENTER" prompt 252 appears to keep its messages visible 253 4 : Mar 31, 2006 * BufReadPost seems to fire twice; BufReadEnter 254 only fires once, so the "Source this file..." 255 message is now issued only once. 256 3 : Mar 20, 2006 * removed query, now requires sourcing to be 257 extracted (:so %). Message to that effect 258 included. 259 * :VimballList now shows files that would be 260 extracted. 261 2 : Mar 20, 2006 * query, :UseVimball included 262 1 : Mar 20, 2006 * initial release 263 264 265 ============================================================================== 266 vim:tw=78:ts=8:noet:ft=help:fdm=marker