mirror of
https://github.com/borgbackup/borg.git
synced 2024-12-24 08:45:13 +00:00
Merge pull request #32 from jdchristensen/docs2
Docs2: update lots of documentation
This commit is contained in:
Jonas Borgström
commit
b5037cf460
8 changed files with 76 additions and 28 deletions
17
README.rst
17
README.rst
|
|
@ -1,13 +1,13 @@
|
|||
What is Attic?
|
||||
--------------
|
||||
Attic is a deduplicating backup program. The main goal of attic is to provide
|
||||
Attic is a deduplicating backup program. The main goal of Attic is to provide
|
||||
an efficient and secure way to backup data. The data deduplication
|
||||
technique used makes Attic suitable for daily backups since only actual changes
|
||||
technique used makes Attic suitable for daily backups since only changes
|
||||
are stored.
|
||||
|
||||
Easy to use
|
||||
~~~~~~~~~~~
|
||||
Initialze backup repository and create a backup archive::
|
||||
Initialize backup repository and create a backup archive::
|
||||
|
||||
$ attic init /usbdrive/my-backup.attic
|
||||
$ attic create -v /usbdrive/my-backup.attic::documents ~/Documents
|
||||
|
|
@ -25,8 +25,8 @@ Optional data encryption
|
|||
and authenticity is verified using HMAC-SHA256.
|
||||
|
||||
Off-site backups
|
||||
attic can store data on any remote host accessible over SSH as long as
|
||||
attic is installed.
|
||||
Attic can store data on any remote host accessible over SSH. This is
|
||||
most efficient if Attic is also installed on the remote host.
|
||||
|
||||
Backups mountable as filesystems
|
||||
Backup archives are mountable as userspace filesystems for easy backup
|
||||
|
|
@ -34,8 +34,9 @@ Backups mountable as filesystems
|
|||
|
||||
What do I need?
|
||||
---------------
|
||||
Attic requires Python 3.2 or above to work. Besides Python attic also requires
|
||||
Attic requires Python 3.2 or above to work. Besides Python, Attic also requires
|
||||
msgpack-python and sufficiently recent OpenSSL (>= 1.0.0).
|
||||
In order to mount archives as filesystems, llfuse is required.
|
||||
|
||||
How do I install it?
|
||||
--------------------
|
||||
|
|
@ -45,8 +46,8 @@ How do I install it?
|
|||
|
||||
Where are the docs?
|
||||
-------------------
|
||||
Go to https://pythonhosted.org/Attic/ for a prebuilt version of the docs. You
|
||||
can also build them yourself form the docs folder.
|
||||
Go to https://pythonhosted.org/Attic/ for a prebuilt version of the documentation.
|
||||
You can also build it yourself from the docs folder.
|
||||
|
||||
Where are the tests?
|
||||
--------------------
|
||||
|
|
|
|||
|
|
@ -450,8 +450,22 @@ def run(self, args=None):
|
|||
type=location_validator(archive=True),
|
||||
help='archive to display information about')
|
||||
|
||||
prune_epilog = '''The prune command prunes a repository by deleting archives
|
||||
not matching any of the specified retention options. This command is normally
|
||||
used by automated backup scripts wanting to keep a certain number of historic
|
||||
backups. As an example, "-d 7" means to keep the latest backup on each day
|
||||
for 7 days. Days without backups do not count towards the total. The rules
|
||||
are applied from hourly to yearly, and backups selected by previous rules do
|
||||
not count towards those of later rules. Dates and times are interpreted in
|
||||
the local timezone, and weeks go from Monday to Sunday. Specifying a
|
||||
negative number of archives to keep means that there is no limit. If a
|
||||
prefix is set with -p, then only archives that start with the prefix are
|
||||
considered for deletion and only those archives count towards the totals
|
||||
specified by the rules.'''
|
||||
|
||||
subparser = subparsers.add_parser('prune', parents=[common_parser],
|
||||
description=self.do_prune.__doc__)
|
||||
description=self.do_prune.__doc__,
|
||||
epilog=prune_epilog)
|
||||
subparser.set_defaults(func=self.do_prune)
|
||||
subparser.add_argument('-H', '--hourly', dest='hourly', type=int, default=0,
|
||||
help='number of hourly archives to keep')
|
||||
|
|
|
|||
|
|
@ -13,6 +13,7 @@
|
|||
.. _OpenSSL: https://www.openssl.org/
|
||||
.. _Python: http://www.python.org/
|
||||
.. _`msgpack-python`: https://pypi.python.org/pypi/msgpack-python/
|
||||
.. _llfuse: https://pypi.python.org/pypi/llfuse/
|
||||
.. _homebrew: http://mxcl.github.io/homebrew/
|
||||
.. _issue tracker: https://github.com/jborg/attic/issues
|
||||
.. _userspace filesystems: https://en.wikipedia.org/wiki/Filesystem_in_Userspace
|
||||
|
|
|
|||
|
|
@ -5,7 +5,7 @@ Welcome to Attic
|
|||
|project_name| is a deduplicating backup program written in Python.
|
||||
The main goal of |project_name| is to provide an efficient and secure way
|
||||
to backup data. The data deduplication technique used makes |project_name|
|
||||
suitable for daily backups since only actual changes are stored.
|
||||
suitable for daily backups since only the changes are stored.
|
||||
|
||||
|
||||
Easy to use
|
||||
|
|
@ -44,17 +44,17 @@ User's Guide
|
|||
Getting help
|
||||
============
|
||||
|
||||
If you've found a bug or have a concrete feature request you can add your bug
|
||||
report or feature request directly to the project `issue tracker`_. For more
|
||||
general questions or discussions a post to the mailing list is preferred.
|
||||
If you've found a bug or have a concrete feature request, you can add your bug
|
||||
report or feature request directly to the project's `issue tracker`_. For more
|
||||
general questions or discussions, a post to the mailing list is preferred.
|
||||
|
||||
Mailing list
|
||||
------------
|
||||
|
||||
There is a mailing list for Attic on librelist_ you can use for feature
|
||||
There is a mailing list for Attic on librelist_ that you can use for feature
|
||||
requests and general discussions about Attic. A mailing list archive is
|
||||
available `here <http://librelist.com/browser/attic/>`_.
|
||||
|
||||
To subscribe to the list send an email to attic@librelist.com and reply
|
||||
to the confirmation mail. Likevise To unsubscribe send an email to
|
||||
To subscribe to the list, send an email to attic@librelist.com and reply
|
||||
to the confirmation mail. Likewise, to unsubscribe, send an email to
|
||||
attic-unsubscribe@librelist.com and reply to the confirmation mail.
|
||||
|
|
|
|||
|
|
@ -5,7 +5,7 @@ Installation
|
|||
============
|
||||
|
||||
|project_name| requires Python_ 3.2 or above to work. Even though Python 3 is
|
||||
not the default Python version on most Linux distributions it is usually
|
||||
not the default Python version on most Linux distributions, it is usually
|
||||
available as an optional install.
|
||||
|
||||
Other dependencies:
|
||||
|
|
@ -16,6 +16,9 @@ Other dependencies:
|
|||
The OpenSSL version bundled with Mac OS X and FreeBSD is most likey too old.
|
||||
Newer versions are available from homebrew_ on OS X and from FreeBSD ports.
|
||||
|
||||
The llfuse_ python package is also required if you wish to mount an
|
||||
archive as a FUSE filesystem.
|
||||
|
||||
Installing from PyPI using pip
|
||||
------------------------------
|
||||
::
|
||||
|
|
@ -39,5 +42,11 @@ Installing from git
|
|||
$ cd attic
|
||||
$ python setup.py install
|
||||
|
||||
Please not that when installing from git Cython_ is required to generate some files that
|
||||
Please note that when installing from git, Cython_ is required to generate some files that
|
||||
are normally bundled with the release tarball.
|
||||
|
||||
Packages
|
||||
--------
|
||||
|
||||
|project_name| is also part of the Debian_, Ubuntu_ and `Arch Linux`_
|
||||
distributions of GNU/Linux.
|
||||
|
|
|
|||
|
|
@ -113,13 +113,20 @@ Key file based encryption
|
|||
Remote repositories
|
||||
-------------------
|
||||
|
||||
|project_name| can initialize and access repositories on remote hosts as the
|
||||
host is accessible using SSH and |project_name| is installed.
|
||||
|
||||
The following syntax is used to address remote repositories::
|
||||
|project_name| can initialize and access repositories on remote hosts if the
|
||||
host is accessible using SSH. This is fastest and easiest when |project_name|
|
||||
is installed on the remote host, in which case the following syntax is used::
|
||||
|
||||
$ attic init user@hostname:repository.attic
|
||||
|
||||
or::
|
||||
|
||||
$ attic init ssh://user@hostname:port/repository.attic
|
||||
|
||||
If it is not possible to install |project_name| on the remote host,
|
||||
it is still possible to use the remote host to store a repository by
|
||||
mounting the remote filesystem, for example, using sshfs::
|
||||
|
||||
$ sshfs user@hostname:/path/to/folder /tmp/mymountpoint
|
||||
$ attic init /tmp/mymountpoint/repository.attic
|
||||
$ fusermount -u /tmp/mymountpoint
|
||||
|
|
|
|||
|
|
@ -40,21 +40,21 @@ Examples
|
|||
|
||||
This command creates a backup archive containing all files found while
|
||||
recursively traversing all paths specified. The archive will consume almost
|
||||
no disk space for files or parts of files that has already been archived by
|
||||
no disk space for files or parts of files that have already been stored in
|
||||
other archives.
|
||||
|
||||
Examples
|
||||
~~~~~~~~
|
||||
::
|
||||
|
||||
# Backups ~/Documents into an archive named "my-documents"
|
||||
# Backup ~/Documents into an archive named "my-documents"
|
||||
$ attic create /data/myrepo.attic::my-documents ~/Documents
|
||||
|
||||
# Backup ~/Documents and ~/src but exclude pyc files
|
||||
$ attic create /data/myrepo.attic::my-files \
|
||||
~/Documents \
|
||||
~/src \
|
||||
--exclude *.pyc
|
||||
--exclude '*.pyc'
|
||||
|
||||
# Backup the root filesystem into an archive named "root-YYYY-MM-DD"
|
||||
NAME="root-`date +%Y-%m-%d`"
|
||||
|
|
@ -82,7 +82,7 @@ Examples
|
|||
$ attic extract /data/myrepo::my-files home/USERNAME/src
|
||||
|
||||
# Extract the "src" directory but exclude object files
|
||||
$ attic extract /data/myrepo::my-files home/USERNAME/src --exclude *.o
|
||||
$ attic extract /data/myrepo::my-files home/USERNAME/src --exclude '*.o'
|
||||
|
||||
|
||||
.. include:: usage/verify.rst.inc
|
||||
|
|
@ -126,7 +126,7 @@ Examples
|
|||
.. include:: usage/prune.rst.inc
|
||||
|
||||
The ``prune`` command prunes a repository by deleting archives not matching
|
||||
any of the specified retention options specified. This command is normally
|
||||
any of the specified retention options. This command is normally
|
||||
used by automated backup scripts wanting to keep a certain number of historic
|
||||
backups.
|
||||
|
||||
|
|
@ -134,12 +134,16 @@ Examples
|
|||
~~~~~~~~
|
||||
::
|
||||
|
||||
# Keep 7 end of day and 4 end of week archives
|
||||
# Keep 7 end of day and 4 additional end of week archives
|
||||
$ attic prune /data/myrepo --daily=7 --weekly=4
|
||||
|
||||
# Same as above but only apply to archive names starting with "foo"
|
||||
$ attic prune /data/myrepo --daily=7 --weekly=4 --prefix=foo
|
||||
|
||||
# Keep 7 end of day, 4 additional end of week archives, and an
|
||||
# end of month archive for every month:
|
||||
$ attic prune /data/myrepo --daily=7 --weekly=4 --monthly=-1
|
||||
|
||||
|
||||
.. include:: usage/info.rst.inc
|
||||
|
||||
|
|
|
|||
|
|
@ -29,6 +29,18 @@ attic prune
|
|||
number of yearly archives to keep
|
||||
-p PREFIX, --prefix PREFIX
|
||||
only consider archive names starting with this prefix
|
||||
|
||||
The prune command prunes a repository by deleting archives not matching any of
|
||||
the specified retention options. This command is normally used by automated
|
||||
backup scripts wanting to keep a certain number of historic backups. As an
|
||||
example, "-d 7" means to keep the latest backup on each day for 7 days. Days
|
||||
without backups do not count towards the total. The rules are applied from
|
||||
hourly to yearly, and backups selected by previous rules do not count towards
|
||||
those of later rules. Dates and times are interpreted in the local timezone,
|
||||
and weeks go from Monday to Sunday. Specifying a negative number of archives
|
||||
to keep means that there is no limit. If a prefix is set with -p, then only
|
||||
archives that start with the prefix are considered for deletion and only those
|
||||
archives count towards the totals specified by the rules.
|
||||
|
||||
Description
|
||||
~~~~~~~~~~~
|
||||
|
|
|
|||
Loading…
Reference in a new issue