Improve usage, error, and debug messages

Author: Ben Morgan

add.go

@@ -19,7 +19,7 @@ func init() {
 }
 
 var addCmd = &cobra.Command{
-	Use:   "add <pkgfile...>",
+	Use:   "add PKGFILE ...",
 	Short: "Copy and add packages to the repository",
 	Long: `Add (and copy if necessary) the package file to the repository.
 

conf.go

@@ -70,11 +70,16 @@ var confCmd = &cobra.Command{
   configuration file. These can be created manually, or repoctl can
   create them for you.
 
-  Whether you already have a repository or not, creating a new config is
-  sufficient:
+  If you already have a repository, creating a new config is sufficient:
 
     repoctl conf new /path/to/repository/database.db.tar.gz
 
+  Otherwise, make sure to run
+
+    repoctl reset
+
+  afterwards.
+
   Repoctl supports multiple repository configuration through profiles.
   You can add a profile by editing the configuration file manually:
 
@@ -189,7 +194,7 @@ var confEditCmd = &cobra.Command{
 }
 
 var confNewCmd = &cobra.Command{
-	Use:   "new </path/to/repo/database>",
+	Use:   "new DBPATH",
 	Short: "Create a new configuration file",
 	Long: `Create a new initial configuration file.
 

down.go

@@ -40,7 +40,7 @@ func init() {
 }
 
 var downCmd = &cobra.Command{
-	Use:     "down [pkgname...]",
+	Use:     "down [PKGNAME ...]",
 	Aliases: []string{"download"},
 	Short:   "Download and extract tarballs from AUR",
 	Long: `Download and extract tarballs from AUR for given packages.
@@ -170,11 +170,11 @@ func downDependencies(packages []string) (aur.Packages, error) {
 		f.Close()
 	}
 	for _, u := range ups {
-		fmt.Fprintf(os.Stderr, "warning: unknown package %s\n", u)
+		fmt.Fprintf(os.Stderr, "Warning: unknown package %s\n", u)
 		iter := g.To(g.NodeWithName(u).ID())
 		for iter.Next() {
 			node := iter.Node().(*graph.Node)
-			fmt.Fprintf(os.Stderr, "         required by: %s\n", node.PkgName())
+			fmt.Fprintf(os.Stderr, "         Required by: %s\n", node.PkgName())
 		}
 	}
 	return aps, nil

list.go

@@ -53,7 +53,7 @@ func init() {
 }
 
 var listCmd = &cobra.Command{
-	Use:     "list [regex]",
+	Use:     "list [REGEX]",
 	Aliases: []string{"ls"},
 	Short:   "List packages that belong to the managed repository",
 	Long: `List packages that belong to the managed repository.

main.go

@@ -6,10 +6,12 @@ package main
 
 import (
 	"fmt"
+	"io"
 	"os"
 	"os/exec"
 
 	"github.com/cassava/repoctl/conf"
+	"github.com/cassava/repoctl/pacman"
 	"github.com/cassava/repoctl/repo"
 	"github.com/goulash/color"
 	"github.com/spf13/cobra"
@@ -67,8 +69,9 @@ packages from AUR.
 
 Note that in all of these commands, the following terminology is used:
 
-    pkgname: is the name of the package, e.g. pacman
-    pkgfile: is the path to a package file, e.g. pacman-3.5.3-i686.pkg.tar.xz
+  PKGNAME: is the name of the package, e.g. pacman
+  PKGFILE: is the path to a package file, e.g. pacman-3.5.3-i686.pkg.tar.xz
+  DBPATH:  is the (absolute) path to your repo database, e.g. /srv/sirius.db.tar.zst
 
 There are several places that repoctl reads its configuration from.
 If $REPOCTL_CONFIG is set, then only this path is loaded. Otherwise,
@@ -85,12 +88,35 @@ In most systems then, repoctl will read:
   /etc/xdg/repoctl/config.toml
   /home/you/.config/repoctl/config.toml
 
+---
+
+If you are new to repoctl, perform the following commands to get started:
+
+  repoctl conf new DBPATH  # Create a new configuration file
+  repoctl conf edit        # Edit the configuration file
+  repoctl reset            # Initialize the repository
+
+You can then continue by building and adding packages:
+
+  repoctl search QUERY
+  repoctl down -r PKGNAME
+  # cd PKGNAME && makepkg
+  repoctl add PKGFILE ...
+
+And by viewing the status of your repository:
+
+  repoctl status
+
 `,
 	PersistentPreRunE: func(cmd *cobra.Command, args []string) error {
 		// Prevent errors that we print being printed a second time by cobra.
 		cmd.SilenceErrors = true
 		cmd.SilenceUsage = true
 
+		if Conf.Debug {
+			pacman.DebugWriter = newDebugWriter(Term)
+		}
+
 		return nil
 	},
 }
@@ -140,6 +166,9 @@ func ProfileInit(cmd *cobra.Command, args []string) error {
 	if err != nil {
 		return fmt.Errorf("cannot load profile %q: %s", name, err)
 	}
+	if Conf.Debug {
+		Repo.Debug = newDebugWriter(Term)
+	}
 
 	// 4. Run pre-action if defined.
 	if Profile.PreAction != "" {
@@ -149,6 +178,26 @@ func ProfileInit(cmd *cobra.Command, args []string) error {
 	return nil
 }
 
+type debugWriter struct {
+	term *color.Colorizer
+	out  io.Writer
+}
+
+func newDebugWriter(term *color.Colorizer) *debugWriter {
+	if term == nil {
+		return nil
+	}
+
+	return &debugWriter{
+		term: term,
+		out:  os.Stderr,
+	}
+}
+
+func (w *debugWriter) Write(p []byte) (n int, err error) {
+	return w.term.Fprintf(w.out, "@.%s", p)
+}
+
 // ProfileTeardown should be used as the PostRunE part of every command
 // that needs to make use of the profile or the Repo.
 func ProfileTeardown(cmd *cobra.Command, args []string) error {

pacman/doc.go

@@ -4,3 +4,18 @@
 
 // Package pacman provides routines for dealing with Pacman packages.
 package pacman
+
+import (
+	"fmt"
+	"io"
+)
+
+// DebugWriter is used to write debugging information from this module.
+// If it is nil, then no debugging messages are printed.
+var DebugWriter io.Writer = nil
+
+func debugf(format string, obj ...interface{}) {
+	if DebugWriter != nil {
+		fmt.Fprintf(DebugWriter, format, obj...)
+	}
+}

pacman/read-db.go

@@ -44,9 +44,18 @@ func IsDatabaseLocked(dbpath string) bool {
 
 // ReadDatabase reads all the packages from a database file.
 func ReadDatabase(dbpath string) (Packages, error) {
+	debugf("Read database %s\n", dbpath)
+
 	var dr io.ReadCloser
 	var err error
 
+	if ex, err := osutil.FileExists(dbpath); !ex {
+		if err != nil {
+			return nil, fmt.Errorf("read database %s: %w", dbpath, err)
+		}
+		return nil, fmt.Errorf("read database %s: no such file", dbpath)
+	}
+
 	dr, err = archive.NewDecompressor(dbpath)
 	if err != nil {
 		return nil, fmt.Errorf("read database %s: %w", dbpath, err)

pacman/read-fs.go

@@ -93,7 +93,7 @@ func ReadEveryFileInDir(h errs.Handler, dirpath string) (Packages, error) {
 	dirpath = filepath.Clean(dirpath)
 	err := filepath.Walk(dirpath, func(filename string, info os.FileInfo, err error) error {
 		if err != nil {
-			return h(err)
+			return h(fmt.Errorf("read file %s: %w", filename, err))
 		}
 		if info.Mode().IsDir() {
 			if filename == dirpath {

pacman/read-pkg.go

@@ -19,15 +19,16 @@ import (
 // Read reads the package information from a pacman package
 // and returns it in the Package datatype.
 func Read(filename string) (*Package, error) {
+	debugf("Read package %s\n", filename)
 	bs, err := archive.ReadFileFromArchive(filename, ".PKGINFO")
 	if err != nil {
-		return nil, err
+		return nil, fmt.Errorf("read package %s: %w", filename, err)
 	}
 
 	r := bytes.NewReader(bs)
 	info, err := readFilePkgInfo(r)
 	if err != nil {
-		return nil, err
+		return nil, fmt.Errorf("read package %s: %w", filename, err)
 	}
 
 	info.Filename = filename

query.go

@@ -20,7 +20,7 @@ func init() {
 }
 
 var queryCmd = &cobra.Command{
-	Use:   "query [pkgname...]",
+	Use:   "query [PKGNAME ...]",
 	Short: "Query package information from AUR",
 	Long: `Query package information from AUR.
 
@@ -60,7 +60,7 @@ var queryCmd = &cobra.Command{
 				return err
 			}
 			for _, n := range nfe.Names {
-				fmt.Fprintf(os.Stderr, "warning: unknown package %s\n", n)
+				fmt.Fprintf(os.Stderr, "Warning: unknown package %s\n", n)
 			}
 		}