restic list pack snapshotID - create lists of packfiles for a given snapshot as text (#5396)

Co-authored-by: Michael Eischer <michael.eischer@fau.de>

changelog/unreleased/issue-5372

@@ -0,0 +1,7 @@
+Enhancement: Add command to list packfiles belonging to a snapshot
+
+This enhancement adds command `list packs snapshotID` to show the packfiles
+belonging to the given snapshot.
+
+https://github.com/restic/restic/issues/5372
+https://github.com/restic/restic/pull/5396

cmd/restic/cmd_list.go

@@ -2,8 +2,10 @@ package main
 
 import (
 	"context"
+	"fmt"
 	"strings"
 
+	"github.com/restic/restic/internal/data"
 	"github.com/restic/restic/internal/errors"
 	"github.com/restic/restic/internal/global"
 	"github.com/restic/restic/internal/repository"
@@ -19,10 +21,12 @@ func newListCommand(globalOptions *global.Options) *cobra.Command {
 	var listAllowedArgsUseString = strings.Join(listAllowedArgs, "|")
 
 	cmd := &cobra.Command{
-		Use:   "list [flags] [" + listAllowedArgsUseString + "]",
+		Use:   "list [flags] [" + listAllowedArgsUseString + "|packs snapshotID]",
 		Short: "List objects in the repository",
 		Long: `
 The "list" command allows listing objects in the repository based on type.
+The "list packs snapshotID" variant accepts one snapshotID and lists all packfiles
+used by this snapshot.
 
 EXIT STATUS
 ===========
@@ -36,19 +40,18 @@ Exit status is 12 if the password is incorrect.
 		DisableAutoGenTag: true,
 		GroupID:           cmdGroupDefault,
 		RunE: func(cmd *cobra.Command, args []string) error {
-			return runList(cmd.Context(), *globalOptions, args, globalOptions.Term)
+			return runList(cmd.Context(), *globalOptions, args, globalOptions.Term, listAllowedArgsUseString)
 		},
 		ValidArgs: listAllowedArgs,
-		Args:      cobra.MatchAll(cobra.ExactArgs(1), cobra.OnlyValidArgs),
 	}
 	return cmd
 }
 
-func runList(ctx context.Context, gopts global.Options, args []string, term ui.Terminal) error {
+func runList(ctx context.Context, gopts global.Options, args []string, term ui.Terminal, listAllowedArgsUseString string) error {
 	printer := progress.NewTerminalPrinter(false, gopts.Verbosity, term)
 
-	if len(args) != 1 {
-		return errors.Fatal("type not specified")
+	if len(args) == 0 || (args[0] == "packs" && len(args) > 2) || (args[0] != "packs" && len(args) != 1) {
+		return errors.Fatal(fmt.Sprintf("too many parameters or type not specified. Must be one of [%s] or 'packs snapshotID'", listAllowedArgsUseString))
 	}
 
 	ctx, repo, unlock, err := openWithReadLock(ctx, gopts, gopts.NoLock || args[0] == "locks", printer)
@@ -61,6 +64,10 @@ func runList(ctx context.Context, gopts global.Options, args []string, term ui.T
 	switch args[0] {
 	case "packs":
 		t = restic.PackFile
+		if len(args) == 2 {
+			// args[1] needs to be a snapshotID
+			return packfileList(ctx, repo, args[1], printer)
+		}
 	case "index":
 		t = restic.IndexFile
 	case "snapshots":
@@ -86,3 +93,38 @@ func runList(ctx context.Context, gopts global.Options, args []string, term ui.T
 		return nil
 	})
 }
+
+// packfileList handles the list packs <snapshotID> variant.
+// It prints a sorted list of packfiles belonging to this snapshot.
+func packfileList(ctx context.Context, repo restic.Repository, snapshotID string, printer progress.Printer) error {
+	sn, _, err := (&data.SnapshotFilter{}).FindLatest(ctx, repo, repo, snapshotID)
+	if err != nil {
+		return fmt.Errorf("required snapshot ID %q not found", snapshotID)
+	}
+
+	if err = repo.LoadIndex(ctx, printer); err != nil {
+		return err
+	}
+
+	usedBlobs := repo.NewAssociatedBlobSet()
+	bar := printer.NewCounter("snapshot")
+	bar.SetMax(uint64(1))
+	err = data.FindUsedBlobs(ctx, repo, []restic.ID{*sn.Tree}, usedBlobs, bar)
+	bar.Done()
+	if err != nil {
+		return err
+	}
+
+	snapPacks := restic.NewIDSet()
+	for bh := range usedBlobs.Keys() {
+		for _, blob := range repo.LookupBlob(bh) {
+			snapPacks.Insert(blob.PackID())
+		}
+	}
+
+	for _, packID := range snapPacks.List() {
+		printer.S("%v", packID)
+	}
+
+	return nil
+}

cmd/restic/cmd_list_integration_test.go

@@ -14,9 +14,9 @@ import (
 	"github.com/restic/restic/internal/ui/progress"
 )
 
-func testRunList(t testing.TB, gopts global.Options, tpe string) restic.IDs {
+func testRunList(t testing.TB, gopts global.Options, params ...string) restic.IDs {
 	buf, err := withCaptureStdout(t, gopts, func(ctx context.Context, gopts global.Options) error {
-		return runList(ctx, gopts, []string{tpe}, gopts.Term)
+		return runList(ctx, gopts, params, gopts.Term, "")
 	})
 	rtest.OK(t, err)
 	return parseIDsFromReader(t, buf)
@@ -102,3 +102,24 @@ func TestListBlobs(t *testing.T) {
 
 	rtest.Assert(t, blobSetFromIndex.Equals(testIDSet), "the set of restic.ID s should be equal")
 }
+
+func TestPackfileListWithSnapshot(t *testing.T) {
+	// setup
+	env, cleanup := withTestEnvironment(t)
+	defer cleanup()
+	testSetupBackupData(t, env)
+
+	// 3 backups, single file each
+	opts := BackupOptions{}
+	testRunBackup(t, env.testdata, []string{filepath.Join(env.testdata, "0", "0", "9", "40")}, opts, env.gopts)
+	testRunBackup(t, env.testdata, []string{filepath.Join(env.testdata, "0", "0", "9", "41")}, opts, env.gopts)
+	testRunBackup(t, env.testdata, []string{filepath.Join(env.testdata, "0", "0", "9", "42")}, opts, env.gopts)
+	testListSnapshots(t, env.gopts, 3)
+
+	// run packfilelist
+	packfiles := testRunList(t, env.gopts, "packs")
+	rtest.Assert(t, len(packfiles) == 6, "expected 6 packfiles in repository, got %d", len(packfiles))
+
+	packfiles = testRunList(t, env.gopts, "packs", "latest")
+	rtest.Assert(t, len(packfiles) == 2, "expected 2 packfiles in snapshot, got %d", len(packfiles))
+}

doc/view_repository.rst

@@ -30,7 +30,8 @@ The allowed types are (in alphabetic order):
 - :ref:`list_index`
 - :ref:`keys <list_keys_locks_packs>`
 - :ref:`locks <list_keys_locks_packs>`
-- :ref:`packs <list_keys_locks_packs>`
+- :ref:`packs<list_keys_locks_packs>`
+- :ref:`packs [snapshot ID]<list_keys_locks_packs>`
 - :ref:`list_snapshots`
 
 
@@ -160,6 +161,18 @@ Here is an example which lists all the packs in the repository:
     953e5381138bdc44da23740a83065809dd4021f45ce4e351b577dc4c07f81314
     75bca8556f47d16362e58e757ea89a34b28fb96aedcc314bea35d468e5cb665c
 
+If you want to list all packfiles which are part of a snapshot, use the command
+``list packs`` and attach the snapshot ID of the snapshot you want to see.
+
+.. code-block:: console
+
+    $ restic -r /srv/restic-repo list packs latest -q
+    ae92415f79c281330159ed590db2a973048c886aacfa4fabfa0eaac10b396b8f
+    dc25893d422a71af41aaaa843cd7121708cd88679bf3885f94a32900ac068e84
+
+This will give you the list of all packfiles, sorted in ID ascending order.
+
+
 .. _view-repository-objects:
 
 Inspecting repository objects