*pi_zip.txt*	For Vim version 9.2.  Last change: 2026 Aug 19

				+====================+
				| Zip File Interface |
				+====================+

Author:  Charles E. Campbell  <NcampObell@SdrPchip.AorgM-NOSPAM>
	  (remove NOSPAM from Campbell's email first)
Copyright: Copyright (C) 2005-2015 Charles E Campbell	 *zip-copyright*
	The VIM LICENSE (see |copyright|) applies to the files in this
	package, including zipPlugin.vim, zip.vim, and pi_zip.vim.  except use
	"zip.vim" instead of "VIM".  Like anything else that's free, zip.vim
	and its associated files are provided *as is* and comes with no
	warranty of any kind, either expressed or implied.  No guarantees of
	merchantability.  No guarantees of suitability for any purpose.  By
	using this plugin, you agree that in no event will the copyright
	holder be liable for any damages resulting from the use of this
	software. Use at your own risk!

==============================================================================
1. Contents						*zip* *zip-contents*
   1. Contents................................................|zip-contents|
   2. Usage...................................................|zip-usage|
   3. Additional Extensions...................................|zip-extension|
   4. History.................................................|zip-history|

==============================================================================
2. Usage						*zip-usage* *zip-manual*

   When one edits a *.zip file, this plugin will handle displaying a
   contents page.  Select a file to edit by moving the cursor atop
   the desired file, then hit the <return> key.  After editing, one may
   also write to the file.  Currently, one may not make a new file in
   zip archives via the plugin.

   The zip plugin tries to detect some common path traversal attack
   patterns, but it may not catch all possible cases.  Please be very
   careful when using this plugin with untrusted input.

   COMMANDS~
								*zip-x*
   x : extract a listed file when the cursor is atop it

   OPTIONS~

							*g:zip_nomax*

   If this variable exists and is true, the file window will not be
   automatically maximized when opened.

							*g:zip_unzipcmd*
   Use these options to specify the program which does the duty of "unzip" and
   the required argument switches.
   It's used during browsing.  By default: >
	let g:zip_unzipcmd= "unzip"
	let g:zip_unzipcmd_browseopt= "-Z1"
	let g:zip_unzipcmd_readopt= "-p"
<
   Note: a `--` is appended after the g:zip_unzipcmd_browseopt and
   g:zip_unzipcmd_readopt settings to indicate the end of options.

							*g:zip_zipcmd*
   Use these options to specify the program which does the duty of "zip" and
   the required argument switches.
   It's used during the writing (updating) of a file already in a zip
   file; by default: >
	let g:zip_zipcmd= "zip"
	let g:zip_zipcmd_deleteopt= "-d"
	let g:zip_zipcmd_updateopt= "-u"
<
							*g:zip_extractcmd*
   This option specifies the program (and any options needed) used to
   extract a file from a zip archive.  By default, >
	let g:zip_extractcmd= g:zip_unzipcmd
	let g:zip_extractcmd_extractopt= "-o"
<
							*g:zip_exec*
   For security reasons, one may prevent that Vim runs executables
   automatically when opening a buffer.  This option (default: "1")
   can be used to prevent executing the "unzip" command when set to
   "0": >
	let g:zip_exec=0
<
   FALLBACK TO POWERSHELL~

							*g:zip_pwsh*
   This plugin will first attempt to use the (more capable) GNU zip/unzip
   commands.  If these commands are not available or fail, and the user is
   using PowerShell, the plugin will fall back to a PowerShell cmdlet.
   The PowerShell cmdlets are limited: they cannot write or extract files
   within subdirectories of a zip archive.  The advantage, however, is that
   no separate unzip binary needs to be installed.  The 'shell' option will
   be checked whether to choose "pwsh" or "powershell", or set `g:zip_pwsh`.
   If both are available, this plugin will prefer pwsh. Default value of
   "g:zip_pwsh" is an empty string, which would not overwrite the 'shell'
   option configuration.  This functionality is not turned on by default on
   MS-Windows, since the default 'shell' is "cmd.exe". For example: >
	let g:zip_pwsh='powershell'
<
   PREVENTING LOADING~

   If for some reason you do not wish to use vim to examine zipped files,
   you may put the following two variables into your <.vimrc> to prevent
   the zip plugin from loading: >

	let g:loaded_zipPlugin= 1
	let g:loaded_zip      = 1
<

==============================================================================
3. Additional Extensions					*zip-extension*

   Apparently there are a number of archivers which generate zip files that
   don't use the .zip extension (.jar, .xpi, etc).  To handle such files,
   place a line in your <.vimrc> file: >

	au BufReadCmd *.jar,*.xpi call zip#Browse(expand("<amatch>"))
<
   One can simply extend this line to accommodate additional extensions that
   should be treated as zip files.

   Alternatively, one may change *g:zipPlugin_ext* in one's .vimrc.
   Currently (as of May 2026) it holds: >

        let g:zipPlugin_ext='*.aar,*.apk,*.cbz,*.celzip,*.crtx,*.docm,*.docx,
       \ *.dotm,*.dotx,*.ear,*.epub,*.gcsx,*.glox,*.gqsx,*.ja,*.jar,*.kmz,
       \ *.odb,*.odc,*.odf,*.odg,*.odi,*.odm,*.odp,*.ods,*.odt,*.otc,*.otf,
       \ *.otg,*.oth,*.oti,*.otp,*.ots,*.ott,*.oxt,*.pkpass,*.potm,*.potx,
       \ *.ppam,*.ppsm,*.ppsx,*.pptm,*.pptx,*.sldx,*.thmx,*.vdw,*.war,*.whl,
       \ *.wsz, *.xap,*.xlam,*.xlsb,*.xlsm,*.xlsx,*.xltm,*.xltx,*.xpi,*.zip'

==============================================================================
4. History							*zip-history* {{{1
   unreleased:
       Jul 25, 2026 * support both Windows PowerShell 5 and pwsh 7+
       Sep 19, 2025 * support PowerShell Core
       Jul 12, 2025 * drop ../ on write to prevent path traversal attacks
       Mar 11, 2025 * handle filenames with leading '-' correctly
       Aug 21, 2024 * simplify condition to detect MS-Windows
       Aug 18, 2024 * correctly handle special globbing chars
       Aug 05, 2024 * clean-up and make it work with shellslash on Windows
       Aug 05, 2024 * workaround for the FreeBSD's unzip
       Aug 04, 2024 * escape '[' in name of file to be extracted
       Jul 30, 2024 * fix opening remote zipfile
       Jul 24, 2024 * use delete() function
       Jul 23, 2024 * fix 'x' command
       Jun 16, 2024 * handle whitespace on Windows properly (#14998)
   v33 Dec 07, 2021 * *.xlam mentioned twice in zipPlugin
   v32 Oct 22, 2021 * to avoid an issue with a vim 8.2 patch, zipfile: has
		      been changed to zipfile:// . This often shows up
		      as zipfile:/// with zipped files that are root-based.
   v29 Apr 02, 2017 * (Klartext) reported that an encrypted zip file could
		      opened but the swapfile held unencrypted contents.
		      The solution is to edit the contents of a zip file
		      using the |:noswapfile| modifier.
   v28 Oct 08, 2014 * changed the sanity checks for executables to reflect
		      the command actually to be attempted in zip#Read()
		      and zip#Write()
		    * added the extraction of a file capability
       Nov 30, 2015 * added *.epub to the |g:zipPlugin_ext| list
       Sep 13, 2016 * added *.apk to the |g:zipPlugin_ext| list and
		      sorted the suffices.
   v27 Jul 02, 2013 * sanity check: zipfile must have "PK" as its first
		      two bytes.
		    * modified to allow zipfile: entries in quickfix lists
   v26 Nov 15, 2012 * (Jason Spiro) provided a lot of new extensions that
		      are synonyms for .zip
   v25 Jun 27, 2011 * using keepj with unzip -Z
		      (consistent with the -p variant)
		    * (Ben Staniford) now uses
			has("win32unix") && executable("cygpath")
		      before converting to cygwin-style paths
   v24 Jun 21, 2010 * (Cédric Bosdonnat) unzip seems to need its filenames
		      fnameescape'd as well as shellquote'd
		    * (Motoya Kurotsu) inserted keepj before 0d to protect
		      jump list
   v17 May 09, 2008 * arno caught a security bug
   v15 Sep 07, 2007 * &shq now used if not the empty string for g:zip_shq
   v14 May 07, 2007 * using b:zipfile instead of w:zipfile to avoid problem
                      when editing alternate file to bring up a zipfile
   v10 May 02, 2006 * now using "redraw then echo" to show messages, instead
                      of "echo and prompt user"
		    * g:zip_shq provided to allow for quoting control for the
		      command being passed via :r! ... commands.
   v8 Apr 10, 2006 * Bram Moolenaar reported that he received an error message
                     due to "Pattern not found: ^.*\%0c"; this was caused by
		     stridx finding a Name... at the beginning of the line;
		     zip.vim tried 4,$s/^.*\%0c//, but that doesn't work.
		     Fixed.
   v7 Mar 22, 2006 * escaped some characters that can cause filename handling
                     problems.
   v6 Dec 21, 2005 * writing to files not in directories caused problems -
                     fixed (pointed out by Christian Robinson)
   v5 Nov 22, 2005 * report option workaround installed
   v3 Oct 18, 2005 * <amatch> used instead of <afile> in autocmds
   v2 Sep 16, 2005 * silenced some commands (avoiding hit-enter prompt)
                   * began testing under Windows; works thus far
		   * filetype detection fixed
      Nov 03, 2005 * handles writing zipfiles across a network using
                     netrw#NetWrite()
   v1 Sep 15, 2005 * Initial release, had browsing, reading, and writing

==============================================================================
vim:tw=78:ts=8:ft=help:noet:norl:fdm=marker
