vim

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

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