praefect: Add text clarifying what list-untracked-repositories output signfiies

list-untracked-repositories currently outputs json rows for repositories
that exist on disk but are untracked by the database. It's unclear what
these rows are. Add helper text to signal to the user what these rows
mean.

Changelog: changed

2 files changed, 18 insertions, 8 deletions

diff --git a/cmd/praefect/subcmd_list_untracked_repositories.go b/cmd/praefect/subcmd_list_untracked_repositories.go
index 1339cecc2..39d6cd41c 100644
--- a/cmd/praefect/subcmd_list_untracked_repositories.go
+++ b/cmd/praefect/subcmd_list_untracked_repositories.go
@@ -83,10 +83,11 @@ func (cmd listUntrackedRepositories) Exec(flags *flag.FlagSet, cfg config.Config
 
 	walker := repocleaner.NewWalker(nodeSet.Connections(), 16)
 	reporter := reportUntrackedRepositories{
-		ctx:       ctx,
-		checker:   datastore.NewStorageCleanup(db),
-		delimiter: cmd.delimiter,
-		out:       cmd.out,
+		ctx:         ctx,
+		checker:     datastore.NewStorageCleanup(db),
+		delimiter:   cmd.delimiter,
+		out:         cmd.out,
+		printHeader: true,
 	}
 	for _, vs := range cfg.VirtualStorages {
 		for _, node := range vs.Nodes {
@@ -126,10 +127,11 @@ func dialGitalyStorages(ctx context.Context, cfg config.Config, timeout time.Dur
 }
 
 type reportUntrackedRepositories struct {
-	ctx       context.Context
-	checker   *datastore.StorageCleanup
-	out       io.Writer
-	delimiter string
+	ctx         context.Context
+	checker     *datastore.StorageCleanup
+	out         io.Writer
+	delimiter   string
+	printHeader bool
 }
 
 // Report method accepts a list of repositories, checks if they exist in the praefect database
@@ -145,6 +147,13 @@ func (r *reportUntrackedRepositories) Report(virtualStorage, storage string, rep
 		return fmt.Errorf("existence check: %w", err)
 	}
 
+	if len(missing) > 0 && r.printHeader {
+		if _, err := fmt.Fprintf(r.out, "The following repositories were found on disk, but missing from the tracking database:\n"); err != nil {
+			return fmt.Errorf("write header to output: %w", err)
+		}
+		r.printHeader = false
+	}
+
 	for _, replicaPath := range missing {
 		d, err := json.Marshal(map[string]string{
 			"virtual_storage": virtualStorage,
diff --git a/cmd/praefect/subcmd_list_untracked_repositories_test.go b/cmd/praefect/subcmd_list_untracked_repositories_test.go
index 965ad3a8f..a18f17ea6 100644
--- a/cmd/praefect/subcmd_list_untracked_repositories_test.go
+++ b/cmd/praefect/subcmd_list_untracked_repositories_test.go
@@ -109,6 +109,7 @@ func TestListUntrackedRepositories_Exec(t *testing.T) {
 	require.NoError(t, cmd.Exec(flag.NewFlagSet("", flag.PanicOnError), conf))
 
 	exp := []string{
+		"The following repositories were found on disk, but missing from the tracking database:",
 		fmt.Sprintf(`{"relative_path":%q,"storage":"gitaly-1","virtual_storage":"praefect"}`, repo1.RelativePath),
 		fmt.Sprintf(`{"relative_path":%q,"storage":"gitaly-1","virtual_storage":"praefect"}`, repo2.RelativePath),
 		fmt.Sprintf(`{"relative_path":%q,"storage":"gitaly-2","virtual_storage":"praefect"}`, repo3.RelativePath),