diff --git a/README.md b/README.md index 3540fda..49e7942 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,27 @@ Have you ever wanted to be able to do `find -type f -name "*.ml"`, or any other search command, only inside a tar file? If you've experienced any of the above, this is your lucky day! Just mount the -tar file to a directory: +tar file to a directory with fusetar! This program allows you to mount a tar file +as if it were a disk or some other filesystem-containing device. The files inside +the archive are presented transparently as if they were files in a regular filesystem. + +Some advantages of doing this instead of just extracting the tarball: + +This does not require extraction - you can just mount, take a peek, search through files and copy files out, then unmount. This program only performs read operations, the archive is not modified. + +This also means that your filesystem is not polluted. For example, if you wanted to search for a particular file's contents, you would normally have to extract the archive and search with `find`. If the archive is large, this is potentially expensive. With this program you don't have to do any of that - just mount it! + +It doesn't keep the entire file in memory, so you can still access arbitrarily large tar files. File contents will only be fetched from disk when requested. + +Finally, your access to the archive is fully transparent. You do not need to learn any flags or anything - any commands that search through, index or otherwise access files will now work on tar. + +Some disadvantages: + +It's always read-only, so the contents of your archive are preserved. Tar is a streaming format, and it is quite awkward to try to make changes/additions to it, which is why the program currently does not support write operations. + +I/O performance may be affected. As mentioned, tar is a streaming format, and therefore file access can be inefficient. + +# Examples ```sh $ fusetar my-archive.tar mnt/ @@ -17,6 +37,8 @@ $ fusetar my-archive.tar mnt/ And just like that, everything inside the tarball is available to you as a read-only file system, to search, read or do whatever else. +## Debian rootfs + An example with the debian rootfs: ```sh @@ -25,14 +47,12 @@ $ wget https://github.com/kbaraniak/debian-rootfs/releases/download/bookworm-270 $ xz -d debian-amd64-bookworm-rootfs-270224.tar.xz $ mkdir -p mnt $ fusetar debian-amd64-bookworm-rootfs-270224.tar mnt/ -$ ls debian-amd64-bookworm-rootfs-270224.tar.xz +$ ls mnt/ bin boot dev etc home lib lib64 media mnt opt proc root run sbin srv sys tmp usr var ``` As you can see, the root file system inside the tar archive is transparently presented to you now under your mounted directory! -Note that it is read-only. Tar is a streaming format, and it is quite awkward to try to make changes/additions to it. - With that being said, if you absolutely need to write files to the directory (but not to the archive), it is quite easy to make this directory writable - you can simply use overlayfs to overlay an empty directory over this mount. This way, your changes would be preserved inside a separate directory, while unchanged content from the archive remains available: ```sh @@ -65,4 +85,26 @@ dr-xr-xr-x 1 root root 0 Feb 27 2024 sys drwxr-xr-x 1 root root 0 Jul 2 2023 tmp drwxr-xr-x 1 root root 0 Jul 2 2023 usr drwxr-xr-x 1 root root 0 Feb 27 2024 var -``` \ No newline at end of file +``` + + +# Build + +In order to build this program, you need to have the following installed: + +- ocaml 5.3 +- dune 3 +- ocamlfuse +- findlib + +You can install all of these through opam, or through your distribution's package manager if your distribution packages them. + +Once you have these, you can build with `dune build`, and install with `dune install`. You can tell it where to install, e.g. `dune install --prefix /usr/local/`. + +## Nix + +If you are on NixOS, or are willing to install the nix package manager, you can also use the provided `default.nix` (just run `nix-build`). This will download all dependancies and build. It should produce a symlink called `result`, which will point to the results (containing the produced binary under bin/). You can then place the binary wherever you like. + +For development purposes, you can also use the provided `shell.nix`, with `nix-shell`. This will drop you in a development shell, with all necessary packages to build & develop. + +If you have nix and direnv (with nix-direnv) installed, you can simply allow the provided .env file. This will automatically put you in a shell environment with all necessary packages.