| Name | listfs JSON |
| Version |
0.6.1
JSON |
| download |
| home_page | None |
| Summary | Mount file listings as a FUSE filesystem |
| upload_time | 2025-02-06 04:03:43 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.12 |
| license | None |
| keywords |
backup
fuse
lto
tape
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# listfs-py
* `listfs` mounts file listings as a filesystem.
* Useful with `find` and `ncdu`.
* Inspect file and directory origin with `cat` or `getfattr -d`.
* Supported listing type summary (more detail below):
* basic lines of paths
* `find -ls`
* `tar -c -vv`
* tabular text: `mtime bytes path`
* jsonl: `["mtime", bytes, "path"]`
* jsonl: `["mtime", bytes, blocks_1k, "path"]`
* jsonl: `{"t":"mtime", "m":"mode", "s":bytes, "p":"path"}`
## Installation
* `uv tool install listfs`
* If you get an installation error, make sure that the build dependencies are installed:
* Fedora: `sudo dnf install python python3-devel fuse3 fuse3-devel pkg-config gcc`
* Debian: `sudo apt install python3 python3-dev fuse3 libfuse3-dev pkg-config gcc`
## Usage
```text
listfs. Mount file listings as a FUSE filesystem.
Usage:
listfs [-o MOUNT_OPTIONS] [--foreground]
([--skip-components=N] [--prefix-dir=DIR] LISTING)...
MOUNTPOINT
listfs -h | --help | --help-formats | --version
Arguments:
LISTING Path to a listing file.
Must be in a supported format.
May be compressed with zstd, gzip, bzip2, lz4, or xz.
See --help-formats for supported formats.
MOUNTPOINT Directory where the filesystem will be mounted.
Options:
-o --options FUSE mount options.
--foreground Do not fork to background.
--skip-components=N Skip the first N components of the path.
Affects the next LISTING argument.
--prefix-dir=DIR Prefix the path with DIR.
Affects the next LISTING argument.
-h --help Show this message and exit.
--help-formats Show supported listing format detail and exit.
--version Show the version and exit.
```
## Example usage
### Running listfs
```shell
listfs /media/backups/index1.jsonl /mnt/listfs
listfs index.jsonl archive.log listing.txt.zst /mnt/listfs
listfs --skip-components=2 list1.log --skip-components=2 list2.log /mnt
listfs --prefix-dir /b1 index1.jsonl --prefix-dir /b2 index2.jsonl /mnt
```
### Inspecting the mounted filesystem
```shell
getfattr -d /mnt/Documents
getfattr -d /mnt/Documents/myfile.txt
ls -la /mnt/Documents
cat /mnt/Documents/myfile.txt
du -hsc /mnt/Documents/*
```
## Supported listing formats
### Basic path listing
One path per line, parsed literally.
```text
/Documents/
/Documents/linux_iso_links.txt
```
### `find -ls` listing
Listing of files as created by `find -ls`
```text
41 4 drwxr-sr-x 1 user 100 1376 Feb 11 2024 ISOs/recovery
20055 2740608 -rwxr-xr-x 1 user user 2806382592 Dec 15 19:20 ISOs/recovery/Fedora-KDE-Live-x86_64-41-1.4.iso
```
Note: if the file was recent enough as of the time of the listing that it does not indicate the year last modified, the year is assumed based on the timestamp of the listing file.
### `tar` listing
Listing of files as created by `tar -c -vv --index-file=index.log`
(`--full-time` optional)
```text
drwxr-xr-x user/user 0 2022-03-16 12:24 code/cpython/Modules/_ctypes/
-rw-r--r-- user/user 240 2022-03-16 12:24 code/cpython/Modules/_ctypes/_ctypes.c
```
```text
drwxr-xr-x root/root 0 2024-03-02 13:48:35.477158221 Documents/
-rw-r--r-- root/root 262144 2024-09-24 02:18:49.122856322 Documents/tux.svg
```
### tabular text
whitespace-separated fields (each field is required):
* timestamp, in seconds with optional decimal
* size (bytes)
* path (assumed to be a directory if ending with "/", otherwise assumed to be a file)
```text
1681475278.2696418010 24334 /media/data/models/LLM Papers.html
1681475278.2529749660 186175 /media/data/models/LLM Papers_files/bootstrap.min.css
```
### jsonl (array)
`jsonl`; one JSON array per line.
The array may have 3 or 4 items, with the blocks field as optional:
* timestamp string, in seconds with optional decimal
* size in bytes
* size in 1KiB blocks (optional)
* path (assumed to be a directory if ending with "/", otherwise assumed to be a file)
```text
["1684828592.0000000000", 14316, "/Nextcloud/Templates/Elegant.odp"]
```
### jsonl (object)
`jsonl`; one JSON object per line (only `"p"` is required):
* `"t"`: timestamp string, in seconds with optional decimal
* `"y"`: type; `"d"` directory, `"f"` file, `"l"` symlink
* `"i"`: original inode
* `"e"`: `1` if empty directory, `0` otherwise
* `"m"`: octal file mode string (e.g. `"0644"`)
* `"s"`: size (bytes)
* `"k"`: size (1KiB blocks)
* `"p"`: path
```text
{"t":"1722859284.2913177150","y":"d","i":5120416,"e":0,"m":"0755","s":4096,"k":4,"p":"/Documents/README.md"}
{"p":"/Documents/README.txt"}
```
## Notes
Note: GNU find and GNU tar produce different output than macOS / BSD find and tar.
* GNU find and tar quote/escape unusual characters in the path, while bsdtar prints the literal path
* GNU find and tar are more advanced, so you probably installed the GNU tools on macOS anyway, so listfs only supports GNU find- and tar-generated output.
## License
[GPL-3.0-or-later](./LICENSE)
## Links
* <https://github.com/d10n/listfs-py/>
* <https://pypi.org/project/listfs/>
Raw data
{
"_id": null,
"home_page": null,
"name": "listfs",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.12",
"maintainer_email": null,
"keywords": "backup, fuse, lto, tape",
"author": null,
"author_email": "d10n <david@bitinvert.com>",
"download_url": "https://files.pythonhosted.org/packages/4e/df/c424c47974b57fd671cd61f1594bb37e8e1e97bad74f8d900cde18dfe375/listfs-0.6.1.tar.gz",
"platform": null,
"description": "# listfs-py\n\n* `listfs` mounts file listings as a filesystem.\n* Useful with `find` and `ncdu`.\n* Inspect file and directory origin with `cat` or `getfattr -d`.\n* Supported listing type summary (more detail below):\n * basic lines of paths\n * `find -ls`\n * `tar -c -vv`\n * tabular text: `mtime bytes path`\n * jsonl: `[\"mtime\", bytes, \"path\"]`\n * jsonl: `[\"mtime\", bytes, blocks_1k, \"path\"]`\n * jsonl: `{\"t\":\"mtime\", \"m\":\"mode\", \"s\":bytes, \"p\":\"path\"}`\n\n## Installation\n\n* `uv tool install listfs`\n\n* If you get an installation error, make sure that the build dependencies are installed:\n* Fedora: `sudo dnf install python python3-devel fuse3 fuse3-devel pkg-config gcc`\n* Debian: `sudo apt install python3 python3-dev fuse3 libfuse3-dev pkg-config gcc`\n\n## Usage\n```text\nlistfs. Mount file listings as a FUSE filesystem.\nUsage:\n listfs [-o MOUNT_OPTIONS] [--foreground]\n ([--skip-components=N] [--prefix-dir=DIR] LISTING)...\n MOUNTPOINT\n listfs -h | --help | --help-formats | --version\n\nArguments:\n LISTING Path to a listing file.\n Must be in a supported format.\n May be compressed with zstd, gzip, bzip2, lz4, or xz.\n See --help-formats for supported formats.\n MOUNTPOINT Directory where the filesystem will be mounted.\n\nOptions:\n -o --options FUSE mount options.\n --foreground Do not fork to background.\n --skip-components=N Skip the first N components of the path.\n Affects the next LISTING argument.\n --prefix-dir=DIR Prefix the path with DIR.\n Affects the next LISTING argument.\n -h --help Show this message and exit.\n --help-formats Show supported listing format detail and exit.\n --version Show the version and exit.\n```\n\n## Example usage\n\n### Running listfs\n```shell\nlistfs /media/backups/index1.jsonl /mnt/listfs\nlistfs index.jsonl archive.log listing.txt.zst /mnt/listfs\nlistfs --skip-components=2 list1.log --skip-components=2 list2.log /mnt\nlistfs --prefix-dir /b1 index1.jsonl --prefix-dir /b2 index2.jsonl /mnt\n```\n\n### Inspecting the mounted filesystem\n```shell\ngetfattr -d /mnt/Documents\ngetfattr -d /mnt/Documents/myfile.txt\nls -la /mnt/Documents\ncat /mnt/Documents/myfile.txt\ndu -hsc /mnt/Documents/*\n```\n\n## Supported listing formats\n\n### Basic path listing\nOne path per line, parsed literally.\n```text\n/Documents/\n/Documents/linux_iso_links.txt\n```\n\n### `find -ls` listing\nListing of files as created by `find -ls`\n```text\n 41 4 drwxr-sr-x 1 user 100 1376 Feb 11 2024 ISOs/recovery\n20055 2740608 -rwxr-xr-x 1 user user 2806382592 Dec 15 19:20 ISOs/recovery/Fedora-KDE-Live-x86_64-41-1.4.iso\n```\nNote: if the file was recent enough as of the time of the listing that it does not indicate the year last modified, the year is assumed based on the timestamp of the listing file.\n\n### `tar` listing\nListing of files as created by `tar -c -vv --index-file=index.log`\n(`--full-time` optional)\n```text\ndrwxr-xr-x user/user 0 2022-03-16 12:24 code/cpython/Modules/_ctypes/\n-rw-r--r-- user/user 240 2022-03-16 12:24 code/cpython/Modules/_ctypes/_ctypes.c\n```\n```text\ndrwxr-xr-x root/root 0 2024-03-02 13:48:35.477158221 Documents/\n-rw-r--r-- root/root 262144 2024-09-24 02:18:49.122856322 Documents/tux.svg\n```\n\n### tabular text\nwhitespace-separated fields (each field is required):\n* timestamp, in seconds with optional decimal\n* size (bytes)\n* path (assumed to be a directory if ending with \"/\", otherwise assumed to be a file)\n```text\n1681475278.2696418010 24334 /media/data/models/LLM Papers.html\n1681475278.2529749660 186175 /media/data/models/LLM Papers_files/bootstrap.min.css\n```\n\n### jsonl (array)\n`jsonl`; one JSON array per line.\nThe array may have 3 or 4 items, with the blocks field as optional:\n* timestamp string, in seconds with optional decimal\n* size in bytes\n* size in 1KiB blocks (optional)\n* path (assumed to be a directory if ending with \"/\", otherwise assumed to be a file)\n```text\n[\"1684828592.0000000000\", 14316, \"/Nextcloud/Templates/Elegant.odp\"]\n```\n\n### jsonl (object)\n`jsonl`; one JSON object per line (only `\"p\"` is required):\n* `\"t\"`: timestamp string, in seconds with optional decimal\n* `\"y\"`: type; `\"d\"` directory, `\"f\"` file, `\"l\"` symlink\n* `\"i\"`: original inode\n* `\"e\"`: `1` if empty directory, `0` otherwise\n* `\"m\"`: octal file mode string (e.g. `\"0644\"`)\n* `\"s\"`: size (bytes)\n* `\"k\"`: size (1KiB blocks)\n* `\"p\"`: path\n```text\n{\"t\":\"1722859284.2913177150\",\"y\":\"d\",\"i\":5120416,\"e\":0,\"m\":\"0755\",\"s\":4096,\"k\":4,\"p\":\"/Documents/README.md\"}\n{\"p\":\"/Documents/README.txt\"}\n```\n\n## Notes\n\nNote: GNU find and GNU tar produce different output than macOS / BSD find and tar.\n* GNU find and tar quote/escape unusual characters in the path, while bsdtar prints the literal path\n* GNU find and tar are more advanced, so you probably installed the GNU tools on macOS anyway, so listfs only supports GNU find- and tar-generated output.\n\n## License\n[GPL-3.0-or-later](./LICENSE)\n\n## Links\n* <https://github.com/d10n/listfs-py/>\n* <https://pypi.org/project/listfs/>\n",
"bugtrack_url": null,
"license": null,
"summary": "Mount file listings as a FUSE filesystem",
"version": "0.6.1",
"project_urls": {
"homepage": "https://github.com/d10n/listfs-py",
"issues": "https://github.com/d10n/listfs-py/issues",
"source": "https://github.com/d10n/listfs-py.git"
},
"split_keywords": [
"backup",
" fuse",
" lto",
" tape"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "6b45ead7e4290fac9110fd6b748cc11509c74b9360bc8464869a3fb11f1a6d86",
"md5": "2bac1f3517be34f784491fb39c157d52",
"sha256": "48b98d49c04d01dcf92c9b6dda20ba53c26958864843819147fd30a7627e5864"
},
"downloads": -1,
"filename": "listfs-0.6.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2bac1f3517be34f784491fb39c157d52",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.12",
"size": 32013,
"upload_time": "2025-02-06T04:03:42",
"upload_time_iso_8601": "2025-02-06T04:03:42.448322Z",
"url": "https://files.pythonhosted.org/packages/6b/45/ead7e4290fac9110fd6b748cc11509c74b9360bc8464869a3fb11f1a6d86/listfs-0.6.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "4edfc424c47974b57fd671cd61f1594bb37e8e1e97bad74f8d900cde18dfe375",
"md5": "83cc3d414820457e1a19ba2f74232a05",
"sha256": "8a23a14cf5a4b9a7ea91f687105b2a20e0aff58d2f0903fd781409dc715883e3"
},
"downloads": -1,
"filename": "listfs-0.6.1.tar.gz",
"has_sig": false,
"md5_digest": "83cc3d414820457e1a19ba2f74232a05",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.12",
"size": 40973,
"upload_time": "2025-02-06T04:03:43",
"upload_time_iso_8601": "2025-02-06T04:03:43.813975Z",
"url": "https://files.pythonhosted.org/packages/4e/df/c424c47974b57fd671cd61f1594bb37e8e1e97bad74f8d900cde18dfe375/listfs-0.6.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-02-06 04:03:43",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "d10n",
"github_project": "listfs-py",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "listfs"
}
