vim

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

pi_tar.txt (7929B)


      1 *pi_tar.txt*	For Vim version 9.2.  Last change: 2026 Apr 16
      2 
      3 		       +====================+
      4 		       | Tar File Interface |
      5 		       +====================+
      6 
      7 Original Author:  Charles E. Campbell
      8 Copyright 2005-2017:					*tar-copyright*
      9 	The VIM LICENSE (see |copyright|) applies to the files in this
     10 	package, including tarPlugin.vim, tar.vim, and pi_tar.txt.  Like
     11 	anything else that's except use "tar.vim" instead of "VIM".  Like
     12 	anything else that's free, tar.vim and its associated files are
     13 	provided *as is* and comes with no warranty of any kind, either
     14 	expressed or implied.  No guarantees of merchantability.  No
     15 	guarantees of suitability for any purpose.  By using this plugin, you
     16 	agree that in no event will the copyright holder be liable for any
     17 	damages resulting from the use of this software. Use at your own risk!
     18 
     19 ==============================================================================
     20 1. Contents					*tar* *tar-contents*
     21    1. Contents..................................................|tar-contents|
     22    2. Usage.....................................................|tar-usage|
     23    3. Options...................................................|tar-options|
     24    4. History...................................................|tar-history|
     25 
     26 ==============================================================================
     27 2. Usage					*tar-usage* *tar-manual*
     28 
     29    When one edits a *.tar file, this plugin will handle displaying a
     30    contents page.  Select a file to edit by moving the cursor atop
     31    the desired file, then hit the <return> key.  After editing, one may
     32    also write to the file.  Currently, one may not make a new file in
     33    tar archives via the plugin.
     34 
     35 						*:Vimuntar*
     36    VIMUNTAR~
     37 
     38    :Vimuntar [vimhome]
     39 
     40 	This command copies, if necessary, the tarball to the .vim or vimfiles
     41 	directory using the first writable directory in the 'runtimepath' when
     42 	no [vimhome] is specified.  Otherwise, the [vimhome] argument allows
     43 	the user to specify that directory, instead.
     44 
     45 	The copy is done using the command in *g:tar_copycmd* , which is >
     46 		cp   for cygwin, unix, macunix
     47 		copy for windows (32, 95, 64, 16)
     48 <	The extraction is done with the command specified with
     49 	*g:tar_extractcmd* , which by default is >
     50 		"tar -xf"
     51 <
     52 						*:TarDiff*
     53    DIFFERENCING SUPPORT~
     54 
     55    :TarDiff [filename]
     56 
     57 	This command will attempt to show the differences between the tarball
     58 	version of a file and the associated file on the system.  In order to
     59 	find that file on the system, the script uses the path associated with
     60 	the file mentioned in the tarball.  If the current directory is not
     61 	correct for that path, :TarDiff will fail to find the associated file.
     62 
     63 	If the [filename] is given, that filename (and path) will be used
     64 	to specify the associated file.
     65 
     66 
     67    PREVENTING LOADING~
     68 
     69    If for some reason you do not wish to use vim to examine tar'd files,
     70    you may put the following two variables into your <.vimrc> to prevent
     71    the tar plugin from loading: >
     72 
     73 	let g:loaded_tarPlugin= 1
     74 	let g:loaded_tar      = 1
     75 <
     76 							*tar-mappings*
     77    MAPPINGS~
     78 
     79    The following (buffer-local) mappings are available in a tar buffer:
     80 
     81 	<CR>		Open selected file for editing, any changes will be
     82 			written back to the archive.
     83 	<LeftMouse>	same as <CR>
     84 	x		Extract selected file.
     85 
     86 ==============================================================================
     87 3. Options						*tar-options*
     88 
     89    These options are variables that one may change, typically in one's
     90    <.vimrc> file.
     91 			 Default
     92    Variable		  Value   Explanation
     93    *g:tar_browseoptions*    "Ptf"   used to get a list of contents
     94    *g:tar_readoptions*	  "OPxf"  used to extract a file from a tarball
     95    *g:tar_cmd*		  "tar"   the name of the tar program
     96    *g:tar_nomax*	    0	  if true, file window will not be maximized
     97    *g:tar_writeoptions*	  "uf"    used to update/replace a file
     98 
     99 
    100 ==============================================================================
    101 4. History						*tar-history*
    102 
    103 	unreleased:
    104 		Apr 16, 2026	* add missing g:tar_secure into tar#Extract
    105 		Apr 15, 2026	* add path traversal checks in tar#Extract()
    106 		Apr 09, 2026	* fix zstd support and dotted filename support
    107 		Apr 06, 2026	* fix lz4 support
    108 		Feb 07, 2026	* make path traversal detection more robust
    109 		Feb 06, 2026	* fix bug with nowrapscan
    110 		Jul 16, 2025	* update minimum required Vim version
    111 		Jul 13, 2025	* drop leading /
    112 		May 19, 2025	* restore working directory after read/write
    113 		Apr 16, 2025	* decouple from netrw by adding s:WinPath()
    114 				  instead of shelling out to file(1)
    115 		Mar 02, 2025	* determine the compression using readblob()
    116 		Mar 02, 2025	* escape the filename before using :read
    117 		Mar 01, 2025	* fix syntax error in tar#Read()
    118 		Feb 28, 2025	* add support for bzip3 (#16755)
    119 		Feb 06, 2025	* add support for lz4 (#16591)
    120 		Nov 11, 2024	* support permissions (#7379)
    121 		Feb 19, 2024	* announce adoption
    122 		Jan 08, 2024	* fix a few problems (#138331, #12637, #8109)
    123 	v31	Apr 02, 2017	* (klartext) reported that browsing encrypted
    124 				  files in a zip archive created unencrypted
    125 				  swap files.  I am applying a similar fix
    126 				  used on zip.vim to tar.vim: new buffers
    127 				  are opened with |:noswapfile|.
    128 		May 16, 2017	* When the mouse option isn't empty, the
    129 				  leftmouse can be used to select a file
    130 				  in the tar-file listing.
    131 	v30	Apr 22, 2014	* .tgz files are ambiguous: they may have been
    132 				  compressed with either gzip or bzip2.  Tar.vim
    133 				  disambiguates by using unix's "file" command.
    134 		Feb 18, 2016	* Changed =~ to =~# where appropriate
    135 		Feb 18, 2017	* Now also permits xz decompression
    136 	v28	Jun 23, 2011	* a few more decompression options (tbz tb2 txz)
    137 	v27	May 31, 2011	* moved cygwin detection before g:tar_copycmd
    138 				  handling
    139 				* inserted additional |:keepj| modifiers
    140 				* changed silent  to  sil!  (|:silent|)
    141 	v26	Aug 09, 2010	* uses buffer-local instead of window variables
    142 				  to hold tarfile name
    143 				* inserted keepj before 0d to protect jump list
    144 	v25	Jun 19, 2010	* (Jan Steffens) added support for xz
    145 				  compression
    146 	v24	Apr 07, 2009	* :Untarvim command implemented
    147 		Sep 28, 2009	* Added lzma support
    148 	v22	Aug 08, 2008	* security fixes
    149 	v16	Jun 06, 2008	* tarfile:: used instead of tarfile: when
    150 				  editing files inside tarballs.  Fixes a
    151 				  problem with tarballs called things like
    152 				  c:\abc.tar. (tnx to Bill McCarthy)
    153 	v14	May 09, 2008	* arno caught a security bug
    154 		May 28, 2008	* various security improvements.  Now requires
    155 				  patch 299 which provides the fnameescape()
    156 				  function
    157 		May 30, 2008	* allows one to view *.gz and *.bz2 files that
    158 				  are in *.tar files.
    159 	v12	Sep 07, 2007	* &shq now used if not the empty string for
    160 				  g:tar_shq
    161 	v10	May 02, 2006	* now using "redraw then echo" to show messages,
    162 				  instead of "echo and prompt user"
    163 	v9	May 02, 2006	* improved detection of masquerading as tar file
    164 	v8	May 02, 2006	* allows editing of files that merely masquerade
    165 				  as tar files
    166 	v7	Mar 22, 2006	* work on making tar plugin work across network
    167 		Mar 27, 2006	* g:tar_cmd now available for users to change
    168 				  the name of the tar program to be used.  By
    169 				  default, of course, it's "tar".
    170 	v6	Dec 21, 2005	* writing to files not in directories caused
    171 				  problems - fixed (pointed out by
    172 				  Christian Robinson)
    173 	v5	Nov 22, 2005	* report option workaround installed
    174 	v3	Sep 16, 2005	* handles writing files in an archive back to
    175 				  the archive
    176 		Oct 18, 2005	* <amatch> used instead of <afile> in autocmds
    177 		Oct 18, 2005	* handles writing to compressed archives
    178 		Nov 03, 2005	* handles writing tarfiles across a network
    179 				  using netrw#NetWrite()
    180 	v2			* converted to use Vim7's new autoload feature
    181 				  by Bram Moolenaar
    182 	v1	(original)	* Michael Toren
    183 				  (see michael.toren.net/code/
    184 				   link seems dead)
    185 
    186 ==============================================================================
    187 vim:tw=78:ts=8:noet:ft=help