1. Exascale User's Guide
  2. Using ESCLI
  3. ESCLI Command Reference
  4. File Management
  5. lssnapshots

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 filename { --all | --tree | [ -l ] [ --detail ] [ --attributes attribute[,attribute] ... ] 
     [ --filter filter[,filter] ... ] [ --count value ] }

Command Options

The options for the lssnapshots command are:

  • filename: 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: Returns output in a long, tabular form.

  • --detail: Lists all attributes in a detailed form.

  • --attributes: Lists the specific attributes to display.

  • --filter: Used to specify conditions for filtering the output.

  • --count: Specifies the maximum number of results to report.

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-95 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 @MYDATA/x

Example 6-96 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 @MYDATA/x --detail

Example 6-97 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 @MYDATA/x --detail --attributes name,vault.name,createTime,vault.createTime

Example 6-98 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 @MYDATA/x --filter createTime>2020-01-01

Example 6-99 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 @MYDATA/x --count 5

Example 6-100 Display a Snapshot Tree

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

@TEST/> putfile somelocalfile file1
Putting file somelocalfile to @TEST/file1
Success.

@TEST/> snapshotfile file1 snap1_of_file1
Success.

@TEST/> clonefile file1 clone1
Success.

@TEST/> snapshotfile file1 snap2_of_file1
Success.

@TEST/> 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 @TEST/clone1 --tree

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

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

Example 6-101 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 @TEST/clone1 --all

---FILE/CLONES:---

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

---SNAPSHOTS:---

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

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

Parent topic: File Management