| Name | btrview JSON |
| Version |
0.8.1
JSON |
| download |
| home_page | None |
| Summary | View btrfs snapshot trees |
| upload_time | 2024-05-30 02:08:39 |
| maintainer | None |
| docs_url | None |
| author | Chris Copley |
| requires_python | >=3.11 |
| license | MIT License Copyright (c) 2024 Chris Copley Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. |
| keywords |
btrfs
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
markdown-it-py
mdurl
pygments
rich
six
treelib
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# BTRVIEW
## Overview:
Call btrview with a label to get an overview of the subvolume and snapshot tree layout for that specified btrfs filesystem. Call it with multiple labels and it will list each filesystem specified. Call it with no labels, and it will give an overview of every btrfs filesystem it can find.
```
> sudo btrview --labels HDDs --fold 5
```
Subvolumes that are mounted (in fstab or somehow else) are in bold, those that are grey are subvolumes that aren't currently reachable on the filesystem, and subvolumes in red (not shown here) are not currently on the filesytem. This could be because they're deleted, or maybe its child subvolume was `btrfs received` from another filesystem.
Wondering what the difference between the subvolume and snapshot tree is? [Check out the FAQ](#q-whats-the-difference-between-the-subvolume-tree-and-the-snapshot-tree)!
## Installation:
Btrview relies on the following dependencies:
* [python 3.11 or greater](https://www.python.org/)
* [findmnt](https://man7.org/linux/man-pages/man8/findmnt.8.html) (should be installed by default on most distributions)
* [btrfs-progs](https://github.com/kdave/btrfs-progs/tree/master)
* [python-btrfsutil](https://github.com/kdave/btrfs-progs/tree/master/libbtrfsutil) (might be included with btrfs progs)
* [python-treelib](https://treelib.readthedocs.io/en/latest/)
* [python-rich](https://rich.readthedocs.io/en/stable/introduction.html)
The easiest way to download btrview is to use [pipx](https://pipx.pypa.io/stable/installation/) to download it from the python package index. Use the command `pipx install --system-site-packages btrview`. Using pipx to install btrview will also install treelib and rich and add the `btrview` command to your path allowing you to run the command from anywhere on the system.
If you don't feel like installing via pipx you can download it via `git clone https://github.com/CopOnTheRun/btrview` then `cd btrview`. From within the btrview directory you can run the script with `python -m btrview`. Note that if you clone the repository you'll need to make sure you have all the dependencies installed already.
### Installation Troubleshooting
Q: How come when I use the sudo command with btrview I get `sudo: btrview: command not found`, but when I run it without sudo the command is recognized?
A: You are likely using a linux distribution which hard codes the paths sudo can use to find executables. There are two options here, you can either comment out the line that contains "secure_path" in `/etc/sudoers` or you can add the path you're using to that variable. The former option will change it so that any executable in the user's path can be executed, the latter option will merely add the user's path to list of allowed paths.
## Some Qs and As:
### Q: What is btrfs?
In short, it's a copy on write (COW) filesystem. If you're not already using btrfs, then check out the [documentation](https://btrfs.readthedocs.io/en/latest/) to see if it's something you'd be interested in.
### Q: What does btrview do?
It produces a view of the btrfs filesystems, mounts, as well as the subvolume tree or snapshot tree on your system.
### Q: What's the difference between the subvolume tree and the snapshot tree?
The subvolume tree is a tree of which subvolumes are within other subvolumes, parents being denoted by "Parent ID". The subvolume tree can be manipulated by moving subvolumes in or out of other subvolumes. The snapshot tree shows the relations between snapshots, ie snapshots taken of snapshots, etc.
If that's a little obscure here's a visual example of the difference.
If you run these commands:
```
btrfs subvolume create subvol
btrfs subvolume create subvol/nested_subvol
btrfs subvolume snapshot subvol subvol/subvol-snap
btrfs subvolume snapshot subvol subvol/subvol-snap2
btrfs subvolume snapshot subvol/nested_subvol subvol/nested_subvol-snap
```
The subvolume tree would look like:
```
subvol
├── nested_subvol
├── subvol-snap
├── subvol-snap2
└── nested_subvol-snap
```
The snapshot tree would look like:
```
subvol
├── subvol-snap
└── subvol-snap2
nested_subvol
└── nested_subvol-snap
```
### Q: What's the point of this program?
The main thing btrview accomplishes is providing an organized overview of a (or multiple) btrfs filesystem(s). Due to the fact btrfs relies only on loose conventions to determine where snapshots are stored, and how subvolumes are organized, it can be difficult to gain an understanding of how things are laid out. With btrview it's easy to know which subvolumes have snapshots, how many, and where they're stored. Even if your snapshots and subvolumes are scattered around a messy filesystem they'll all still show up as a nice little tree.
### Q: What's not the point of this program?
This is in no way shape or form a backup solution. Use something like [btrbk](https://github.com/digint/btrbk) for that.
This is also not a snapshot diff viewer. If that sounds like something you're interested in check out [httm](https://github.com/kimono-koans/httm).
To put it plainly, btrview merely shows the state of things as they are, it doesn't actually "do" anything.
### Q: How is the "btr" part of btrview pronounced?
The same as the "btr" part of btrfs.
Raw data
{
"_id": null,
"home_page": null,
"name": "btrview",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "btrfs",
"author": "Chris Copley",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/3a/e2/24d5f5cd69dc813739c098bd3c814de7d194e1608ea4d16a0683a2008d17/btrview-0.8.1.tar.gz",
"platform": null,
"description": "# BTRVIEW\n\n## Overview:\n\nCall btrview with a label to get an overview of the subvolume and snapshot tree layout for that specified btrfs filesystem. Call it with multiple labels and it will list each filesystem specified. Call it with no labels, and it will give an overview of every btrfs filesystem it can find.\n\n```\n> sudo btrview --labels HDDs --fold 5\n```\n\n\nSubvolumes that are mounted (in fstab or somehow else) are in bold, those that are grey are subvolumes that aren't currently reachable on the filesystem, and subvolumes in red (not shown here) are not currently on the filesytem. This could be because they're deleted, or maybe its child subvolume was `btrfs received` from another filesystem.\n\nWondering what the difference between the subvolume and snapshot tree is? [Check out the FAQ](#q-whats-the-difference-between-the-subvolume-tree-and-the-snapshot-tree)!\n\n## Installation:\n\nBtrview relies on the following dependencies:\n* [python 3.11 or greater](https://www.python.org/)\n* [findmnt](https://man7.org/linux/man-pages/man8/findmnt.8.html) (should be installed by default on most distributions)\n* [btrfs-progs](https://github.com/kdave/btrfs-progs/tree/master)\n* [python-btrfsutil](https://github.com/kdave/btrfs-progs/tree/master/libbtrfsutil) (might be included with btrfs progs)\n* [python-treelib](https://treelib.readthedocs.io/en/latest/)\n* [python-rich](https://rich.readthedocs.io/en/stable/introduction.html)\n\nThe easiest way to download btrview is to use [pipx](https://pipx.pypa.io/stable/installation/) to download it from the python package index. Use the command `pipx install --system-site-packages btrview`. Using pipx to install btrview will also install treelib and rich and add the `btrview` command to your path allowing you to run the command from anywhere on the system.\n\nIf you don't feel like installing via pipx you can download it via `git clone https://github.com/CopOnTheRun/btrview` then `cd btrview`. From within the btrview directory you can run the script with `python -m btrview`. Note that if you clone the repository you'll need to make sure you have all the dependencies installed already.\n\n### Installation Troubleshooting\n\nQ: How come when I use the sudo command with btrview I get `sudo: btrview: command not found`, but when I run it without sudo the command is recognized?\n\nA: You are likely using a linux distribution which hard codes the paths sudo can use to find executables. There are two options here, you can either comment out the line that contains \"secure_path\" in `/etc/sudoers` or you can add the path you're using to that variable. The former option will change it so that any executable in the user's path can be executed, the latter option will merely add the user's path to list of allowed paths.\n\n## Some Qs and As:\n\n### Q: What is btrfs?\n\nIn short, it's a copy on write (COW) filesystem. If you're not already using btrfs, then check out the [documentation](https://btrfs.readthedocs.io/en/latest/) to see if it's something you'd be interested in.\n\n### Q: What does btrview do?\n\nIt produces a view of the btrfs filesystems, mounts, as well as the subvolume tree or snapshot tree on your system.\n\n### Q: What's the difference between the subvolume tree and the snapshot tree?\n\nThe subvolume tree is a tree of which subvolumes are within other subvolumes, parents being denoted by \"Parent ID\". The subvolume tree can be manipulated by moving subvolumes in or out of other subvolumes. The snapshot tree shows the relations between snapshots, ie snapshots taken of snapshots, etc.\n\nIf that's a little obscure here's a visual example of the difference.\n\nIf you run these commands:\n\n```\nbtrfs subvolume create subvol\nbtrfs subvolume create subvol/nested_subvol\nbtrfs subvolume snapshot subvol subvol/subvol-snap\nbtrfs subvolume snapshot subvol subvol/subvol-snap2\nbtrfs subvolume snapshot subvol/nested_subvol subvol/nested_subvol-snap\n```\n\nThe subvolume tree would look like:\n\n```\nsubvol\n\u251c\u2500\u2500 nested_subvol\n\u251c\u2500\u2500 subvol-snap\n\u251c\u2500\u2500 subvol-snap2\n\u2514\u2500\u2500 nested_subvol-snap\n```\n\nThe snapshot tree would look like:\n\n```\nsubvol\n\u251c\u2500\u2500 subvol-snap\n\u2514\u2500\u2500 subvol-snap2\nnested_subvol\n\u2514\u2500\u2500 nested_subvol-snap\n```\n\n### Q: What's the point of this program?\n\nThe main thing btrview accomplishes is providing an organized overview of a (or multiple) btrfs filesystem(s). Due to the fact btrfs relies only on loose conventions to determine where snapshots are stored, and how subvolumes are organized, it can be difficult to gain an understanding of how things are laid out. With btrview it's easy to know which subvolumes have snapshots, how many, and where they're stored. Even if your snapshots and subvolumes are scattered around a messy filesystem they'll all still show up as a nice little tree.\n\n### Q: What's not the point of this program?\n\nThis is in no way shape or form a backup solution. Use something like [btrbk](https://github.com/digint/btrbk) for that. \n\nThis is also not a snapshot diff viewer. If that sounds like something you're interested in check out [httm](https://github.com/kimono-koans/httm).\n\nTo put it plainly, btrview merely shows the state of things as they are, it doesn't actually \"do\" anything.\n\n### Q: How is the \"btr\" part of btrview pronounced?\n\nThe same as the \"btr\" part of btrfs.\n\n",
"bugtrack_url": null,
"license": "MIT License Copyright (c) 2024 Chris Copley Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ",
"summary": "View btrfs snapshot trees",
"version": "0.8.1",
"project_urls": {
"Issues": "https://github.com/CopOnTheRun/btrview/issues",
"Repository": "https://github.com/CopOnTheRun/btrview"
},
"split_keywords": [
"btrfs"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "e10f67f4c3c39cf06856849961718fdbca7a6b079f1faadfaac7e3e96b804b2b",
"md5": "27e3d7acc179750b7579ee19ed419b39",
"sha256": "4bd02bf2e1621de7d31d183ea3fbf0b5e332297ca6178b07889f86a5c5d82d8c"
},
"downloads": -1,
"filename": "btrview-0.8.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "27e3d7acc179750b7579ee19ed419b39",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 16173,
"upload_time": "2024-05-30T02:08:38",
"upload_time_iso_8601": "2024-05-30T02:08:38.181205Z",
"url": "https://files.pythonhosted.org/packages/e1/0f/67f4c3c39cf06856849961718fdbca7a6b079f1faadfaac7e3e96b804b2b/btrview-0.8.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "3ae224d5f5cd69dc813739c098bd3c814de7d194e1608ea4d16a0683a2008d17",
"md5": "7380ae542c626408c59731606d9c10c7",
"sha256": "24cc65a3b5f854b9941d97bfd08f3ffbd5b296dc67ecf782d6a4d3d1676c61e1"
},
"downloads": -1,
"filename": "btrview-0.8.1.tar.gz",
"has_sig": false,
"md5_digest": "7380ae542c626408c59731606d9c10c7",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 15880,
"upload_time": "2024-05-30T02:08:39",
"upload_time_iso_8601": "2024-05-30T02:08:39.853051Z",
"url": "https://files.pythonhosted.org/packages/3a/e2/24d5f5cd69dc813739c098bd3c814de7d194e1608ea4d16a0683a2008d17/btrview-0.8.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-05-30 02:08:39",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "CopOnTheRun",
"github_project": "btrview",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "markdown-it-py",
"specs": [
[
"==",
"3.0.0"
]
]
},
{
"name": "mdurl",
"specs": [
[
"==",
"0.1.2"
]
]
},
{
"name": "pygments",
"specs": [
[
"==",
"2.18.0"
]
]
},
{
"name": "rich",
"specs": [
[
"==",
"13.7.1"
]
]
},
{
"name": "six",
"specs": [
[
"==",
"1.16.0"
]
]
},
{
"name": "treelib",
"specs": [
[
"==",
"1.7.0"
]
]
}
],
"lcname": "btrview"
}
