{"id":25858181,"url":"https://github.com/atom/asar","last_synced_at":"2025-03-01T20:01:04.370Z","repository":{"id":21032554,"uuid":"24328822","full_name":"electron/asar","owner":"electron","description":"Simple extensive tar-like archive format with indexing","archived":false,"fork":false,"pushed_at":"2024-10-26T14:04:25.000Z","size":785,"stargazers_count":2564,"open_issues_count":16,"forks_count":249,"subscribers_count":70,"default_branch":"main","last_synced_at":"2024-10-29T11:12:35.510Z","etag":null,"topics":["asar","chrome","electron","javascript","pickle"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/electron.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":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2014-09-22T13:04:52.000Z","updated_at":"2024-10-29T09:44:27.000Z","dependencies_parsed_at":"2023-02-18T19:46:01.793Z","dependency_job_id":"cca214b0-09df-4fae-8fcc-bace69f8e13d","html_url":"https://github.com/electron/asar","commit_stats":{"total_commits":304,"total_committers":50,"mean_commits":6.08,"dds":0.7598684210526316,"last_synced_commit":"8a9959e2250eb58155e22c257dae242eda3efa0f"},"previous_names":["atom/asar"],"tags_count":71,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/electron%2Fasar","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/electron%2Fasar/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/electron%2Fasar/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/electron%2Fasar/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/electron","download_url":"https://codeload.github.com/electron/asar/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241418270,"owners_count":19959736,"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":["asar","chrome","electron","javascript","pickle"],"created_at":"2025-03-01T20:00:42.884Z","updated_at":"2025-03-01T20:01:04.364Z","avatar_url":"https://github.com/electron.png","language":"TypeScript","readme":"# @electron/asar - Electron Archive\n\n[![Test](https://github.com/electron/asar/actions/workflows/test.yml/badge.svg)](https://github.com/electron/asar/actions/workflows/test.yml)\n[![npm version](http://img.shields.io/npm/v/@electron/asar.svg)](https://npmjs.org/package/@electron/asar)\n\nAsar is a simple extensive archive format, it works like `tar` that concatenates\nall files together without compression, while having random access support.\n\n## Features\n\n* Support random access\n* Use JSON to store files' information\n* Very easy to write a parser\n\n## Command line utility\n\n### Install\n\nThis module requires Node 10 or later.\n\n```bash\n$ npm install --engine-strict @electron/asar\n```\n\n### Usage\n\n```bash\n$ asar --help\n\n  Usage: asar [options] [command]\n\n  Commands:\n\n    pack|p \u003cdir\u003e \u003coutput\u003e\n       create asar archive\n\n    list|l \u003carchive\u003e\n       list files of asar archive\n\n    extract-file|ef \u003carchive\u003e \u003cfilename\u003e\n       extract one file from archive\n\n    extract|e \u003carchive\u003e \u003cdest\u003e\n       extract archive\n\n\n  Options:\n\n    -h, --help     output usage information\n    -V, --version  output the version number\n\n```\n\n#### Excluding multiple resources from being packed\n\nGiven:\n```\n    app\n(a) ├── x1\n(b) ├── x2\n(c) ├── y3\n(d) │   ├── x1\n(e) │   └── z1\n(f) │       └── x2\n(g) └── z4\n(h)     └── w1\n```\n\nExclude: a, b\n```bash\n$ asar pack app app.asar --unpack-dir \"{x1,x2}\"\n```\n\nExclude: a, b, d, f\n```bash\n$ asar pack app app.asar --unpack-dir \"**/{x1,x2}\"\n```\n\nExclude: a, b, d, f, h\n```bash\n$ asar pack app app.asar --unpack-dir \"{**/x1,**/x2,z4/w1}\"\n```\n\n## Using programmatically\n\n### Example\n\n```javascript\nconst asar = require('@electron/asar');\n\nconst src = 'some/path/';\nconst dest = 'name.asar';\n\nawait asar.createPackage(src, dest);\nconsole.log('done.');\n```\n\nPlease note that there is currently **no** error handling provided!\n\n### Transform\nYou can pass in a `transform` option, that is a function, which either returns\nnothing, or a `stream.Transform`. The latter will be used on files that will be\nin the `.asar` file to transform them (e.g. compress).\n\n```javascript\nconst asar = require('@electron/asar');\n\nconst src = 'some/path/';\nconst dest = 'name.asar';\n\nfunction transform (filename) {\n  return new CustomTransformStream()\n}\n\nawait asar.createPackageWithOptions(src, dest, { transform: transform });\nconsole.log('done.');\n```\n\n## Format\n\nAsar uses [Pickle][pickle] to safely serialize binary value to file.\n\nThe format of asar is very flat:\n\n```\n| UInt32: header_size | String: header | Bytes: file1 | ... | Bytes: file42 |\n```\n\nThe `header_size` and `header` are serialized with [Pickle][pickle] class, and\n`header_size`'s [Pickle][pickle] object is 8 bytes.\n\nThe `header` is a JSON string, and the `header_size` is the size of `header`'s\n`Pickle` object.\n\nStructure of `header` is something like this:\n\n```json\n{\n   \"files\": {\n      \"tmp\": {\n         \"files\": {}\n      },\n      \"usr\" : {\n         \"files\": {\n           \"bin\": {\n             \"files\": {\n               \"ls\": {\n                 \"offset\": \"0\",\n                 \"size\": 100,\n                 \"executable\": true,\n                 \"integrity\": {\n                   \"algorithm\": \"SHA256\",\n                   \"hash\": \"...\",\n                   \"blockSize\": 1024,\n                   \"blocks\": [\"...\", \"...\"]\n                 }\n               },\n               \"cd\": {\n                 \"offset\": \"100\",\n                 \"size\": 100,\n                 \"executable\": true,\n                 \"integrity\": {\n                   \"algorithm\": \"SHA256\",\n                   \"hash\": \"...\",\n                   \"blockSize\": 1024,\n                   \"blocks\": [\"...\", \"...\"]\n                 }\n               }\n             }\n           }\n         }\n      },\n      \"etc\": {\n         \"files\": {\n           \"hosts\": {\n             \"offset\": \"200\",\n             \"size\": 32,\n             \"integrity\": {\n                \"algorithm\": \"SHA256\",\n                \"hash\": \"...\",\n                \"blockSize\": 1024,\n                \"blocks\": [\"...\", \"...\"]\n              }\n           }\n         }\n      }\n   }\n}\n```\n\n`offset` and `size` records the information to read the file from archive, the\n`offset` starts from 0 so you have to manually add the size of `header_size` and\n`header` to the `offset` to get the real offset of the file.\n\n`offset` is a UINT64 number represented in string, because there is no way to\nprecisely represent UINT64 in JavaScript `Number`. `size` is a JavaScript\n`Number` that is no larger than `Number.MAX_SAFE_INTEGER`, which has a value of\n`9007199254740991` and is about 8PB in size. We didn't store `size` in UINT64\nbecause file size in Node.js is represented as `Number` and it is not safe to\nconvert `Number` to UINT64.\n\n`integrity` is an object consisting of a few keys:\n* A hashing `algorithm`, currently only `SHA256` is supported.\n* A hex encoded `hash` value representing the hash of the entire file.\n* An array of hex encoded hashes for the `blocks` of the file.  i.e. for a blockSize of 4KB this array contains the hash of every block if you split the file into N 4KB blocks.\n* A integer value `blockSize` representing the size in bytes of each block in the `blocks` hashes above\n\n[pickle]: https://chromium.googlesource.com/chromium/src/+/main/base/pickle.h\n","funding_links":[],"categories":["Package"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fatom%2Fasar","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fatom%2Fasar","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fatom%2Fasar/lists"}