pi_zip.txt (9704B)
1 *pi_zip.txt* For Vim version 9.2. Last change: 2026 Aug 19 2 3 +====================+ 4 | Zip File Interface | 5 +====================+ 6 7 Author: Charles E. Campbell <NcampObell@SdrPchip.AorgM-NOSPAM> 8 (remove NOSPAM from Campbell's email first) 9 Copyright: Copyright (C) 2005-2015 Charles E Campbell *zip-copyright* 10 The VIM LICENSE (see |copyright|) applies to the files in this 11 package, including zipPlugin.vim, zip.vim, and pi_zip.vim. except use 12 "zip.vim" instead of "VIM". Like anything else that's free, zip.vim 13 and its associated files are provided *as is* and comes with no 14 warranty of any kind, either expressed or implied. No guarantees of 15 merchantability. No guarantees of suitability for any purpose. By 16 using this plugin, you agree that in no event will the copyright 17 holder be liable for any damages resulting from the use of this 18 software. Use at your own risk! 19 20 ============================================================================== 21 1. Contents *zip* *zip-contents* 22 1. Contents................................................|zip-contents| 23 2. Usage...................................................|zip-usage| 24 3. Additional Extensions...................................|zip-extension| 25 4. History.................................................|zip-history| 26 27 ============================================================================== 28 2. Usage *zip-usage* *zip-manual* 29 30 When one edits a *.zip file, this plugin will handle displaying a 31 contents page. Select a file to edit by moving the cursor atop 32 the desired file, then hit the <return> key. After editing, one may 33 also write to the file. Currently, one may not make a new file in 34 zip archives via the plugin. 35 36 The zip plugin tries to detect some common path traversal attack 37 patterns, but it may not catch all possible cases. Please be very 38 careful when using this plugin with untrusted input. 39 40 COMMANDS~ 41 *zip-x* 42 x : extract a listed file when the cursor is atop it 43 44 OPTIONS~ 45 46 *g:zip_nomax* 47 48 If this variable exists and is true, the file window will not be 49 automatically maximized when opened. 50 51 *g:zip_unzipcmd* 52 Use these options to specify the program which does the duty of "unzip" and 53 the required argument switches. 54 It's used during browsing. By default: > 55 let g:zip_unzipcmd= "unzip" 56 let g:zip_unzipcmd_browseopt= "-Z1" 57 let g:zip_unzipcmd_readopt= "-p" 58 < 59 Note: a `--` is appended after the g:zip_unzipcmd_browseopt and 60 g:zip_unzipcmd_readopt settings to indicate the end of options. 61 62 *g:zip_zipcmd* 63 Use these options to specify the program which does the duty of "zip" and 64 the required argument switches. 65 It's used during the writing (updating) of a file already in a zip 66 file; by default: > 67 let g:zip_zipcmd= "zip" 68 let g:zip_zipcmd_deleteopt= "-d" 69 let g:zip_zipcmd_updateopt= "-u" 70 < 71 *g:zip_extractcmd* 72 This option specifies the program (and any options needed) used to 73 extract a file from a zip archive. By default, > 74 let g:zip_extractcmd= g:zip_unzipcmd 75 let g:zip_extractcmd_extractopt= "-o" 76 < 77 *g:zip_exec* 78 For security reasons, one may prevent that Vim runs executables 79 automatically when opening a buffer. This option (default: "1") 80 can be used to prevent executing the "unzip" command when set to 81 "0": > 82 let g:zip_exec=0 83 < 84 FALLBACK TO POWERSHELL~ 85 86 *g:zip_pwsh* 87 This plugin will first attempt to use the (more capable) GNU zip/unzip 88 commands. If these commands are not available or fail, and the user is 89 using PowerShell, the plugin will fall back to a PowerShell cmdlet. 90 The PowerShell cmdlets are limited: they cannot write or extract files 91 within subdirectories of a zip archive. The advantage, however, is that 92 no separate unzip binary needs to be installed. The 'shell' option will 93 be checked whether to choose "pwsh" or "powershell", or set `g:zip_pwsh`. 94 If both are available, this plugin will prefer pwsh. Default value of 95 "g:zip_pwsh" is an empty string, which would not overwrite the 'shell' 96 option configuration. This functionality is not turned on by default on 97 MS-Windows, since the default 'shell' is "cmd.exe". For example: > 98 let g:zip_pwsh='powershell' 99 < 100 PREVENTING LOADING~ 101 102 If for some reason you do not wish to use vim to examine zipped files, 103 you may put the following two variables into your <.vimrc> to prevent 104 the zip plugin from loading: > 105 106 let g:loaded_zipPlugin= 1 107 let g:loaded_zip = 1 108 < 109 110 ============================================================================== 111 3. Additional Extensions *zip-extension* 112 113 Apparently there are a number of archivers which generate zip files that 114 don't use the .zip extension (.jar, .xpi, etc). To handle such files, 115 place a line in your <.vimrc> file: > 116 117 au BufReadCmd *.jar,*.xpi call zip#Browse(expand("<amatch>")) 118 < 119 One can simply extend this line to accommodate additional extensions that 120 should be treated as zip files. 121 122 Alternatively, one may change *g:zipPlugin_ext* in one's .vimrc. 123 Currently (as of May 2026) it holds: > 124 125 let g:zipPlugin_ext='*.aar,*.apk,*.cbz,*.celzip,*.crtx,*.docm,*.docx, 126 \ *.dotm,*.dotx,*.ear,*.epub,*.gcsx,*.glox,*.gqsx,*.ja,*.jar,*.kmz, 127 \ *.odb,*.odc,*.odf,*.odg,*.odi,*.odm,*.odp,*.ods,*.odt,*.otc,*.otf, 128 \ *.otg,*.oth,*.oti,*.otp,*.ots,*.ott,*.oxt,*.pkpass,*.potm,*.potx, 129 \ *.ppam,*.ppsm,*.ppsx,*.pptm,*.pptx,*.sldx,*.thmx,*.vdw,*.war,*.whl, 130 \ *.wsz, *.xap,*.xlam,*.xlsb,*.xlsm,*.xlsx,*.xltm,*.xltx,*.xpi,*.zip' 131 132 ============================================================================== 133 4. History *zip-history* {{{1 134 unreleased: 135 Jul 25, 2026 * support both Windows PowerShell 5 and pwsh 7+ 136 Sep 19, 2025 * support PowerShell Core 137 Jul 12, 2025 * drop ../ on write to prevent path traversal attacks 138 Mar 11, 2025 * handle filenames with leading '-' correctly 139 Aug 21, 2024 * simplify condition to detect MS-Windows 140 Aug 18, 2024 * correctly handle special globbing chars 141 Aug 05, 2024 * clean-up and make it work with shellslash on Windows 142 Aug 05, 2024 * workaround for the FreeBSD's unzip 143 Aug 04, 2024 * escape '[' in name of file to be extracted 144 Jul 30, 2024 * fix opening remote zipfile 145 Jul 24, 2024 * use delete() function 146 Jul 23, 2024 * fix 'x' command 147 Jun 16, 2024 * handle whitespace on Windows properly (#14998) 148 v33 Dec 07, 2021 * *.xlam mentioned twice in zipPlugin 149 v32 Oct 22, 2021 * to avoid an issue with a vim 8.2 patch, zipfile: has 150 been changed to zipfile:// . This often shows up 151 as zipfile:/// with zipped files that are root-based. 152 v29 Apr 02, 2017 * (Klartext) reported that an encrypted zip file could 153 opened but the swapfile held unencrypted contents. 154 The solution is to edit the contents of a zip file 155 using the |:noswapfile| modifier. 156 v28 Oct 08, 2014 * changed the sanity checks for executables to reflect 157 the command actually to be attempted in zip#Read() 158 and zip#Write() 159 * added the extraction of a file capability 160 Nov 30, 2015 * added *.epub to the |g:zipPlugin_ext| list 161 Sep 13, 2016 * added *.apk to the |g:zipPlugin_ext| list and 162 sorted the suffices. 163 v27 Jul 02, 2013 * sanity check: zipfile must have "PK" as its first 164 two bytes. 165 * modified to allow zipfile: entries in quickfix lists 166 v26 Nov 15, 2012 * (Jason Spiro) provided a lot of new extensions that 167 are synonyms for .zip 168 v25 Jun 27, 2011 * using keepj with unzip -Z 169 (consistent with the -p variant) 170 * (Ben Staniford) now uses 171 has("win32unix") && executable("cygpath") 172 before converting to cygwin-style paths 173 v24 Jun 21, 2010 * (Cédric Bosdonnat) unzip seems to need its filenames 174 fnameescape'd as well as shellquote'd 175 * (Motoya Kurotsu) inserted keepj before 0d to protect 176 jump list 177 v17 May 09, 2008 * arno caught a security bug 178 v15 Sep 07, 2007 * &shq now used if not the empty string for g:zip_shq 179 v14 May 07, 2007 * using b:zipfile instead of w:zipfile to avoid problem 180 when editing alternate file to bring up a zipfile 181 v10 May 02, 2006 * now using "redraw then echo" to show messages, instead 182 of "echo and prompt user" 183 * g:zip_shq provided to allow for quoting control for the 184 command being passed via :r! ... commands. 185 v8 Apr 10, 2006 * Bram Moolenaar reported that he received an error message 186 due to "Pattern not found: ^.*\%0c"; this was caused by 187 stridx finding a Name... at the beginning of the line; 188 zip.vim tried 4,$s/^.*\%0c//, but that doesn't work. 189 Fixed. 190 v7 Mar 22, 2006 * escaped some characters that can cause filename handling 191 problems. 192 v6 Dec 21, 2005 * writing to files not in directories caused problems - 193 fixed (pointed out by Christian Robinson) 194 v5 Nov 22, 2005 * report option workaround installed 195 v3 Oct 18, 2005 * <amatch> used instead of <afile> in autocmds 196 v2 Sep 16, 2005 * silenced some commands (avoiding hit-enter prompt) 197 * began testing under Windows; works thus far 198 * filetype detection fixed 199 Nov 03, 2005 * handles writing zipfiles across a network using 200 netrw#NetWrite() 201 v1 Sep 15, 2005 * Initial release, had browsing, reading, and writing 202 203 ============================================================================== 204 vim:tw=78:ts=8:ft=help:noet:norl:fdm=marker