bupstash-list-contents(1) 
=========================

## SYNOPSIS

List snapshot contents.

`bupstash list-contents [OPTIONS] QUERY... `

## DESCRIPTION

`bupstash list-contents` lists the contents of the item matching the given query.

Items created by using `bupstash put` on a directory will have an associated index, other items
are not listable.

## OUTPUT FORMATS

### Human

When `--format` is set to `human`, `bupstash list-contents` outputs aligned rows consisting of:

```
PERMS SIZE YYYY/MM/DD HH:MM:SS PATH...
```

The included date is the time of the last change to a given file as reported by the
operating system at the time of the snapshot.

Prefer using one of the versioned machine readable formats when writing scripts.

### JSONl1

When `--format` is set to `jsonl1`, `bupstash list-contents` outputs one json object per line.

Each line has the following json schema:

```
{
  "path": string | [ bytes... ],
  "mode": number,
  "size": number,
  "uid": number,
  "gid": number,
  "mtime": number,
  "mtime_nsec": number,
  "ctime": number,
  "ctime_nsec": number,
  "norm_dev": number,
  "ino": number,
  "nlink": number,
  "link_target": string | null,
  "dev_major": number | null,
  "dev_minor": number | null,
  "xattrs": {string : string | [bytes...] ...} | null,
  "sparse": boolean,
  "data_hash": "$KIND[:$HEXBYTE]" | null
}
```

## QUERY LANGUAGE

For full documentation on the query language, see bupstash-query-language(7).

## QUERY CACHING

The list-contents command uses the same query caching mechanisms as bupstash-list(1), check that page for
more information on the query cache.

## OPTIONS

* -r, --repository REPO:
  The repository to connect to, , may be of the form `ssh://$SERVER/$PATH` for
  remote repositories if ssh access is configured. If not specified, is set to `BUPSTASH_REPOSITORY`.

* -k, --key KEY:
  Key used to decrypt data and metadata. If not set, defaults
  to `BUPSTASH_KEY`.

* --format FORMAT:
  Set output format to one of the following 'human', 'jsonl'.

* --query-cache PATH:
  Path to the query-cache file, defaults to one of the following, in order, provided
  the appropriate environment variables are set, `$BUPSTASH_QUERY_CACHE`,
  `$XDG_CACHE_HOME/.cache/bupstash/bupstash.qcache` or `$HOME/.cache/bupstash/bupstash.qcache`.

* --pick PATH:
  List a sub-directory of the query.

* --utc-timestamps:
  Display and search against timestamps in utc time instead of local time.

  * --no-progress:
  Suppress progress indicators (Progress indicators are also suppressed when stderr
  is not an interactive terminal).

* -q, --quiet:
  Be quiet, implies --no-progress.

## ENVIRONMENT

* BUPSTASH_REPOSITORY:
  The repository to connect to. May be of the form `ssh://$SERVER/$PATH` for
  remote repositories if ssh access is configured.

* BUPSTASH_REPOSITORY_COMMAND:
  A command to run to connect to an instance of bupstash-serve(1). This 
  allows more complex connections to the repository for less common use cases.

* BUPSTASH_KEY:
  Path to a primary key that will be used for decrypting data and metadata.

* BUPSTASH_KEY_COMMAND:
  A command to run that must print the key data, can be used instead of BUPSTASH_KEY
  to fetch the key from arbitrary locations such as the network or other secret storage.

* BUPSTASH_QUERY_CACHE:
  Path to the query cache file to use.


## EXAMPLES

### Get an item with a specific id from the repository

```
$ bupstash list-contents id="14eb*"
drwxr-xr-x 0     2020/10/30 13:32:04 .
-rw-r--r-- 1967  2020/10/30 13:32:04 data.txt
```

## SEE ALSO

bupstash(1), bupstash-put(1), bupstash-diff(1), bupstash-keyfiles(7), bupstash-query-language(7)