6.2.8.7 lssnapshots

List snapshots associated with a file.

Purpose

The lssnapshots command displays information about snapshots that are associated with the specified file.

Syntax

lssnapshots file-name [ --all | --tree ] [ -l ] [ --detail ] 
            [ --attributes attribute[,attribute]... ] 
            [ --filter filter[,filter]... ] [ --count value ]

Command Options

The options for the lssnapshots command are:

  • file-name: Identifies the file that is the subject of the command. The specified file can be a snapshot, clone, or regular file.

  • --all: Lists information about all files, clones, and snapshots belonging to the snapshot tree that contains the specified file. The output is presented in a series of lists. The first list contains the files and clones in the snapshot tree. The remaining output lists snapshots that are grouped by their source file.

  • --tree: Lists information about all files, clones, and snapshots belonging to the snapshot tree that contains the specified file. The output is arranged in a graphical tree.

  • -l: Displays output in a long, tabular format.

  • --detail: Displays detailed output with additional attributes.

  • --attributes: Identifies specific attributes to display in the output.

    You can use this option to focus on a subset of attributes as an alternative to the --detail option.

  • --filter: Specifies conditions for including items in the output.

  • --sort: Sorts the output using the specified attributes.

  • --count: Specifies the maximum number of items to display in the output.

Usage Notes

Note the following information when using this command:

  • If you do not specify the command options --all or --tree, then the command displays information about immediate snapshots of the specified source file.

  • You cannot use any other command options in conjunction with --all or --tree.

  • Filters are specified as: <attribute><operator><value>.

    Attributes can be file attributes, or vault attributes with the vault. prefix. Multiple filter conditions are delimited by commas.

    The allowed operators are =, >=, <=, >, and <.

    Dates can be specified using the following formats:

    • yyyy-MM-dd''T''HH:mm:ss
    • yyyy-MM-dd (Time is assumed to be 00:00 AM)
    • HH:mm:ss (Date is assumed to be today)

    Any of these formats can be followed by a timezone specification.

    File sizes can be specified using suffixes K, KB, M, MB, G, GB, T, TB. The suffix is not case-sensitive.

    For example, to filter the results to show only snapshots created after noon today, with a size greater than 10 megabytes, you could use the following:

    --filter creationTime>12:00:00,size>10M

  • Output is ordered according to the snapshot creation time, starting with the most recent.

Examples

Example 6-96 List Basic Snapshot Information

The following example shows how to list information about all of the snapshots that are based on the specified file.

@> lssnapshots @my-data/my-file

Example 6-97 List Detailed Snapshot Information

The following example shows how to list detailed information about all of the snapshots that are based on the specified file.

@> lssnapshots @my-data/my-file --detail

Example 6-98 List Snapshot Information with Specific Attributes

The following example shows how to list specific attributes about all of the snapshots that are based on the specified file.

@> lssnapshots @my-data/my-file --detail --attributes name,vault.name,createTime,vault.createTime

Example 6-99 Filter the List of Snapshots

The following example shows how to specify a filter that constrains the command output. In the example, the output is limited to the snapshots that were created after the specified date.

@> lssnapshots @my-data/my-file --filter createTime>2020-01-01

Example 6-100 List the Latest Snapshots

The following example shows how to specify a count that constrains the command output. In the example, the output is limited to the 5 most recently created snapshots.

@> lssnapshots @my-data/my-file --count 5

Example 6-101 Display a Snapshot Tree

The command output in this example assumes a group of related files created using the following command sequence:

@my-data/> putfile somelocalfile file1
Putting file somelocalfile to @my-data/file1
Success.

@my-data/> snapshotfile file1 snap1_of_file1
Success.

@my-data/> clonefile file1 clone1
Success.

@my-data/> snapshotfile file1 snap2_of_file1
Success.

@my-data/> snapshotfile clone1 snap1_of_clone1
Success.

The following example shows how to display all files in a snapshot tree using the --tree command option. 

@> lssnapshots @my-data/clone1 --tree

+---- [1] @my-data/snap1_of_file1
+---- [2] @my-data/?8000_0000_000a:00000001
|
|`---+---- [4] @my-data/snap1_of_clone1
|    +---- [6] @my-data/clone1
|
+---- [3] @my-data/snap2_of_file1
+---- [5] @my-data/file1

Note that the command output includes an internal snapshot (@my-data/?8000_0000_000a:00000001), which was implicitly created as part of the cloning operation to create @my-data/clone1.

Example 6-102 List all Files in a Snapshot Tree

The following example shows how to display all files in a snapshot tree using the --all command option. This example assumes the same scenario as the previous example. 

@> lssnapshots @my-data/clone1 --all

---FILE/CLONES:---

2022-05-02 06:14:41 UTC @my-data/file1
2022-05-02 06:15:15 UTC @my-data/clone1

---SNAPSHOTS:---

@my-data/file1
  2022-05-02 06:15:06 UTC @my-data/snap1_of_file1
  2022-05-02 06:15:15 UTC @my-data/?8000_0000_000a:00000001
  2022-05-02 06:15:24 UTC @my-data/snap2_of_file1

@my-data/clone1
  2022-05-02 06:15:45 UTC @my-data/snap1_of_clone1

Parent topic: File Management