From ed20fa5ee7970fbfa2991d41fe5f9eebbcca88e8 Mon Sep 17 00:00:00 2001 From: Nick Craig-Wood Date: Sat, 6 Jan 2018 17:00:20 +0000 Subject: [PATCH] ls* commands: update docs and add defaults into options for lsf --- cmd/ls/ls.go | 7 +++- cmd/ls/lshelp/lshelp.go | 22 +++++++++++++ cmd/lsd/lsd.go | 5 +++ cmd/lsf/lsf.go | 73 +++++++++++++++++++++++++---------------- cmd/lsjson/lsjson.go | 3 +- cmd/lsl/lsl.go | 7 +++- 6 files changed, 86 insertions(+), 31 deletions(-) create mode 100644 cmd/ls/lshelp/lshelp.go diff --git a/cmd/ls/ls.go b/cmd/ls/ls.go index f0b47e35e..4c153d59d 100644 --- a/cmd/ls/ls.go +++ b/cmd/ls/ls.go @@ -4,6 +4,7 @@ import ( "os" "github.com/ncw/rclone/cmd" + "github.com/ncw/rclone/cmd/ls/lshelp" "github.com/ncw/rclone/fs" "github.com/spf13/cobra" ) @@ -14,7 +15,11 @@ func init() { var commandDefintion = &cobra.Command{ Use: "ls remote:path", - Short: `List all the objects in the path with size and path.`, + Short: `List the objects in the path with size and path.`, + Long: ` +Lists the objects in the source path to standard output in a human +readable format with size and path. Recurses by default. +` + lshelp.Help, Run: func(command *cobra.Command, args []string) { cmd.CheckArgs(1, 1, command, args) fsrc := cmd.NewFsSrc(args) diff --git a/cmd/ls/lshelp/lshelp.go b/cmd/ls/lshelp/lshelp.go new file mode 100644 index 000000000..8b713636b --- /dev/null +++ b/cmd/ls/lshelp/lshelp.go @@ -0,0 +1,22 @@ +package lshelp + +// Help describes the common help for all the list commands +var Help = ` +Any of the filtering options can be applied to this commmand. + +There are several related list commands + + * ` + "`ls`" + ` to list size and path of objects only + * ` + "`lsl`" + ` to list modification time, size and path of objects only + * ` + "`lsd`" + ` to list directories only + * ` + "`lsf`" + ` to list objects and directories in easy to parse format + * ` + "`lsjson`" + ` to list objects and directories in JSON format + +` + "`ls`,`lsl`,`lsd`" + ` are designed to be human readable. +` + "`lsf`" + ` is designed to be human and machine readable. +` + "`lsjson`" + ` is designed to be machine readable. + +Note that ` + "`ls`,`lsl`,`lsd`" + ` all recurse by default - use "--max-depth 1" to stop the recursion. + +The other list commands ` + "`lsf`,`lsjson`" + ` do not recurse by default - use "-R" to make them recurse. +` diff --git a/cmd/lsd/lsd.go b/cmd/lsd/lsd.go index e8d70f079..9c984f778 100644 --- a/cmd/lsd/lsd.go +++ b/cmd/lsd/lsd.go @@ -4,6 +4,7 @@ import ( "os" "github.com/ncw/rclone/cmd" + "github.com/ncw/rclone/cmd/ls/lshelp" "github.com/ncw/rclone/fs" "github.com/spf13/cobra" ) @@ -15,6 +16,10 @@ func init() { var commandDefintion = &cobra.Command{ Use: "lsd remote:path", Short: `List all directories/containers/buckets in the path.`, + Long: ` +Lists the directories in the source path to standard output. Recurses +by default. +` + lshelp.Help, Run: func(command *cobra.Command, args []string) { cmd.CheckArgs(1, 1, command, args) fsrc := cmd.NewFsSrc(args) diff --git a/cmd/lsf/lsf.go b/cmd/lsf/lsf.go index c3d22ce74..e9d98f841 100644 --- a/cmd/lsf/lsf.go +++ b/cmd/lsf/lsf.go @@ -6,6 +6,7 @@ import ( "os" "github.com/ncw/rclone/cmd" + "github.com/ncw/rclone/cmd/ls/lshelp" "github.com/ncw/rclone/fs" "github.com/pkg/errors" "github.com/spf13/cobra" @@ -21,15 +22,36 @@ var ( func init() { cmd.Root.AddCommand(commandDefintion) flags := commandDefintion.Flags() - flags.StringVarP(&format, "format", "F", "", "Output format.") - flags.StringVarP(&separator, "separator", "s", "", "Separator.") - flags.BoolVarP(&dirSlash, "dir-slash", "d", false, "Dir name contains slash one the end.") + flags.StringVarP(&format, "format", "F", "p", "Output format - see help for details") + flags.StringVarP(&separator, "separator", "s", ";", "Separator for the items in the format.") + flags.BoolVarP(&dirSlash, "dir-slash", "d", true, "Append a slash to directory names.") commandDefintion.Flags().BoolVarP(&recurse, "recursive", "R", false, "Recurse into the listing.") } var commandDefintion = &cobra.Command{ Use: "lsf remote:path", - Short: `List all the objects in the path with modification time, size and path in specific format: 'p' - path, 's' - size, 't' - modification time, ex. 'tsp'. Default output contains only path. If format is empty, dir-slash flag is always true.`, + Short: `List directories and objects in remote:path formatted for parsing`, + Long: ` +List the contents of the source path (directories and objects) to +standard output in a form which is easy to parse by scripts. By +default this will just be the names of the objects and directories, +one per line. The directories will have a / suffix. + +Use the --format option to control what gets listed. By default this +is just the path, but you can use these parameters to control the +output: + + p - path + s - size + t - modification time + +So if you wanted the path, size and modification time, you would use +--format "pst", or maybe --format "tsp" to put the path last. + +By default the separator is ";" this can be changed with the +--separator flag. Note that separators aren't escaped in the path so +putting it last is a good strategy. +` + lshelp.Help, Run: func(command *cobra.Command, args []string) { cmd.CheckArgs(1, 1, command, args) fsrc := cmd.NewFsSrc(args) @@ -39,37 +61,32 @@ var commandDefintion = &cobra.Command{ }, } -//Lsf lists all the objects in the path with modification time, size and path in specific format. +// Lsf lists all the objects in the path with modification time, size +// and path in specific format. func Lsf(fsrc fs.Fs, out io.Writer) error { + var list fs.ListFormat + list.SetSeparator(separator) + list.SetDirSlash(dirSlash) + + for _, char := range format { + switch char { + case 'p': + list.AddPath() + case 't': + list.AddModTime() + case 's': + list.AddSize() + default: + return errors.Errorf("Unknown format character %q", char) + } + } + return fs.Walk(fsrc, "", false, fs.ConfigMaxDepth(recurse), func(path string, entries fs.DirEntries, err error) error { if err != nil { fs.Stats.Error(err) fs.Errorf(path, "error listing: %v", err) return nil } - if format == "" { - format = "p" - dirSlash = true - } - if separator == "" { - separator = ";" - } - var list fs.ListFormat - list.SetSeparator(separator) - list.SetDirSlash(dirSlash) - - for _, char := range format { - switch char { - case 'p': - list.AddPath() - case 't': - list.AddModTime() - case 's': - list.AddSize() - default: - return errors.Wrap(err, "failed to parse format argument") - } - } for _, entry := range entries { fmt.Fprintln(out, fs.ListFormatted(&entry, &list)) } diff --git a/cmd/lsjson/lsjson.go b/cmd/lsjson/lsjson.go index 02427f7fb..30250e3e0 100644 --- a/cmd/lsjson/lsjson.go +++ b/cmd/lsjson/lsjson.go @@ -8,6 +8,7 @@ import ( "time" "github.com/ncw/rclone/cmd" + "github.com/ncw/rclone/cmd/ls/lshelp" "github.com/ncw/rclone/fs" "github.com/pkg/errors" "github.com/spf13/cobra" @@ -76,7 +77,7 @@ The time is in RFC3339 format with nanosecond precision. The whole output can be processed as a JSON blob, or alternatively it can be processed line by line as each item is written one to a line. -`, +` + lshelp.Help, Run: func(command *cobra.Command, args []string) { cmd.CheckArgs(1, 1, command, args) fsrc := cmd.NewFsSrc(args) diff --git a/cmd/lsl/lsl.go b/cmd/lsl/lsl.go index d572510d0..4d284310c 100644 --- a/cmd/lsl/lsl.go +++ b/cmd/lsl/lsl.go @@ -4,6 +4,7 @@ import ( "os" "github.com/ncw/rclone/cmd" + "github.com/ncw/rclone/cmd/ls/lshelp" "github.com/ncw/rclone/fs" "github.com/spf13/cobra" ) @@ -14,7 +15,11 @@ func init() { var commandDefintion = &cobra.Command{ Use: "lsl remote:path", - Short: `List all the objects path with modification time, size and path.`, + Short: `List the objects in path with modification time, size and path.`, + Long: ` +Lists the objects in the source path to standard output in a human +readable format with modification time, size and path. Recurses by default. +` + lshelp.Help, Run: func(command *cobra.Command, args []string) { cmd.CheckArgs(1, 1, command, args) fsrc := cmd.NewFsSrc(args)