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