{"id":13567585,"url":"https://github.com/wagoodman/tar-overlay","last_synced_at":"2025-04-11T00:42:58.949Z","repository":{"id":81986540,"uuid":"50197559","full_name":"wagoodman/tar-overlay","owner":"wagoodman","description":"A shell script which creates and manages named overlayfs mounts backed by the contents from tar files.","archived":false,"fork":false,"pushed_at":"2016-07-06T15:58:37.000Z","size":10,"stargazers_count":19,"open_issues_count":0,"forks_count":2,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-04-11T00:42:50.368Z","etag":null,"topics":["containers","overlayfs","systemd-nspawn","tar"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/wagoodman.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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":"2016-01-22T17:50:12.000Z","updated_at":"2024-10-25T06:40:51.000Z","dependencies_parsed_at":null,"dependency_job_id":"b04c6977-617d-42be-a376-a79e252f0e9d","html_url":"https://github.com/wagoodman/tar-overlay","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wagoodman%2Ftar-overlay","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wagoodman%2Ftar-overlay/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wagoodman%2Ftar-overlay/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wagoodman%2Ftar-overlay/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wagoodman","download_url":"https://codeload.github.com/wagoodman/tar-overlay/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248322602,"owners_count":21084336,"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":["containers","overlayfs","systemd-nspawn","tar"],"created_at":"2024-08-01T13:02:35.544Z","updated_at":"2025-04-11T00:42:58.915Z","avatar_url":"https://github.com/wagoodman.png","language":"Shell","funding_links":[],"categories":["Shell"],"sub_categories":[],"readme":"# Tar-Overlay\nA shell script which creates and manages named overlayfs mounts backed by the contents from tar files.\n\nNote: this is a work in progress, so it is not stable yet.\n\n## Example\nGiven a tar with a set of files, create two independent scratch 'instances' where you can add, modify,\nand delete files that can be reverted on command:\n\n1) install a tar, this becomes an immutable 'image':\n```\n[wagoodman@vm1 ~]$ tar-overlay install-image ~/Downloads/msgpack-python-0.4.6.tar.gz\n[wagoodman@vm1 ~]$ tar-overlay list-images\n   msgpack-python-0.4.6\n```\n\n2) create a few instances and mount them:\n```\n[wagoodman@vm1 ~]$ tar-overlay create-overlay foo msgpack-python-0.4.6\n[wagoodman@vm1 ~]$ tar-overlay create-overlay bar msgpack-python-0.4.6\n[wagoodman@vm1 ~]$ tar-overlay list-overlays\n   scratch1\n   scratch2\n\n[wagoodman@vm1 ~]$ tar-overlay mount-overlay foo\n   ~/bin/tar-overlay/store/instances/foo/rootfs\n\n[wagoodman@vm1 ~]$ tar-overlay mount-overlay bar\n   ~/bin/tar-overlay/store/instances/bar/rootfs\n```\nNote: the output for each mount attempt is where the instance mountpoint is.\n\n3) Make some changes in one of the instances (foo):\n```\n[wagoodman@vm1 ~]$ tree -L 1 ~/bin/tar-overlay/store/instances/foo/rootfs\n~/bin/tar-overlay/store/instances/foo/rootfs\n├── COPYING\n├── msgpack\n├── PKG-INFO\n├── README.rst\n├── setup.py\n└── test\n\n2 directories, 4 files\n\n[wagoodman@vm1 ~]$ rm -rf ~/bin/tar-overlay/store/instances/foo/rootfs/test\n```\n\nNotice that we can query which files have changed:\n```\n[wagoodman@vm1 ~]$ tar-overlay show-changes foo\n.\n└── test\n    ├── test_buffer.py\n    ├── test_case.py\n    ├── test_except.py\n    ├── test_extension.py\n    ├── test_format.py\n    ├── test_limits.py\n    ├── test_newspec.py\n    ├── test_obj.py\n    ├── test_pack.py\n    ├── test_read_size.py\n    ├── test_seq.py\n    ├── test_sequnpack.py\n    ├── test_subtype.py\n    ├── test_unpack.py\n    └── test_unpack_raw.py\n\n1 directories, 15 files\n```\n\nAlso notice that the other instance (bar) still has the original file:\n```\n[wagoodman@vm1 ~]$ tree -L 1 ~/bin/tar-overlay/store/instances/bar/rootfs\n~/bin/tar-overlay/store/instances/bar/rootfs\n├── COPYING\n├── msgpack\n├── PKG-INFO\n├── README.rst\n├── setup.py\n└── test\n\n2 directories, 4 files\n\n[wagoodman@vm1 ~]$ rm -rf ~/bin/tar-overlay/store/instances/bar/rootfs/test\n```\n(See, the 'test' dir is still there)\n\n4) Restore the 'foo' instance back to the original contents from the tar:\n```\n[wagoodman@vm1 ~]$ tar-overlay reset-overlay foo\n[wagoodman@vm1 ~]$ tree -L 1 ~/bin/tar-overlay/store/instances/foo/rootfs\n~/bin/tar-overlay/store/instances/foo/rootfs\n├── COPYING\n├── msgpack\n├── PKG-INFO\n├── README.rst\n├── setup.py\n└── test\n\n2 directories, 4 files\n\n```\n\n# Motivation\nThe motivation for this was to take a read-only directory tree and make several\nread-write 'instances' of that directory tree, where changes made in each instance would\nnot affect files in the other instances. Furthermore, there were benefits with\nhaving the functionality to restore any instance to the original directory tree,\nas if no modifications were done. This could all be done by making copies of the\ntar contents for each instance, however, some of these directory trees were 1 GB\nor more in size and only a few files are modified between all of the instances.\n\nDocker provides almost the same functionality via dockerfiles, however, I am\nnot using docker for this project... so building and managing images this way seemed\nawkward if I wasn't planning to use docker for containers. Instead, since overlayfs\nhas been integrated into the kernel and a wrapper script seemed simple enough to\nmake, tar-overlay was born!\n\n# Usage\n```\ntar-overlay [command] [options]\n\nImage commands:\n    install-image \u003ctar-file\u003e   Take the given tar and make it available as in immutable image.\n    list-images                List all known images.\n\nOverlay Commands:\n    create \u003cname\u003e \u003cimage-name\u003e  Instantiate an image (make an instance).\n    list                        List image instantiations.\n    mount \u003cname\u003e                Mount an instantiation for use.\n    mount-all                   Mount all overlays.\n    info \u003cname\u003e                 Show all information regardin the given overlay name.\n    rename \u003cname\u003e \u003cnew name\u003e    Rename the given instantiation.\n    reset \u003cname\u003e                Undo all changes made to original image.\n    show-changes \u003cname\u003e         Show a tree of all modified files\n    status \u003cname\u003e               Shows if the given overlay is mounted.\n    umount \u003cname\u003e               Unmount an instantiation.\n    umount-all                  Unmount all overlays.\n\nFuture Commands:\n    rename-image \u003ciamge-name\u003e    Rename the given image.\n    delete-image \u003cimage-name\u003e    Delete the given image.\n    mount-image                  Mounts an image directly (not advised).\n    umount-image                 Unmounts a directly mounted image.\n    delete \u003cname\u003e                Delete the given instantiation.\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwagoodman%2Ftar-overlay","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwagoodman%2Ftar-overlay","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwagoodman%2Ftar-overlay/lists"}