Skip to content
This repository


Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

A simple Ruby-esque interface to creating, extracting, and updating ZIP archives in 100% Ruby.

branch: master
= Archive::Zip - ZIP Archival Made Easy

The Archive::Zip library intends to provide a simple, yet complete and
Ruby-esque, interface to working with ZIP archives.

Basic archive creation and extraction can be handled using only a few methods.
More complex operations involving the manipulation of existing archives in place
(adding, removing, and modifying entries) are also possible with a little more
work.  Even adding advanced features such as new compression codecs are
supported with a moderate amount of effort.

== License

Copyright © 2010 Jeremy Bopp <jeremy at bopp dot net>

Licensed under the same terms as Ruby -- See the included LICENSE file for

== Installation/Removal

Download the GEM file and install it with:
  % sudo gem install archive-zip-VERSION.gem

or directly with:
  % sudo gem install archive-zip

Removal is the same in either case:
  % sudo gem uninstall archive-zip

== Example
More examples can be found in the +examples+ directory of the source

Create a few archives:
  gem 'archive-zip'  # Use require_gem for rubygems versions older than 0.9.0.
  require 'archive/zip'

  # Add a_directory and its contents to
  Archive::Zip.archive('', 'a_directory')

  # Add the contents of a_directory to
  Archive::Zip.archive('', 'a_directory/.')

  # Add a_file and a_directory and its contents to
  Archive::Zip.archive('', ['a_directory', 'a_file'])

  # Add only the files and symlinks contained in a_directory under the path
  # a/b/c/a_directory in
    :directories => false,
    :path_prefix => 'a/b/c'

  # Add the contents of a_directory to and encrypt Ruby source
  # files.
  require 'archive/zip/codec/null_encryption'
  require 'archive/zip/codec/traditional_encryption'
    :encryption_codec => lambda do |entry|
      if entry.file? and entry.zip_path =~ /\.rb$/ then
    :password => 'seakrit'

  # Create a new archive which will be written to a pipe.
  # Assume $stdout is the write end a pipe.
  # (ruby example.rb | cat >$stdout, :w) do |z|

Now extract those archives:
  gem 'archive-zip'  # Use require_gem for rubygems versions older than 0.9.0.
  require 'archive/zip'

  # Extract to a_destination.
  Archive::Zip.extract('', 'a_destination')

  # Extract to a_destination, skipping directory entries.
    :directories => false

  # Extract to a_destination, skipping symlinks.
    :symlinks => false

  # Extract to a_destination, skipping entries for which files
  # already exist but are newer or for which files do not exist at all.
    :create => false,
    :overwrite => :older

  # Extract to a_destination, decrypting the contents.
  Archive::Zip.extract('', 'a_destination', :password => 'seakrit')

== Features

1.  100% native Ruby.  (Well, almost... depends on zlib.)
2.  Archive creation and extraction is supported with only a few lines of code.
3.  Archives can be updated "in place" or dumped out to other files or pipes.
4.  Files, symlinks, and directories are supported within archives.
5.  Unix permission/mode bits are supported.
6.  Unix user and group ownerships are supported.
7.  Unix last accessed and last modified times are supported.
8.  Entry extension (AKA extra field) implementations can be added on the fly.
9.  Unknown entry extension types are preserved during archive processing.
10. The Deflate and Store compression codecs are supported out of the box.
11. More compression codecs can be added on the fly.
12. Traditional (weak) encryption is supported out of the box.

== Known Bugs/Limitations

1.  More testcases are needed.
2.  All file entries are archived and extracted in binary mode.  No attempt is
    made to normalize text files to the line ending convention of any target
3.  Hard links and device files are not currently supported within archives.
4.  Reading archives from non-seekable IO, such as pipes and sockets, is not
5.  MSDOS permission attributes are not supported.
6.  Strong encryption is not supported.
7.  Zip64 is not supported.
8.  Digital signatures are not supported.

== Contributing

Contributions for bug fixes, documentation, extensions, tests, etc. are
encouraged.  Please read the file HACKING for details.
Something went wrong with that request. Please try again.