mirror/restic
1
0
Fork 0
mirror of https://github.com/restic/restic.git synced 2024-12-21 23:33:03 +00:00
Code Issues Releases Wiki Activity

add feature flag documentation

Browse source
This commit is contained in:
Michael Eischer 2024-02-17 21:41:07 +01:00
parent 70839155f2
commit fe68d2cafb
3 changed files with 45 additions and 3 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

9
changelog/unreleased/issue-4601 Normal file
View file

@ -0,0 +1,9 @@
Enhancement: Add support for feature flags
Restic now supports feature flags that can be used to enable and disable
experimental features. The flags can be set using the environment variable
`RESTIC_FEATURES`. To get a list of currently supported feature flags,
run the `features` command.
https://github.com/restic/restic/issues/4601
https://github.com/restic/restic/pull/4666

11
cmd/restic/cmd_features.go
View file

@ -10,14 +10,21 @@ import (
"github.com/spf13/cobra"
)
// FIXME explain semantics
var featuresCmd = &cobra.Command{
Use: "features",
Short: "Print list of feature flags",
Long: `
The "features" command prints a list of supported feature flags.
To pass feature flags to restic, set the RESTIC_FEATURES environment variable
to "featureA=true,featureB=false". Specifying an unknown feature flag is an error.
A feature can either be in alpha, beta, stable or deprecated state.
An _alpha_ feature is disabled by default and may change in arbitrary ways between restic versions or be removed.
A _beta_ feature is enabled by default, but still can change in minor ways or be removed.
A _stable_ feature is always enabled and cannot be disabled. The flag will be removed in a future restic version.
A _deprecated_ feature is always disabled and cannot be enabled. The flag will be removed in a future restic version.
EXIT STATUS
===========

28
doc/047_tuning_backup_parameters.rst
View file

@ -26,7 +26,8 @@ When you start a backup, restic will concurrently count the number of files and
their total size, which is used to estimate how long it will take. This will
cause some extra I/O, which can slow down backups of network file systems or
FUSE mounts. To avoid this overhead at the cost of not seeing a progress
estimate, use the ``--no-scan`` option which disables this file scanning.
estimate, use the ``--no-scan`` option of the ``backup`` command which disables
this file scanning.
Backend Connections
===================
@ -111,3 +112,28 @@ to disk. An operating system usually caches file write operations in memory and
them to disk after a short delay. As larger pack files take longer to upload, this
increases the chance of these files being written to disk. This can increase disk wear
for SSDs.
Feature Flags
=============
Feature flags allow disabling or enabling certain experimental restic features. The flags
can be specified via the ``RESTIC_FEATURES`` environment variable. The variable expects a
comma-separated list of ``key[=value],key2[=value2]`` pairs. The key is the name of a feature
flag. The value is optional and can contain either the value ``true`` (default if omitted)
or ``false``. The list of currently available feautre flags is shown by the ``features``
command.
Restic will return an error if an invalid feature flag is specified. No longer relevant
feature flags may be removed in a future restic release. Thus, make sure to no longer
specify these flags.
A feature can either be in alpha, beta, stable or deprecated state.
- An _alpha_ feature is disabled by default and may change in arbitrary ways between restic
versions or be removed.
- A _beta_ feature is enabled by default, but still can change in minor ways or be removed.
- A _stable_ feature is always enabled and cannot be disabled. This allows for a transition
period after which the flag will be removed in a future restic version.
- A _deprecated_ feature is always disabled and cannot be enabled. The flag will be removed
in a future restic version.