{"id":22006089,"url":"https://github.com/rubyzip/rubyzip","last_synced_at":"2025-05-14T11:07:57.331Z","repository":{"id":1085929,"uuid":"935822","full_name":"rubyzip/rubyzip","owner":"rubyzip","description":"Official Rubyzip repository","archived":false,"fork":false,"pushed_at":"2025-02-10T08:07:30.000Z","size":2841,"stargazers_count":1376,"open_issues_count":35,"forks_count":312,"subscribers_count":39,"default_branch":"master","last_synced_at":"2025-04-30T08:01:49.396Z","etag":null,"topics":["encryption","ruby","rubyzip","zip-extraction"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-2-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rubyzip.png","metadata":{"files":{"readme":"README.md","changelog":"Changelog.md","contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2010-09-24T10:50:15.000Z","updated_at":"2025-04-28T22:48:08.000Z","dependencies_parsed_at":"2023-02-16T12:45:34.974Z","dependency_job_id":"e753aa18-e445-4325-9158-1f3edead0cf9","html_url":"https://github.com/rubyzip/rubyzip","commit_stats":{"total_commits":1277,"total_committers":133,"mean_commits":9.601503759398497,"dds":0.6985121378230227,"last_synced_commit":"5b0d25e416814beb062c707c1319eb79b9d4272f"},"previous_names":[],"tags_count":33,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rubyzip%2Frubyzip","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rubyzip%2Frubyzip/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rubyzip%2Frubyzip/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rubyzip%2Frubyzip/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rubyzip","download_url":"https://codeload.github.com/rubyzip/rubyzip/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251735798,"owners_count":21635393,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["encryption","ruby","rubyzip","zip-extraction"],"created_at":"2024-11-30T01:08:54.975Z","updated_at":"2025-05-06T20:38:21.987Z","avatar_url":"https://github.com/rubyzip.png","language":"Ruby","readme":"# rubyzip\n\n[![Gem Version](https://badge.fury.io/rb/rubyzip.svg)](http://badge.fury.io/rb/rubyzip)\n[![Tests](https://github.com/rubyzip/rubyzip/actions/workflows/tests.yml/badge.svg)](https://github.com/rubyzip/rubyzip/actions/workflows/tests.yml)\n[![Linter](https://github.com/rubyzip/rubyzip/actions/workflows/lint.yml/badge.svg)](https://github.com/rubyzip/rubyzip/actions/workflows/lint.yml)\n[![Code Climate](https://codeclimate.com/github/rubyzip/rubyzip.svg)](https://codeclimate.com/github/rubyzip/rubyzip)\n[![Coverage Status](https://img.shields.io/coveralls/rubyzip/rubyzip.svg)](https://coveralls.io/r/rubyzip/rubyzip?branch=master)\n\nRubyzip is a ruby library for reading and writing zip files.\n\n## Important notes\n\n### Updating to version 3.0\n\nThe public API of some classes has been modernized to use named parameters for optional arguments. Please check your usage of the following Rubyzip classes:\n* `File`\n* `Entry`\n* `InputStream`\n* `OutputStream`\n\n**Please see [Updating to version 3.x](https://github.com/rubyzip/rubyzip/wiki/Updating-to-version-3.x) in the wiki for details.**\n\n## Requirements\n\nVersion 3.x requires at least Ruby 3.0.\n\nVersion 2.x requires at least Ruby 2.4, and is known to work on Ruby 3.x.\n\nIt is not recommended to use any versions of Rubyzip earlier than 2.3 due to security issues.\n\n## Installation\n\nRubyzip is available on RubyGems:\n\n```\ngem install rubyzip\n```\n\nOr in your Gemfile:\n\n```ruby\ngem 'rubyzip'\n```\n\n## Usage\n\n### Basic zip archive creation\n\n```ruby\nrequire 'rubygems'\nrequire 'zip'\n\nfolder = \"Users/me/Desktop/stuff_to_zip\"\ninput_filenames = ['image.jpg', 'description.txt', 'stats.csv']\n\nzipfile_name = \"/Users/me/Desktop/archive.zip\"\n\nZip::File.open(zipfile_name, create: true) do |zipfile|\n  input_filenames.each do |filename|\n    # Two arguments:\n    # - The name of the file as it will appear in the archive\n    # - The original file, including the path to find it\n    zipfile.add(filename, File.join(folder, filename))\n  end\n  zipfile.get_output_stream(\"myFile\") { |f| f.write \"myFile contains just this\" }\nend\n```\n\n### Zipping a directory recursively\n\nCopy from [here](https://github.com/rubyzip/rubyzip/blob/9d891f7353e66052283562d3e252fe380bb4b199/samples/example_recursive.rb)\n\n```ruby\nrequire 'zip'\n\n# This is a simple example which uses rubyzip to\n# recursively generate a zip file from the contents of\n# a specified directory. The directory itself is not\n# included in the archive, rather just its contents.\n#\n# Usage:\n#   directory_to_zip = \"/tmp/input\"\n#   output_file = \"/tmp/out.zip\"\n#   zf = ZipFileGenerator.new(directory_to_zip, output_file)\n#   zf.write()\nclass ZipFileGenerator\n  # Initialize with the directory to zip and the location of the output archive.\n  def initialize(input_dir, output_file)\n    @input_dir = input_dir\n    @output_file = output_file\n  end\n\n  # Zip the input directory.\n  def write\n    entries = Dir.entries(@input_dir) - %w[. ..]\n\n    ::Zip::File.open(@output_file, create: true) do |zipfile|\n      write_entries entries, '', zipfile\n    end\n  end\n\n  private\n\n  # A helper method to make the recursion work.\n  def write_entries(entries, path, zipfile)\n    entries.each do |e|\n      zipfile_path = path == '' ? e : File.join(path, e)\n      disk_file_path = File.join(@input_dir, zipfile_path)\n\n      if File.directory? disk_file_path\n        recursively_deflate_directory(disk_file_path, zipfile, zipfile_path)\n      else\n        put_into_archive(disk_file_path, zipfile, zipfile_path)\n      end\n    end\n  end\n\n  def recursively_deflate_directory(disk_file_path, zipfile, zipfile_path)\n    zipfile.mkdir zipfile_path\n    subdir = Dir.entries(disk_file_path) - %w[. ..]\n    write_entries subdir, zipfile_path, zipfile\n  end\n\n  def put_into_archive(disk_file_path, zipfile, zipfile_path)\n    zipfile.add(zipfile_path, disk_file_path)\n  end\nend\n```\n\n### Save zip archive entries sorted by name\n\nTo save zip archives with their entries sorted by name (see below), set `::Zip.sort_entries` to `true`\n\n```\nVegetable/\nVegetable/bean\nVegetable/carrot\nVegetable/celery\nfruit/\nfruit/apple\nfruit/kiwi\nfruit/mango\nfruit/orange\n```\n\nOpening an existing zip file with this option set will not change the order of the entries automatically. Altering the zip file - adding an entry, renaming an entry, adding or changing the archive comment, etc - will cause the ordering to be applied when closing the file.\n\n### Default permissions of zip archives\n\nOn Posix file systems the default file permissions applied to a new archive\nare (0666 - umask), which mimics the behavior of standard tools such as `touch`.\n\nOn Windows the default file permissions are set to 0644 as suggested by the\n[Ruby File documentation](http://ruby-doc.org/core-2.2.2/File.html).\n\nWhen modifying a zip archive the file permissions of the archive are preserved.\n\n### Reading a Zip file\n\n```ruby\nMAX_SIZE = 1024**2 # 1MiB (but of course you can increase this)\nZip::File.open('foo.zip') do |zip_file|\n  # Handle entries one by one\n  zip_file.each do |entry|\n    puts \"Extracting #{entry.name}\"\n    raise 'File too large when extracted' if entry.size \u003e MAX_SIZE\n\n    # Extract to file or directory based on name in the archive\n    entry.extract\n\n    # Read into memory\n    content = entry.get_input_stream.read\n  end\n\n  # Find specific entry\n  entry = zip_file.glob('*.csv').first\n  raise 'File too large when extracted' if entry.size \u003e MAX_SIZE\n  puts entry.get_input_stream.read\nend\n```\n\n### Notes on `Zip::InputStream`\n\n`Zip::InputStream` can be used for faster reading of zip file content because it does not read the Central directory up front.\n\nThere is one exception where it can not work however, and this is if the file does not contain enough information in the local entry headers to extract an entry. This is indicated in an entry by the General Purpose Flag bit 3 being set.\n\n\u003e If bit 3 (0x08) of the general-purpose flags field is set, then the CRC-32 and file sizes are not known when the header is written. The fields in the local header are filled with zero, and the CRC-32 and size are appended in a 12-byte structure (optionally preceded by a 4-byte signature) immediately after the compressed data.\n\nIf `Zip::InputStream` finds such an entry in the zip archive it will raise an exception (`Zip::StreamingError`).\n\n`Zip::InputStream` is not designed to be used for random access in a zip file. When performing any operations on an entry that you are accessing via `Zip::InputStream.get_next_entry` then you should complete any such operations before the next call to `get_next_entry`.\n\n```ruby\nzip_stream = Zip::InputStream.new(File.open('file.zip'))\n\nwhile entry = zip_stream.get_next_entry\n  # All required operations on `entry` go here.\nend\n```\n\nAny attempt to move about in a zip file opened with `Zip::InputStream` could result in the incorrect entry being accessed and/or Zlib buffer errors. If you need random access in a zip file, use `Zip::File`.\n\n### Password Protection (Experimental)\n\nRubyzip supports reading/writing zip files with traditional zip encryption (a.k.a. \"ZipCrypto\"). AES encryption is not yet supported. It can be used with buffer streams, e.g.:\n\n#### Version 2.x\n\n```ruby\n# Writing.\nenc = Zip::TraditionalEncrypter.new('password')\nbuffer = Zip::OutputStream.write_buffer(::StringIO.new(''), enc) do |output|\n  output.put_next_entry(\"my_file.txt\")\n  output.write my_data\nend\n\n# Reading.\ndec = Zip::TraditionalDecrypter.new('password')\nZip::InputStream.open(buffer, 0, dec) do |input|\n  entry = input.get_next_entry\n  puts \"Contents of '#{entry.name}':\"\n  puts input.read\nend\n```\n\n#### Version 3.x\n\n```ruby\n# Writing.\nenc = Zip::TraditionalEncrypter.new('password')\nbuffer = Zip::OutputStream.write_buffer(encrypter: enc) do |output|\n  output.put_next_entry(\"my_file.txt\")\n  output.write my_data\nend\n\n# Reading.\ndec = Zip::TraditionalDecrypter.new('password')\nZip::InputStream.open(buffer, decrypter: dec) do |input|\n  entry = input.get_next_entry\n  puts \"Contents of '#{entry.name}':\"\n  puts input.read\nend\n```\n\n_This is an experimental feature and the interface for encryption may change in future versions._\n\n## Known issues\n\n### Modify docx file with rubyzip\n\nUse `write_buffer` instead `open`. Thanks to @jondruse\n\n```ruby\nbuffer = Zip::OutputStream.write_buffer do |out|\n  @zip_file.entries.each do |e|\n    unless [DOCUMENT_FILE_PATH, RELS_FILE_PATH].include?(e.name)\n      out.put_next_entry(e.name)\n      out.write e.get_input_stream.read\n    end\n  end\n\n  out.put_next_entry(DOCUMENT_FILE_PATH)\n  out.write xml_doc.to_xml(:indent =\u003e 0).gsub(\"\\n\",\"\")\n\n  out.put_next_entry(RELS_FILE_PATH)\n  out.write rels.to_xml(:indent =\u003e 0).gsub(\"\\n\",\"\")\nend\n\nFile.open(new_path, \"wb\") {|f| f.write(buffer.string) }\n```\n\n## Configuration\n\n### Existing Files\n\nBy default, rubyzip will not overwrite files if they already exist inside of the extracted path. To change this behavior, you may specify a configuration option like so:\n\n```ruby\nZip.on_exists_proc = true\n```\n\nIf you're using rubyzip with rails, consider placing this snippet of code in an initializer file such as `config/initializers/rubyzip.rb`\n\nAdditionally, if you want to configure rubyzip to overwrite existing files while creating a .zip file, you can do so with the following:\n\n```ruby\nZip.continue_on_exists_proc = true\n```\n\n### Non-ASCII Names\n\nIf you want to store non-english names and want to open them on Windows(pre 7) you need to set this option:\n\n```ruby\nZip.unicode_names = true\n```\n\nSometimes file names inside zip contain non-ASCII characters. If you can assume which encoding was used for such names and want to be able to find such entries using `find_entry` then you can force assumed encoding like so:\n\n```ruby\nZip.force_entry_names_encoding = 'UTF-8'\n```\n\nAllowed encoding names are the same as accepted by `String#force_encoding`\n\n### Date Validation\n\nSome zip files might have an invalid date format, which will raise a warning. You can hide this warning with the following setting:\n\n```ruby\nZip.warn_invalid_date = false\n```\n\n### Size Validation\n\nBy default (in rubyzip \u003e= 2.0), rubyzip's `extract` method checks that an entry's reported uncompressed size is not (significantly) smaller than its actual size. This is to help you protect your application against [zip bombs](https://en.wikipedia.org/wiki/Zip_bomb). Before `extract`ing an entry, you should check that its size is in the range you expect. For example, if your application supports processing up to 100 files at once, each up to 10MiB, your zip extraction code might look like:\n\n```ruby\nMAX_FILE_SIZE = 10 * 1024**2 # 10MiB\nMAX_FILES = 100\nZip::File.open('foo.zip') do |zip_file|\n  num_files = 0\n  zip_file.each do |entry|\n    num_files += 1 if entry.file?\n    raise 'Too many extracted files' if num_files \u003e MAX_FILES\n    raise 'File too large when extracted' if entry.size \u003e MAX_FILE_SIZE\n    entry.extract\n  end\nend\n```\n\nIf you need to extract zip files that report incorrect uncompressed sizes and you really trust them not too be too large, you can disable this setting with\n```ruby\nZip.validate_entry_sizes = false\n```\n\nNote that if you use the lower level `Zip::InputStream` interface, `rubyzip` does *not* check the entry `size`s. In this case, the caller is responsible for making sure it does not read more data than expected from the input stream.\n\n### Compression level\n\nWhen adding entries to a zip archive you can set the compression level to trade-off compressed size against compression speed. By default this is set to the same as the underlying Zlib library's default (`Zlib::DEFAULT_COMPRESSION`), which is somewhere in the middle.\n\nYou can configure the default compression level with:\n\n```ruby\nZip.default_compression = X\n```\n\nWhere X is an integer between 0 and 9, inclusive. If this option is set to 0 (`Zlib::NO_COMPRESSION`) then entries will be stored in the zip archive uncompressed. A value of 1 (`Zlib::BEST_SPEED`) gives the fastest compression and 9 (`Zlib::BEST_COMPRESSION`) gives the smallest compressed file size.\n\nThis can also be set for each archive as an option to `Zip::File`:\n\n```ruby\nZip::File.open('foo.zip', create:true, compression_level: 9) do |zip|\n  zip.add ...\nend\n```\n\n### Zip64 Support\n\nSince version 3.0, Zip64 support is enabled for writing by default. To disable it do this:\n\n```ruby\nZip.write_zip64_support = false\n```\n\nPrior to version 3.0, Zip64 support is disabled for writing by default.\n\n_NOTE_: If Zip64 write support is enabled then any extractor subsequently used may also require Zip64 support to read from the resultant archive.\n\n### Block Form\n\nYou can set multiple settings at the same time by using a block:\n\n```ruby\n  Zip.setup do |c|\n    c.on_exists_proc = true\n    c.continue_on_exists_proc = true\n    c.unicode_names = true\n    c.default_compression = Zlib::BEST_COMPRESSION\n  end\n```\n\n## Compatibility\n\nRubyzip is known to run on a number of platforms and under a number of different Ruby versions.\n\n### Version 2.3.x\n\nRubyzip 2.3 is known to work on MRI 2.4 to 3.4 on Linux and Mac, and JRuby and Truffleruby on Linux. There are known issues with Windows which have been fixed on the development branch. Please [let us know](https://github.com/rubyzip/rubyzip/pulls) if you know Rubyzip 2.3 works on a platform/Ruby combination not listed here, or [raise an issue](https://github.com/rubyzip/rubyzip/issues) if you see a failure where we think it should work.\n\n### Next (version 3.0.0)\n\nPlease see the table below for what we think the current situation is. Note: an empty cell means \"unknown\", not \"does not work\".\n\n| OS/Ruby | 3.0 | 3.1 | 3.2 | 3.3 | 3.4 | Head | JRuby 9.4.9.0 | JRuby Head | Truffleruby 24.1.1 | Truffleruby Head |\n|---------|-----|-----|-----|-----|-----|------|---------------|------------|--------------------|------------------|\n|Ubuntu 22.04| CI | CI | CI | CI | CI | ci | CI | ci | CI | ci |\n|Mac OS 14.7.2| CI | CI | CI | CI | CI | ci | x |  | x |  |\n|Windows Server 2022| CI |  |  |  | CI\u0026nbsp;mswin\u003c/br\u003eCI\u0026nbsp;ucrt |  |  |  |  |  |\n\nKey: `CI` - tested in CI, should work; `ci` - tested in CI, might fail; `x` - known working; `o` - known failing.\n\nRubies 3.1+ are also tested separately with YJIT turned on (Ubuntu and Mac OS).\n\nSee [the Actions tab](https://github.com/rubyzip/rubyzip/actions) in GitHub for full details.\n\nPlease [raise a PR](https://github.com/rubyzip/rubyzip/pulls) if you know Rubyzip works on a platform/Ruby combination not listed here, or [raise an issue](https://github.com/rubyzip/rubyzip/issues) if you see a failure where we think it should work.\n\n## Developing\n\nInstall the dependencies:\n\n```shell\nbundle install\n```\n\nRun the tests with `rake`:\n\n```shell\nrake\n```\n\nPlease also run `rubocop` over your changes.\n\nOur CI runs on [GitHub Actions](https://github.com/rubyzip/rubyzip/actions). Please note that `rubocop` is run as part of the CI configuration and will fail a build if errors are found.\n\n## Website and Project Home\n\nhttp://github.com/rubyzip/rubyzip\n\nhttp://rdoc.info/github/rubyzip/rubyzip/master/frames\n\n## Authors\n\nSee https://github.com/rubyzip/rubyzip/graphs/contributors for a comprehensive list.\n\n### Current maintainers\n\n* Robert Haines (@hainesr)\n* John Lees-Miller (@jdleesmiller)\n* Oleksandr Simonov (@simonoff)\n\n### Original author\n\n* Thomas Sondergaard\n\n## License\n\nRubyzip is distributed under the same license as Ruby. In practice this means you can use it under the terms of the Ruby License or the 2-Clause BSD License. See https://www.ruby-lang.org/en/about/license.txt and LICENSE.md for details.\n\n## Research notice\nPlease note that this repository is participating in a study into sustainability\n of open source projects. Data will be gathered about this repository for\n approximately the next 12 months, starting from June 2021.\n\nData collected will include number of contributors, number of PRs, time taken to\n close/merge these PRs, and issues closed.\n\nFor more information, please visit\n[our informational page](https://sustainable-open-science-and-software.github.io/) or download our [participant information sheet](https://sustainable-open-science-and-software.github.io/assets/PIS_sustainable_software.pdf).\n","funding_links":[],"categories":["Ruby","Gems"],"sub_categories":["Misc"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frubyzip%2Frubyzip","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frubyzip%2Frubyzip","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frubyzip%2Frubyzip/lists"}