diff options
Diffstat (limited to 'doc/metadata.mdwn')
-rw-r--r-- | doc/metadata.mdwn | 41 |
1 files changed, 41 insertions, 0 deletions
diff --git a/doc/metadata.mdwn b/doc/metadata.mdwn new file mode 100644 index 000000000..d3c3b748e --- /dev/null +++ b/doc/metadata.mdwn @@ -0,0 +1,41 @@ +git-annex allows you to store arbitrary metadata about files stored in the +git-annex repository. The metadata is stored in the `git-annex` branch, and +so is automatically kept in sync with the rest of git-annex's state, such +as [[location_tracking]] information. + +Some of the things you can do with metadata include: + +* Using `git annex metadata file` to show all + the metadata associated with a file. +* [[tips/metadata_driven_views]] +* Limiting the files git-annex commands act on to those with + or without particular metadata. + For example `git annex find --metadata tag=foo --or --metadata tag=bar` +* Using it in [[preferred_content]] expressions. + For example "tag=important or not author=me" + +Each file (actually the underlying key) can have any number of metadata +fields, which each can have any number of values. For example, to tag +files, the `tag` field is typically used, with values set to each tag that +applies to the file. + +The field names are limited to alphanumerics (and `[_-.]`). The metadata +values can contain absolutely anything you like -- but you're recommended +to keep it simple and reasonably short. + +Here are some recommended metadata fields to use: + +* `tag` - With each tag being a different value. +* `year`, `month` - When this particular version of the file came into + being. + +To make git-annex automatically set the year and month when adding files, +run `git config annex.genmetadata true` + +git-annex's metadata can be updated in a distributed fashion. For example, +two users, each with their own clone of a repository, can set and unset +metadata at the same time, even for the same field of the same file. +When they push their changes, `git annex merge` will combine their +metadata changes in a consistent and (probably) intuitive way. + +See [[the metadata design page|design/metadata]] for more details. |