From 2696ed67ebb4a3be994ff35567bdc74459d9f0bf Mon Sep 17 00:00:00 2001 From: Joey Hess Date: Fri, 30 Nov 2012 16:01:29 -0400 Subject: document the key format --- doc/internals.mdwn | 2 +- doc/internals/key_format.mdwn | 20 ++++++++++++++++++++ 2 files changed, 21 insertions(+), 1 deletion(-) create mode 100644 doc/internals/key_format.mdwn diff --git a/doc/internals.mdwn b/doc/internals.mdwn index 89940ba6a..34498b912 100644 --- a/doc/internals.mdwn +++ b/doc/internals.mdwn @@ -11,7 +11,7 @@ to the file content. First there are two levels of directories used for hashing, to prevent too many things ending up in any one directory. -Each subdirectory has the name of a key in one of the +Each subdirectory has the [[name_of_a_key|key_format]] in one of the [[key-value_backends|backends]]. The file inside also has the name of the key. This two-level structure is used because it allows the write bit to be removed from the subdirectories as well as from the files. That prevents accidentially diff --git a/doc/internals/key_format.mdwn b/doc/internals/key_format.mdwn new file mode 100644 index 000000000..f08055234 --- /dev/null +++ b/doc/internals/key_format.mdwn @@ -0,0 +1,20 @@ +A git-annex key has this format: + + BACKEND-sNNNN-mNNNN--NAME + +For example: + + SHA256E-s31390--f50d7ac4c6b9031379986bc362fcefb65f1e52621ce1708d537e740fefc59cc0.mp3 + +* The backend is one of the [[key-value_backends|backends]], which + are always upper-cased. +* The name field at the end has a format dependent on the backend. It is + always the last field, and is prefixed with "--". Unlike other fields, + it may contain "-" in its content. It should not contain newline characters; + otherwise nearly anything goes. +* The "-s" field is optional, and is the size of the content in bytes. +* The "-m" field is optional, and is the mtime of the file when it was + added to git-annex, expressed as seconds from the epoch. + This is currently only used by the WORM backend. +* Other fields could be added in the future, if needed. +* Fields may appear, in any order (though always before the name field). -- cgit v1.2.3