ls* commands: update docs and add defaults into options for lsf

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)

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.
+`

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)

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(&format, "format", "F", "p", "Output format - see  help for details")
-	flags.StringVarP(&separator, "separator", "s", "", "Separator.")
+	flags.StringVarP(&separator, "separator", "s", ";", "Separator for the items in the format.")
-	flags.BoolVarP(&dirSlash, "dir-slash", "d", false, "Dir name contains slash one the end.")
+	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,21 +61,9 @@ 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 {
-	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)
@@ -67,9 +77,16 @@ func Lsf(fsrc fs.Fs, out io.Writer) error {
 		case 's':
 			list.AddSize()
 		default:
-				return errors.Wrap(err, "failed to parse format argument")
+			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
+		}
 		for _, entry := range entries {
 			fmt.Fprintln(out, fs.ListFormatted(&entry, &list))
 		}

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)

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)