summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorGravatar Joey Hess <joey@kitenet.net>2014-02-23 00:08:29 -0400
committerGravatar Joey Hess <joey@kitenet.net>2014-02-23 00:08:29 -0400
commit704fa2fa789b453d354f2f375b0b42481c8990f6 (patch)
treeafb28b2548c067be546b22fa6b04fa8b5d76c3fd /doc
parente0ae2f6bba897367ae23bfb1a6584ebd4843452e (diff)
annex.genmetadata can be set to make git-annex automatically set metadata (year and month) when adding files
Diffstat (limited to 'doc')
-rw-r--r--doc/design/metadata.mdwn18
-rw-r--r--doc/git-annex.mdwn6
-rw-r--r--doc/metadata.mdwn41
-rw-r--r--doc/tips/metadata_driven_views.mdwn2
4 files changed, 50 insertions, 17 deletions
diff --git a/doc/design/metadata.mdwn b/doc/design/metadata.mdwn
index a648f5fe6..992ae1ca7 100644
--- a/doc/design/metadata.mdwn
+++ b/doc/design/metadata.mdwn
@@ -29,7 +29,7 @@ directories nest.
relevant metadata from the files.
TODO: It's not clear that
removing a file should nuke all the metadata used to filter it into the
- branch (especially if it's derived metadata like the year).
+ branch
Currently, only metadata used for visible subdirs is added and removed
this way.
Also, this is not usable in direct mode because deleting the
@@ -56,19 +56,7 @@ For example, by examining MP3 metadata.
Also auto add metadata when adding files to view branches. See below.
-## derived metadata
-
-This is probably not stored anywhere. It's computed on demand by a pure
-function from the other metadata.
-(Should be a general mechanism for this. (It probably generalizes to
-sql queries if we want to go that far.))
-
-### data metadata
-
-TODO From the ctime, some additional
-metadata is derived, at least year=yyyy and probably also month, etc.
-
-### directory hierarchy metadata
+## directory hierarchy metadata
From the original filename used in the master branch, when
constructing a view, generate fields. For example foo/bar/baz.mp3
@@ -87,8 +75,6 @@ those filenames to derive the same metadata, unless there is persistent
storage. Luckily, the filenames used in the views currently include the
subdirs.
-**done**!
-
# other uses for metadata
Uses are not limited to view branches.
diff --git a/doc/git-annex.mdwn b/doc/git-annex.mdwn
index 3c233f378..ab158a952 100644
--- a/doc/git-annex.mdwn
+++ b/doc/git-annex.mdwn
@@ -1279,6 +1279,12 @@ Here are all the supported configuration settings.
Note that setting numcopies to 0 is very unsafe.
+* `annex.genmetadata`
+
+ Set this to `true` to make git-annex automatically generate some metadata
+ when adding files to the repository. In particular, it stores
+ year and month metadata, from the file's modification date.
+
* `annex.queuesize`
git-annex builds a queue of git commands, in order to combine similar
diff --git a/doc/metadata.mdwn b/doc/metadata.mdwn
new file mode 100644
index 000000000..414a91053
--- /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 freeform (but cannot include spaces). 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.
diff --git a/doc/tips/metadata_driven_views.mdwn b/doc/tips/metadata_driven_views.mdwn
index e24bf29ae..0af05bd3f 100644
--- a/doc/tips/metadata_driven_views.mdwn
+++ b/doc/tips/metadata_driven_views.mdwn
@@ -1,5 +1,5 @@
git-annex now has support for storing
-[[arbitrary metadata|design/metadata]] about annexed files. For example, this can be
+[[arbitrary metadata|metadata]] about annexed files. For example, this can be
used to tag files, to record the author of a file, etc. The metadata is
synced around between repositories with the other information git-annex
keeps track of.