2023-02-21 17:50:00 +00:00
Btrfs-progs
2015-10-27 15:30:22 +00:00
===========
2023-07-13 14:21:36 +00:00
[](https://github.com/kdave/btrfs-progs/actions/workflows/devel.yml)
[](https://github.com/kdave/btrfs-progs/actions/workflows/coverage.yml)
2023-07-13 14:36:26 +00:00
[](https://codecov.io/gh/kdave/btrfs-progs)
2023-07-13 14:21:36 +00:00
[](https://github.com/kdave/btrfs-progs/actions/workflows/artifacts-static-build.yml)
[](https://github.com/kdave/btrfs-progs/actions/workflows/ci-build-test.yml)
2023-07-11 15:11:19 +00:00
2015-10-27 15:30:22 +00:00
Userspace utilities to manage btrfs filesystems.
License: GPLv2.
Btrfs is a copy on write (COW) filesystem for Linux aimed at implementing
advanced features while focusing on fault tolerance, repair and easy
administration.
2022-01-11 22:40:48 +00:00
This repository hosts following utilities and also documentation:
2015-10-27 15:30:22 +00:00
2022-08-07 14:03:14 +00:00
* **btrfs** — the main administration tool ([manual page](https://btrfs.readthedocs.io/en/latest/btrfs.html))
* **mkfs.btrfs** — utility to create the filesystem ([manual page](https://btrfs.readthedocs.io/en/latest/mkfs.btrfs.html))
2023-02-21 18:05:52 +00:00
* all-in-one binary in the busybox style with mkfs.btrfs, btrfs-image and other tools built-in ([standalone tools](https://btrfs.readthedocs.io/en/latest/btrfs.html#standalone-tools))
2021-07-08 12:53:16 +00:00
* **libbtrfsutil** (LGPL v2.1) — C and python 3 bindings, see [libbtrfsutil/README.md ](libbtrfsutil/README.md ) for more
2023-02-21 18:05:52 +00:00
* manual pages and documentation source published at [btrfs.readthedocs.io ](https://btrfs.readthedocs.io ) (RTD)
2018-11-26 15:52:05 +00:00
2023-04-13 14:51:00 +00:00
See [INSTALL ](INSTALL ) for build instructions, [tests/README.md ](tests/README.md ) for
testing information and [ci/README.md ](ci/README.md ) for CI information.
2015-10-27 15:30:22 +00:00
Release cycle
-------------
The major version releases are time-based and follow the cycle of the linux
kernel releases. The cycle usually takes 2 months. A minor version releases may
2016-11-10 17:31:53 +00:00
happen in the meantime if there are bug fixes or minor useful improvements
queued.
The release tags are signed with a GPG key ID `F2B4 1200 C54E FB30 380C 1756 C565 D5F9 D76D 583B` ,
release tarballs are hosted at [kernel.org ](https://www.kernel.org/pub/linux/kernel/people/kdave/btrfs-progs/ ).
2023-02-21 18:05:52 +00:00
See file [CHANGES ](CHANGES ) or [changelogs on RTD ](https://btrfs.readthedocs.io/en/latest/CHANGES.html ).
2016-11-10 17:31:53 +00:00
2023-12-01 00:22:06 +00:00
Releases with changelog are also published at [Github release page ](https://github.com/kdave/btrfs-progs/releases ).
### Static binaries
For each release there are static binaries of `btrfs` and `btrfs.box` provided.
These can be used in rescue environments and are built for `x86_64`
architecture (with maximum backward compatibility), inside the [Github Actions
workflow](https://github.com/kdave/btrfs-progs/actions/workflows/artifacts-static-build.yml).
The `btrfs.box` is an all-in-one tool in the [busybox ](https://www.busybox.net )
style, the functionality is determined by the binary names (either symlink,
hradlink or a file copy).
2023-12-08 14:21:00 +00:00
### Feature compatibility
The *btrfs-progs* of version *X.Y* declare support of kernel features of the same
version. New progs on old kernel are expected to work, limited only by features
provided by the kernel.
### Build compatibility
Build is supported on the [GNU C library ](https://www.gnu.org/software/libc/ )
as the primary target, and on the [musl libc ](https://musl.libc.org/ ).
The supported compilers are [gcc ](https://gcc.gnu.org/ ) (minimal version 4.8)
and [clang ](https://clang.llvm.org/ ) (minimal version 3.4).
Build tests are done on [several distributions ](https://github.com/kdave/btrfs-progs/blob/master/.github/workflows/ci-build-test.yml ), see
[Github actions workflow ](https://github.com/kdave/btrfs-progs/actions/workflows/ci-build-test.yml ).
2016-11-10 17:31:53 +00:00
Reporting bugs
--------------
There are several ways, each has its own specifics and audience that can give
2017-04-03 17:47:10 +00:00
feedback or work on a fix. The following list is sorted in the order of
preference:
2016-11-10 17:31:53 +00:00
2023-08-28 12:53:07 +00:00
* [Github issue tracker ](https://github.com/kdave/btrfs-progs/issues )
2016-11-10 17:31:53 +00:00
* to the mailing list *linux-btrfs@vger.kernel.org* -- (not required to
subscribe), beware that the mail might get overlooked in other traffic
2022-01-11 22:40:48 +00:00
* IRC (irc.libera.chat #btrfs ) -- good for discussions eg. if a bug is already
2016-11-10 17:31:53 +00:00
known, but reports could miss developers' attention
2023-02-21 18:05:52 +00:00
* please don't use https://bugzilla.kernel.org for btrfs-progs bugs
2016-11-10 17:31:53 +00:00
2015-10-27 15:30:22 +00:00
Development
-----------
2023-02-21 18:05:52 +00:00
The development takes place in the mailing list (*linux-btrfs@vger.kernel.org*)
2023-08-28 12:53:07 +00:00
or at Github (issues, pull requests). Changes should be split to logical parts
2023-02-21 18:05:52 +00:00
if possible, documentation may be included in the same patch as to code or
separately.
2016-11-10 17:31:53 +00:00
The development model of btrfs-progs shares a lot with the kernel model. The
2023-08-28 12:53:07 +00:00
* **one logical change per patch**: e.g. not mixing bugfixes, cleanups, features
2016-11-10 17:31:53 +00:00
etc., sometimes it's not clear and will be usually pointed out during reviews
2023-08-28 12:53:07 +00:00
* proper **subject line** : e.g. prefix with _btrfs-progs: subpart, ..._ ,
2016-11-10 17:31:53 +00:00
descriptive yet not too long, see `git log --oneline` for some inspiration
* proper **changelog** : the changelogs are often missing or lacking explanation _why_
the change was made, or _how_ is something broken, _what_ are user-visible
effects of the bug or the fix, _how_ does an improvement help or the intended
_usecase_
2023-02-21 18:05:52 +00:00
* the **Signed-off-by** line is not mandatory for less significant changes
(typos, documentation) but is desired as this documents who authored the
change, you can read more about the
2017-09-11 15:17:26 +00:00
[The Developer's Certificate of Origin (chapter 11) ](https://www.kernel.org/doc/html/latest/process/submitting-patches.html#sign-your-work-the-developer-s-certificate-of-origin )
* if you are not used to the signed-off style, your contributions won't be
rejected just because of it's missing, the _Author:_ tag will be added as a
substitute in order to allow contributions without much bothering with
formalities
2016-11-10 17:31:53 +00:00
2023-08-28 12:53:07 +00:00
### Pull requests
The pull requests on Github may be used for code or documentation
contributions. There are basic build checks enabled in the Github actions CI
2023-12-01 00:07:53 +00:00
for pull requests. The status can be checked at the
[workflow page ](https://github.com/kdave/btrfs-progs/actions/workflows/pull-request.yml ).
2023-08-28 12:53:07 +00:00
* open a PR against branches *devel* or *master*
* push update to the same branch if you need to
* close the PR in case it's wrong, a mistake or needs rework
* if you're sure the changes don't need a CI build verification, please add `[skip ci]` to the changelog
2020-07-31 01:03:34 +00:00
Source code coding style and preferences follow the
[kernel coding style ](https://www.kernel.org/doc/html/latest/process/coding-style.html ).
2020-12-25 19:15:11 +00:00
You can find the editor settings in `.editorconfig` and use the
2020-07-31 01:03:34 +00:00
[EditorConfig ](https://editorconfig.org/ ) plugin to let your editor use that,
or update your editor settings manually.
2021-03-02 21:22:07 +00:00
Testing
-------
2023-12-01 00:07:53 +00:00
The documentation for writing and running tests can be found in
[tests/ ](tests/README.md ) and continuous integration/container images in
[ci/ ](ci/README.md ).
Development branches are tested by Github
[Action workflows ](https://github.com/kdave/btrfs-progs/actions ).
Code coverage provided by [codecov.io ](https://codecov.io ) can be found
[here ](https://codecov.io/gh/kdave/btrfs-progs ).
2021-03-02 21:22:07 +00:00
2016-12-08 16:36:04 +00:00
Documentation updates
---------------------
Documentation fixes or updates do not need much explanation so sticking to the
2018-11-26 16:47:22 +00:00
code rules in the previous section is not necessary. GitHub pull requests are
2016-12-08 16:36:04 +00:00
OK, patches could be sent to me directly and not required to be also in the
2023-08-28 12:53:07 +00:00
mailing list. Pointing out typos via IRC also works, although might get
2016-12-08 16:36:04 +00:00
accidentally lost in the noise.
2015-10-27 15:30:22 +00:00
2023-02-21 18:05:52 +00:00
Documentation sources are written in
[RST ](https://en.wikipedia.org/wiki/ReStructuredText ) and built by sphinx.
2022-01-11 22:40:48 +00:00
2020-03-31 17:09:28 +00:00
Third-party sources
-------------------
Build dependencies are listed in [INSTALL ](INSTALL ). Implementation of checksum/hash
functions is provided by copies of the respective sources to avoid adding
2023-02-21 18:05:52 +00:00
dependencies that would make deployments in rescue or limited environments
harder. The implementations are portable and there are optimized versions for
2023-12-01 00:07:53 +00:00
some architectures. Optionally it's possible to use
[libgcrypt ](https://www.gnupg.org/software/libgcrypt/index.html ),
[libsodium ](https://doc.libsodium.org ),
[libkcapi ](https://www.chronox.de/libkcapi.html ),
[Botan ](https://botan.randombit.net ) or
[OpenSSL ](https://www.openssl.org ) implementations.
The builtin implemtations uses the following sources:
[CRC32C ](https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git ),
[XXHASH ](https://github.com/Cyan4973/xxHash ),
[SHA256 ](https://tools.ietf.org/html/rfc4634 ),
[BLAKE2 ](https://github.com/BLAKE2/BLAKE2 ).
2020-03-31 17:09:28 +00:00
2022-01-11 22:40:48 +00:00
Some other code is borrowed from kernel, eg. the raid5 tables or data structure
2023-02-21 18:05:52 +00:00
implementation (list, rb-tree).
2022-01-11 22:40:48 +00:00
2015-10-27 15:30:22 +00:00
References
----------
2022-10-06 15:52:25 +00:00
* [Documentation ](https://btrfs.readthedocs.io )
2023-02-21 18:10:46 +00:00
* [Manual pages ](https://btrfs.readthedocs.io/en/latest/man-index.html )
* [Changes -- brfs-progs ](https://btrfs.readthedocs.io/en/latest/CHANGES.html )
* [Features by kernel version ](https://btrfs.readthedocs.io/en/latest/Feature-by-version.html )
