vim

Fork of vim, an acceptable text editor
git clone git://git.laack.co/vim.git
Log | Files | Refs | README | LICENSE

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