document 3-level trust

1 files changed, 34 insertions, 5 deletions

diff --git a/doc/trust.mdwn b/doc/trust.mdwn
index 6ce43f30e..edec6568e 100644
--- a/doc/trust.mdwn
+++ b/doc/trust.mdwn
@@ -1,3 +1,11 @@
+Git-annex supports three levels of trust of a repository:
+
+* semitrusted (default)
+* untrusted
+* trusted
+
+## semi-trusted
+
 Normally, git-annex does not fully trust its stored [[location_tracking]]
 information. When removing content, it will directly check
 that other repositories have enough [[copies]].
@@ -7,14 +15,35 @@ Generally that explicit checking is a good idea. Consider that the current
 out. Or, a remote may have suffered a catastrophic loss of data, or itself
 been lost.
 
-Sometimes though, you may have reasons to trust the location tracking
-information for a remote repository. For example, it may be an offline
+There is still some trust involved here. A semi-trusted repository is
+dependended on to retain a copy of the file content; possibly the only
+[[copy|copies]].
+
+(Being semitrusted is the default. The `git annex semitrust` command
+restores a repository to this default, when it has been overridden.)
+
+## untrusted
+
+An untrusted repository is not trusted to retain data at all. Git-annex
+will not count data in such a repository as a of the data, and will
+retain sufficient [[copies]] elsewhere.
+
+This is a good choice for eg, portable drives that could get lost. Or,
+if a disk is known to be dying, you can set it to untrusted and let
+`git annex fsck` warn about data that needs to be copied off it.
+
+To configure a repository as untrusted, use the `git annex untrust`
+command.
+
+## trusted
+
+Sometimes, you may have reasons to fully trust the location tracking
+information for a repository. For example, it may be an offline
 archival drive, from which you rarely or never remove content. Deciding
 when it makes sense to trust the tracking info is up to you.
 
 One way to handle this is just to use `--force` when a command cannot
 access a remote you trust.
 
-Another option is to configure which remotes you trust with the 
-`git annex trust` command, or by manually adding the UUIDs of trusted remotes
-to `.git-annex/trust.log`.
+To configure a repository as fully trusted, use the `git annex trust`
+command.