git-annex/doc/copies.mdwn

Annexed data is stored inside  your git repository's `.git/annex` directory.
Some [[special_remotes]] can store annexed data elsewhere.

It's important that data not get lost by an ill-considered `git annex drop`
command.  So, git-annex can be configured to try
to keep N copies of a file's content available across all repositories. 
(Although [[untrusted_repositories|trust]] don't count toward this total.)

By default, N is 1; it is configured by running `git annex numcopies N`.
This default can be overridden on a per-file-type basis by the annex.numcopies
setting in `.gitattributes` files. The --numcopies switch allows
temporarily using a different value.

`git annex drop` attempts to check with other git remotes, to check that N
copies of the file exist. If enough repositories cannot be verified to have
it, it will retain the file content to avoid data loss. Note that
[[trusted_repositories|trust]] are not explicitly checked.

For example, consider three repositories: Server, Laptop, and USB. Both Server
and USB have a copy of a file, and N=1. If on Laptop, you `git annex get
$file`, this will transfer it from either Server or USB (depending on which
is available), and there are now 3 copies of the file.

Suppose you want to free up space on Laptop again, and you `git annex drop` the file
there. If USB is connected, or Server can be contacted, git-annex can check
that it still has a copy of the file, and the content is removed from
Laptop. But if USB is currently disconnected, and Server also cannot be
contacted, it can't verify that it is safe to drop the file, and will
refuse to do so.

With N=2, in order to drop the file content from Laptop, it would need access
to both USB and Server.
update documentation for new, neutered key-value backends Backends are now only used to generate keys (and check them); they are not arbitrary key-value stores for data, because it turned out such a store is better modeled as a special remote. Updated docs to not imply backends do more than they do now. Sometimes I'm tempted to rename "backend" to "keytype" or something, which would really be more clear. But it would be an annoying transition for users, with annex.backends etc. 2011-08-28 20:28:38 +00:00			Annexed data is stored inside your git repository's `.git/annex` directory.
			`Some [[special_remotes]] can store annexed data elsewhere.`
update 2010-10-19 19:59:40 +00:00
			It's important that data not get lost by an ill-considered `git annex drop`
update documentation for new, neutered key-value backends Backends are now only used to generate keys (and check them); they are not arbitrary key-value stores for data, because it turned out such a store is better modeled as a special remote. Updated docs to not imply backends do more than they do now. Sometimes I'm tempted to rename "backend" to "keytype" or something, which would really be more clear. But it would be an annoying transition for users, with annex.backends etc. 2011-08-28 20:28:38 +00:00			`command. So, git-annex can be configured to try`
In .gitattributes, the git-annex-numcopies attribute can be used to control the number of copies to retain of different types of files. 2010-11-28 19:28:20 +00:00			`to keep N copies of a file's content available across all repositories.`
document 3-level trust 2011-01-26 18:09:06 +00:00			`(Although [[untrusted_repositories\|trust]] don't count toward this total.)`
In .gitattributes, the git-annex-numcopies attribute can be used to control the number of copies to retain of different types of files. 2010-11-28 19:28:20 +00:00
global numcopies setting * numcopies: New command, sets global numcopies value that is seen by all clones of a repository. * The annex.numcopies git config setting is deprecated. Once the numcopies command is used to set the global number of copies, any annex.numcopies git configs will be ignored. * assistant: Make the prefs page set the global numcopies. This global numcopies setting is needed to let preferred content expressions operate on numcopies. It's also convenient, because typically if you want git-annex to preserve N copies of files in a repo, you want it to do that no matter which repo it's running in. Making it global avoids needing to warn the user about gotchas involving inconsistent annex.numcopies settings. (See changes to doc/numcopies.mdwn.) Added a new variety of git-annex branch log file, that holds only 1 value. Will probably be useful for other stuff later. This commit was sponsored by Nicolas Pouillard. 2014-01-20 20:47:56 +00:00			By default, N is 1; it is configured by running `git annex numcopies N`.
			`This default can be overridden on a per-file-type basis by the annex.numcopies`
mention --numcopies 2011-06-01 20:54:28 +00:00			setting in `.gitattributes` files. The --numcopies switch allows
			`temporarily using a different value.`
update 2010-10-19 19:59:40 +00:00
			`git annex drop` attempts to check with other git remotes, to check that N
			`copies of the file exist. If enough repositories cannot be verified to have`
Add trust and untrust subcommands, to allow configuring remotes that are trusted to retain files without explicit checking. 2010-12-28 21:17:02 +00:00			`it, it will retain the file content to avoid data loss. Note that`
wording 2010-12-29 21:01:56 +00:00			`[[trusted_repositories\|trust]] are not explicitly checked.`
update 2010-10-19 19:59:40 +00:00
			`For example, consider three repositories: Server, Laptop, and USB. Both Server`
			and USB have a copy of a file, and N=1. If on Laptop, you `git annex get
			$file`, this will transfer it from either Server or USB (depending on which
			`is available), and there are now 3 copies of the file.`

			Suppose you want to free up space on Laptop again, and you `git annex drop` the file
			`there. If USB is connected, or Server can be contacted, git-annex can check`
			`that it still has a copy of the file, and the content is removed from`
			`Laptop. But if USB is currently disconnected, and Server also cannot be`
			`contacted, it can't verify that it is safe to drop the file, and will`
			`refuse to do so.`

			`With N=2, in order to drop the file content from Laptop, it would need access`
			`to both USB and Server.`