align channel and user cache flags and document them

cmd/slackdump/internal/cfg/cfg.go

@@ -87,6 +87,6 @@ func SetBaseFlags(fs *flag.FlagSet, mask FlagMask) {
 	}
 	if mask&OmitUserCacheFlag == 0 {
 		fs.BoolVar(&SlackConfig.UserCache.Disabled, "no-user-cache", false, "disable user cache")
-		fs.DurationVar(&SlackConfig.UserCache.MaxAge, "user-cache-age", slackdump.DefOptions.UserCache.MaxAge, "maximum user cache age")
+		fs.DurationVar(&SlackConfig.UserCache.Retention, "user-cache-retention", slackdump.DefOptions.UserCache.Retention, "user cache retention duration.  After this time, the cache is considered stale and will be refreshed.")
 	}
 }

cmd/slackdump/internal/list/channels.go

@@ -2,6 +2,7 @@ package list
 
 import (
 	"context"
+	"fmt"
 	"runtime/trace"
 	"time"
 
@@ -19,7 +20,7 @@ var CmdListChannels = &base.Command{
 	PrintFlags: true,
 	FlagMask:   cfg.OmitDownloadFlag,
 	Short:      "list workspace channels",
-	Long: `
+	Long: fmt.Sprintf(`
 # List Channels Command
 
 Lists all visible channels for the currently logged in user.  The list
@@ -28,14 +29,17 @@ including archived ones.
 
 Please note that it may take a while to retrieve all channels, if your
 workspace has lots of them.
-` + sectListFormat,
+
+The channels are cached, and the cache is valid for %s.  Use the -no-chan-cache
+and -chan-cache-retention flags to control the cache behavior.
+`+sectListFormat, chanCacheOpts.Retention),
 
 	RequireAuth: true,
 }
 
 func init() {
 	CmdListChannels.Flag.BoolVar(&chanCacheOpts.Disabled, "no-chan-cache", chanCacheOpts.Disabled, "disable channel cache")
-	CmdListChannels.Flag.DurationVar(&chanCacheOpts.MaxAge, "chan-cache-age", chanCacheOpts.MaxAge, "channel cache retention time")
+	CmdListChannels.Flag.DurationVar(&chanCacheOpts.Retention, "chan-cache-retention", chanCacheOpts.Retention, "channel cache retention time.  After this time, the cache is considered stale and will be refreshed.")
 }
 
 func listChannels(ctx context.Context, cmd *base.Command, args []string) error {
@@ -73,9 +77,9 @@ func listChannels(ctx context.Context, cmd *base.Command, args []string) error {
 }
 
 var chanCacheOpts = slackdump.CacheConfig{
-	Disabled: false,
-	MaxAge:   20 * time.Minute,
-	Filename: "channels.json",
+	Disabled:  false,
+	Retention: 20 * time.Minute,
+	Filename:  "channels.json",
 }
 
 func maybeLoadChanCache(cacheDir string, teamID string) (types.Channels, bool) {
@@ -87,7 +91,7 @@ func maybeLoadChanCache(cacheDir string, teamID string) (types.Channels, bool) {
 	if err != nil {
 		return nil, false
 	}
-	cc, err := m.LoadChannels(teamID, chanCacheOpts.MaxAge)
+	cc, err := m.LoadChannels(teamID, chanCacheOpts.Retention)
 	if err != nil {
 		return nil, false
 	}

cmd/slackdump/internal/list/doc.go

@@ -11,5 +11,5 @@ var (
 ## Listing format
 
 By default, the data is being output in TEXT format.  You can choose the listing
-format by specifying "-type X" flag, where X is one of: ` + fmt.Sprint(format.All())
+format by specifying "-format X" flag, where X is one of: ` + fmt.Sprint(format.All())
 )

cmd/slackdump/internal/list/list.go

@@ -25,7 +25,7 @@ import (
 var CmdList = &base.Command{
 	UsageLine: "slackdump list",
 	Short:     "list users or channels",
-	Long: `
+	Long: fmt.Sprintf(`
 # List Command
 
 List lists users or channels for the Slack Workspace.  It may take a while on a
@@ -36,16 +36,15 @@ The data is dumped to a JSON file in the base directory, and additionally,
 printed on the screen in the requested format.
 
 - To disable saving data to a file, use '-no-save' flag.
-- To disable printing to the screen, use '-q' (quiet) flag.
+- To disable printing on the screen, use '-q' (quiet) flag.
 
 ## Caching
-Channel and User data is cached.  User cache lasts for 4 hours, and channel
-cache — for 20 minutes.  This is to prevent fetching the same data for every
-execution, which could be slow for the large workspaces.
+Channel and User data is cached.  Default user cache retention is %s, and
+channel cache — %s.  This is to speed up consecutive runs of the command.
 
-The caching can be turned off by using common flags "-no-user-cache" and
-"-no-channel-cache".
-`,
+The caching can be turned off by using flags "-no-user-cache" and
+"-no-chan-cache".
+`, cfg.SlackConfig.UserCache.Retention, chanCacheOpts.Retention),
 	Commands: []*base.Command{
 		CmdListUsers,
 		CmdListChannels,

cmd/slackdump/internal/list/users.go

@@ -2,6 +2,7 @@ package list
 
 import (
 	"context"
+	"fmt"
 
 	"github.com/rusq/slackdump/v2"
 	"github.com/rusq/slackdump/v2/cmd/slackdump/internal/cfg"
@@ -15,11 +16,15 @@ var CmdListUsers = &base.Command{
 	PrintFlags: true,
 	FlagMask:   cfg.OmitDownloadFlag,
 	Short:      "list workspace users",
-	Long: `
+	Long: fmt.Sprintf(`
 # List Users
 
-List users lists workspace users in the desired format.` +
-		sectListFormat,
+List users lists workspace users in the desired format.
+
+Users are cached for %v.  To disable caching, use '-no-user-cache' flag and
+'-user-cache-retention' flag to control the caching behaviour.
+`+
+		sectListFormat, cfg.SlackConfig.UserCache.Retention),
 	RequireAuth: true,
 }
 

cmd/slackdump/internal/v1/main.go

@@ -366,7 +366,7 @@ func parseCmdLine(args []string) (params, error) {
 	// - cache controls
 	fs.StringVar(&p.appCfg.SlackConfig.CacheDir, "cache-dir", cfg.CacheDir(), "slackdump cache directory")
 	fs.StringVar(&p.appCfg.SlackConfig.UserCache.Filename, "user-cache-file", slackdump.DefOptions.UserCache.Filename, "user cache file`name`.")
-	fs.DurationVar(&p.appCfg.SlackConfig.UserCache.MaxAge, "user-cache-age", slackdump.DefOptions.UserCache.MaxAge, "user cache lifetime `duration`. Set this to 0 to disable cache.")
+	fs.DurationVar(&p.appCfg.SlackConfig.UserCache.Retention, "user-cache-age", slackdump.DefOptions.UserCache.Retention, "user cache lifetime `duration`. Set this to 0 to disable cache.")
 	fs.BoolVar(&p.appCfg.SlackConfig.UserCache.Disabled, "no-user-cache", slackdump.DefOptions.UserCache.Disabled, "skip fetching users")
 
 	// - time frame options

cmd/slackdump/main.go

@@ -304,6 +304,8 @@ func whatDo(w io.Writer) (choice, error) {
 	return choice(ans), nil
 }
 
+// isInteractive returns true if the program is running in the interactive
+// terminal.
 func isInteractive() bool {
 	return term.IsTerminal(int(os.Stdout.Fd())) && term.IsTerminal(int(os.Stdin.Fd())) && os.Getenv("TERM") != "dumb"
 }

config.go

@@ -27,9 +27,9 @@ type Config struct {
 
 // CacheConfig represents the options for the cache.
 type CacheConfig struct {
-	Filename string
-	MaxAge   time.Duration
-	Disabled bool
+	Filename  string
+	Retention time.Duration
+	Disabled  bool
 }
 
 type Limits struct {
@@ -89,7 +89,7 @@ var DefOptions = Config{
 		},
 	},
 	DumpFiles:    false,
-	UserCache:    CacheConfig{Filename: "users.cache", MaxAge: 4 * time.Hour},
+	UserCache:    CacheConfig{Filename: "users.cache", Retention: 4 * time.Hour},
 	CacheDir:     "",  // default cache dir
 	BaseLocation: ".", // default location is the current directory
 	Logfile:      "",  // empty, means STDERR

users.go

@@ -30,7 +30,7 @@ func (s *Session) GetUsers(ctx context.Context) (types.Users, error) {
 		return nil, err
 	}
 
-	users, err := m.LoadUsers(s.wspInfo.TeamID, s.cfg.UserCache.MaxAge)
+	users, err := m.LoadUsers(s.wspInfo.TeamID, s.cfg.UserCache.Retention)
 	if err != nil {
 		s.log.Println("caching users")
 		users, err = s.fetchUsers(ctx)

users_test.go

@@ -137,7 +137,7 @@ func TestSession_GetUsers(t *testing.T) {
 		{
 			"everything goes as planned",
 			fields{options: Config{
-				UserCache: CacheConfig{Filename: gimmeTempFile(t, dir), MaxAge: 5 * time.Hour},
+				UserCache: CacheConfig{Filename: gimmeTempFile(t, dir), Retention: 5 * time.Hour},
 				Limits: Limits{
 					Tier2: TierLimits{Burst: 1},
 					Tier3: TierLimits{Burst: 1},
@@ -153,7 +153,7 @@ func TestSession_GetUsers(t *testing.T) {
 		{
 			"loaded from cache",
 			fields{options: Config{
-				UserCache: CacheConfig{Filename: gimmeTempFileWithUsers(t, dir), MaxAge: 5 * time.Hour},
+				UserCache: CacheConfig{Filename: gimmeTempFileWithUsers(t, dir), Retention: 5 * time.Hour},
 				Limits: Limits{
 					Tier2: TierLimits{Burst: 1},
 					Tier3: TierLimits{Burst: 1},