git-annex/doc/git-annex-view.mdwn

# NAME

git-annex view - enter a view branch

# SYNOPSIS

git annex view `[tag ...] [field=value ...] [field=glob ...] [?tag ...] [field?=glob] [!tag ...] [field!=value ...]`

# DESCRIPTION

Uses metadata to build a view branch of the files in the current branch,
and checks out the view branch. Only files in the current branch whose
metadata matches all the specified field values and tags will be
shown in the view.

Multiple values for a metadata field can be specified, either by using
a glob (`field="*"`) or by listing each wanted value. The resulting view
will put files in subdirectories according to the value of their fields.
  
Once within such a view, you can make additional directories, and
copy or move files into them. When you commit, the metadata will
be updated to correspond to your changes. Deleting files and committing
also updates the metadata.

As well as the usual metadata, there are fields available corresponding
to the path to the file. So a file "foo/bar/baz/file" has fields "/=foo",
"foo/=bar", and "foo/bar/=baz". These location fields can be used the
same as other metadata to construct the view.

For example, `/=foo` will only include files from the foo
directory in the view, while `foo/=*` will preserve the
subdirectories of the foo directory in the view.

To enter a view containing only files that lack a given metadata
value or tag, specify field!=value or !tag. (Globs cannot be used here.)

`field?=*` is like `field=*` but adds an additional directory named `_` (by
default) that contains files that do not have the field set to any value.
Similarly, `?tag` adds an additional directory named `_` that contains
files that do not have any tags set. Moving files from the `_` directory to
another directory and committing will set the metadata. And moving files
into the `_` directory and committing will unset the metadata. 

The name of the `_` directory can be changed using the annex.viewunsetdirectory
git config.

Filenames in the view branch include their path within the original branch, to
ensure that they are unique. The path comes after the main filename, and
before any extensions. For example, "foo/bar.baz" will have a name
like "bar_%foo%.baz". annex.maxextensionlength can be used to configure
what is treated as an extension.

# OPTIONS

* The [[git-annex-common-options]](1) can be used.

# SEE ALSO

[[git-annex]](1)

[[git-annex-metadata]](1)

[[git-annex-vpop]](1)

[[git-annex-vfilter]](1)

[[git-annex-vadd]](1)

[[git-annex-vcycle]](1)

[[git-annex-adjust]](1)

# AUTHOR

Joey Hess <id@joeyh.name>

Warning: Automatically converted into a man page by mdwn2man. Edit with care.