git-annex/doc/metadata.mdwn

git-annex allows you to store arbitrary metadata about the content of 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 "metadata=tag=important or not metadata=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 `[_-.]`), and are case
insensitive. The metadata values can contain absolutely anything you
like -- but you're recommended to keep it simple and reasonably short.

Here are some metadata fields that git-annex has special support for:

* `tag` - With each tag being a different value.
* `year`, `month` - When this particular version of the file came into
  being.
* `$field-lastchanged` - This is automatically maintained for each
  field that's set, and gives the date and time of the most recent
  change to the field. It cannot be modified directly.
* `lastchanged` - This is automatically maintained, giving the data and time
  of the last change to any of the metadata of a file.

To make git-annex automatically set the year and month when adding files,
run `git config annex.genmetadata true`. Also, see
[[tips/automatically_adding_metadata]].

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.
improve metadata documentation 2014-03-26 20:55:29 +00:00			`git-annex allows you to store arbitrary metadata about the content of 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.`
annex.genmetadata can be set to make git-annex automatically set metadata (year and month) when adding files 2014-02-23 04:08:29 +00:00
			`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.`
2014-04-07 11:46:18 +00:00			`For example "metadata=tag=important or not metadata=author=me"`
annex.genmetadata can be set to make git-annex automatically set metadata (year and month) when adding files 2014-02-23 04:08:29 +00:00
			`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.`

metadata: FIeld names are now case insensative. 2014-02-25 22:45:09 +00:00			The field names are limited to alphanumerics (and `[_-.]`), and are case
			`insensitive. The metadata values can contain absolutely anything you`
			`like -- but you're recommended to keep it simple and reasonably short.`
annex.genmetadata can be set to make git-annex automatically set metadata (year and month) when adding files 2014-02-23 04:08:29 +00:00
Each for each metadata field, there's now an automatically maintained "$field-lastchanged" that gives the timestamp of the last change to that field. Note that this is a nearly entirely free feature. The data was already stored in the metadata log in an easily accessible way, and already was parsed to a time when parsing the log. The generation of the metadata fields may even be done lazily, although probably not entirely (the map has to be evaulated to when queried). 2014-03-18 22:55:43 +00:00			`Here are some metadata fields that git-annex has special support for:`
annex.genmetadata can be set to make git-annex automatically set metadata (year and month) when adding files 2014-02-23 04:08:29 +00:00
			* `tag` - With each tag being a different value.
			* `year`, `month` - When this particular version of the file came into
			`being.`
Each for each metadata field, there's now an automatically maintained "$field-lastchanged" that gives the timestamp of the last change to that field. Note that this is a nearly entirely free feature. The data was already stored in the metadata log in an easily accessible way, and already was parsed to a time when parsing the log. The generation of the metadata fields may even be done lazily, although probably not entirely (the map has to be evaulated to when queried). 2014-03-18 22:55:43 +00:00			* `$field-lastchanged` - This is automatically maintained for each
better timestamp format 2014-03-18 23:01:50 +00:00			`field that's set, and gives the date and time of the most recent`
			`change to the field. It cannot be modified directly.`
toplevel lastchanged field 2014-03-19 23:10:35 +00:00			* `lastchanged` - This is automatically maintained, giving the data and time
			`of the last change to any of the metadata of a file.`
Each for each metadata field, there's now an automatically maintained "$field-lastchanged" that gives the timestamp of the last change to that field. Note that this is a nearly entirely free feature. The data was already stored in the metadata log in an easily accessible way, and already was parsed to a time when parsing the log. The generation of the metadata fields may even be done lazily, although probably not entirely (the map has to be evaulated to when queried). 2014-03-18 22:55:43 +00:00
annex.genmetadata can be set to make git-annex automatically set metadata (year and month) when adding files 2014-02-23 04:08:29 +00:00			`To make git-annex automatically set the year and month when adding files,`
pre-commit-annex hook script to automatically extract metadata from lots of types of files Using the extract(1) program to do the heavy lifting. Decided to make git-annex run pre-commit-annex when committing. Since git-annex pre-commit also runs it, it'll be run when git commit is run too, via the pre-commit hook. This basically gives back the pre-commit hook that git-annex took away. The implementation avoids repeatedly looking for the hook script when the assistant is running and committing repeatedly; only checks if the hook is available once. To make the script simpler, made git-annex metadata -s field?=value only set a field when it's not already got a value. This commit was sponsored by bak. 2014-03-02 22:01:07 +00:00			run `git config annex.genmetadata true`. Also, see
			`[[tips/automatically_adding_metadata]].`
annex.genmetadata can be set to make git-annex automatically set metadata (year and month) when adding files 2014-02-23 04:08:29 +00:00
			`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.`