From c2615d34810a8de3e472d4fd102a5153abb30d5c Mon Sep 17 00:00:00 2001 From: Matt Bell Date: Sat, 8 Nov 2014 01:02:22 -0800 Subject: [PATCH] core/commands2: Added descriptions for all the existing commands --- core/commands2/bootstrap.go | 43 ++++++++++++++++--------------- core/commands2/cat.go | 13 +++++----- core/commands2/commands.go | 8 +++--- core/commands2/config.go | 32 +++++++++++++---------- core/commands2/diag.go | 16 +++++------- core/commands2/log.go | 22 ++++++++-------- core/commands2/ls.go | 21 ++++++--------- core/commands2/mount_unix.go | 21 ++++++++------- core/commands2/mount_windows.go | 4 ++- core/commands2/name.go | 13 +++------- core/commands2/pin.go | 45 +++++++++++++++------------------ core/commands2/publish.go | 17 ++++++------- core/commands2/resolve.go | 13 ++++------ core/commands2/root.go | 25 +++++++++--------- core/commands2/update.go | 23 ++++++++++------- core/commands2/version.go | 13 +++++----- 16 files changed, 160 insertions(+), 169 deletions(-) diff --git a/core/commands2/bootstrap.go b/core/commands2/bootstrap.go index 2a5782f14..26b15e809 100644 --- a/core/commands2/bootstrap.go +++ b/core/commands2/bootstrap.go @@ -10,26 +10,19 @@ import ( cmds "github.com/jbenet/go-ipfs/commands" config "github.com/jbenet/go-ipfs/config" - //peer "github.com/jbenet/go-ipfs/peer" - //u "github.com/jbenet/go-ipfs/util" ) type BootstrapOutput struct { Peers []*config.BootstrapPeer } +var peerOptionDesc = "A peer to add to the bootstrap list (in the format '/')" + var bootstrapCmd = &cmds.Command{ - Help: `ipfs bootstrap - show, or manipulate bootstrap node addresses - -Running 'ipfs bootstrap' with no arguments will run 'ipfs bootstrap list'. - -Commands: - - list Show the boostrap list. - add
Add a node's address to the bootstrap list. - remove
Remove an address from the bootstrap list. - + Description: "Show or edit the list of bootstrap peers", + Help: `Running 'ipfs bootstrap' with no arguments will run 'ipfs bootstrap list'. ` + bootstrapSecurityWarning, + Run: bootstrapListCmd.Run, Marshallers: bootstrapListCmd.Marshallers, Subcommands: map[string]*cmds.Command{ @@ -40,11 +33,14 @@ Commands: } var bootstrapAddCmd = &cmds.Command{ - Arguments: []cmds.Argument{ - cmds.Argument{"peer", cmds.ArgString, true, true}, - }, - Help: `ipfs bootstrap add - add addresses to the bootstrap list + Description: "Add peers to the bootstrap list", + Help: `Outputs a list of peers that were added (that weren't already +in the bootstrap list). ` + bootstrapSecurityWarning, + + Arguments: []cmds.Argument{ + cmds.Argument{"peer", cmds.ArgString, true, true, peerOptionDesc}, + }, Run: func(res cmds.Response, req cmds.Request) { input, err := bootstrapInputToPeers(req.Arguments()) if err != nil { @@ -81,11 +77,13 @@ var bootstrapAddCmd = &cmds.Command{ } var bootstrapRemoveCmd = &cmds.Command{ - Arguments: []cmds.Argument{ - cmds.Argument{"peer", cmds.ArgString, true, true}, - }, - Help: `ipfs bootstrap remove - remove addresses from the bootstrap list + Description: "Removes peers from the bootstrap list", + Help: `Outputs the list of peers that were removed. ` + bootstrapSecurityWarning, + + Arguments: []cmds.Argument{ + cmds.Argument{"peer", cmds.ArgString, true, true, peerOptionDesc}, + }, Run: func(res cmds.Response, req cmds.Request) { input, err := bootstrapInputToPeers(req.Arguments()) if err != nil { @@ -122,7 +120,10 @@ var bootstrapRemoveCmd = &cmds.Command{ } var bootstrapListCmd = &cmds.Command{ - Help: "ipfs bootstrap list - Show addresses in the bootstrap list", + Description: "Lists peers in the bootstrap list", + Help: `Peers are output in the format '/'. +`, + Run: func(res cmds.Response, req cmds.Request) { peers := req.Context().Config.Bootstrap res.SetOutput(&BootstrapOutput{peers}) diff --git a/core/commands2/cat.go b/core/commands2/cat.go index 62f67b91d..7acfe5435 100644 --- a/core/commands2/cat.go +++ b/core/commands2/cat.go @@ -10,14 +10,15 @@ import ( ) var catCmd = &cmds.Command{ - Arguments: []cmds.Argument{ - cmds.Argument{"object", cmds.ArgString, true, true}, - }, - Help: `ipfs cat - Show ipfs object data. - - Retrieves the object named by and outputs the data + Description: "Show IPFS object data", + Help: `Retrieves the object named by and outputs the data it contains. `, + + Arguments: []cmds.Argument{ + cmds.Argument{"ipfs-path", cmds.ArgString, true, true, + "The path to the IPFS object(s) to be outputted"}, + }, Run: func(res cmds.Response, req cmds.Request) { node := req.Context().Node readers := make([]io.Reader, 0, len(req.Arguments())) diff --git a/core/commands2/commands.go b/core/commands2/commands.go index f1d7f4fc6..6a5ab653d 100644 --- a/core/commands2/commands.go +++ b/core/commands2/commands.go @@ -13,12 +13,10 @@ type Command struct { } var commandsCmd = &cmds.Command{ - // TODO UsageLine: "commands", - // TODO Short: "List all available commands.", - Help: `ipfs commands - List all available commands. + Description: "List all available commands.", + Help: `Lists all available commands (and subcommands) and exits. +`, - Lists all available commands (and sub-commands) and exits. - `, Run: func(res cmds.Response, req cmds.Request) { root := outputCommand("ipfs", Root) res.SetOutput(&root) diff --git a/core/commands2/config.go b/core/commands2/config.go index 1eaf2332d..e0583b4ca 100644 --- a/core/commands2/config.go +++ b/core/commands2/config.go @@ -18,18 +18,8 @@ type ConfigField struct { } var configCmd = &cmds.Command{ - Arguments: []cmds.Argument{ - cmds.Argument{"key", cmds.ArgString, true, false}, - cmds.Argument{"value", cmds.ArgString, false, false}, - }, - Help: `ipfs config [value] - Get/Set ipfs config values. - - ipfs config - Get value of - ipfs config - Set value of to - ipfs config show - Show config file - ipfs config edit - Edit config file in $EDITOR - -Examples: + Description: "Get/set IPFS config values", + Help: `Examples: Get the value of the 'datastore.path' key: @@ -38,8 +28,14 @@ Examples: Set the value of the 'datastore.path' key: ipfs config datastore.path ~/.go-ipfs/datastore - `, + + Arguments: []cmds.Argument{ + cmds.Argument{"key", cmds.ArgString, true, false, + "The key of the config entry (e.g. \"Addresses.API\")"}, + cmds.Argument{"value", cmds.ArgString, false, false, + "The value to set the config entry to"}, + }, Run: func(res cmds.Response, req cmds.Request) { args := req.Arguments() @@ -110,6 +106,11 @@ Examples: } var configShowCmd = &cmds.Command{ + Description: "Outputs the content of the config file", + Help: `WARNING: Your private key is stored in the config file, and it will be +included in the output of this command. +`, + Run: func(res cmds.Response, req cmds.Request) { filename, err := config.Filename(req.Context().ConfigRoot) if err != nil { @@ -128,6 +129,11 @@ var configShowCmd = &cmds.Command{ } var configEditCmd = &cmds.Command{ + Description: "Opens the config file for editing in $EDITOR", + Help: `To use 'ipfs config edit', you must have the $EDITOR environment +variable set to your preferred text editor. +`, + Run: func(res cmds.Response, req cmds.Request) { filename, err := config.Filename(req.Context().ConfigRoot) if err != nil { diff --git a/core/commands2/diag.go b/core/commands2/diag.go index 9be4eb8d5..ef1abf150 100644 --- a/core/commands2/diag.go +++ b/core/commands2/diag.go @@ -28,24 +28,20 @@ type DiagnosticOutput struct { } var diagCmd = &cmds.Command{ - Help: `ipfs diag - Generate diagnostic reports. + Description: "Generates diagnostic reports", - ipfs diag net - Generate a network diagnostic report. - `, Subcommands: map[string]*cmds.Command{ "net": diagNetCmd, }, } var diagNetCmd = &cmds.Command{ - // TODO UsageLine: "net-diag", - // TODO Short: "Generate a diagnostics report", - Help: `ipfs diag net - Generate a network diagnostics report. - - Sends out a message to each node in the network recursively - requesting a listing of data about them including number of - connected peers and latencies between them. + Description: "Generates a network diagnostics report", + Help: `Sends out a message to each node in the network recursively +requesting a listing of data about them including number of +connected peers and latencies between them. `, + Run: func(res cmds.Response, req cmds.Request) { n := req.Context().Node diff --git a/core/commands2/log.go b/core/commands2/log.go index 510085c85..742aab526 100644 --- a/core/commands2/log.go +++ b/core/commands2/log.go @@ -8,19 +8,17 @@ import ( ) var logCmd = &cmds.Command{ - Arguments: []cmds.Argument{ - cmds.Argument{"subsystem", cmds.ArgString, true, false}, - cmds.Argument{"level", cmds.ArgString, true, false}, - }, - // TODO UsageLine: "log ", - // TODO Short: "switch logging levels of a running daemon", - Help: `ipfs log - switch logging levels of a running daemon - - is a the subsystem logging identifier. Use * for all subsystems. - is one of: debug, info, notice, warning, error, critical - -ipfs log is a utility command used to change the logging output of a running daemon. + Description: "Change the logging level", + Help: `'ipfs log' is a utility command used to change the logging +output of a running daemon. `, + + Arguments: []cmds.Argument{ + cmds.Argument{"subsystem", cmds.ArgString, true, false, + "the subsystem logging identifier. Use * for all subsystems."}, + cmds.Argument{"level", cmds.ArgString, true, false, + "one of: debug, info, notice, warning, error, critical"}, + }, Run: func(res cmds.Response, req cmds.Request) { args := req.Arguments() if err := u.SetLogLevel(args[0].(string), args[1].(string)); err != nil { diff --git a/core/commands2/ls.go b/core/commands2/ls.go index 569bfde65..c94e48e3d 100644 --- a/core/commands2/ls.go +++ b/core/commands2/ls.go @@ -23,20 +23,15 @@ type LsOutput struct { } var lsCmd = &cmds.Command{ - Arguments: []cmds.Argument{ - cmds.Argument{"object", cmds.ArgString, false, true}, - }, - // TODO UsageLine: "ls", - // TODO Short: "List links from an object.", - // TODO docs read ipfs-path. argument says option. which? - Help: `ipfs ls - List links from an object. - - Retrieves the object named by and displays the links - it contains, with the following format: - - - + Description: "List links from an object.", + Help: `Retrieves the object named by and displays the links +it contains. `, + + Arguments: []cmds.Argument{ + cmds.Argument{"ipfs-path", cmds.ArgString, false, true, + "The path to the IPFS object(s) to list links from"}, + }, Run: func(res cmds.Response, req cmds.Request) { node := req.Context().Node diff --git a/core/commands2/mount_unix.go b/core/commands2/mount_unix.go index a7d894d0d..2946459b0 100644 --- a/core/commands2/mount_unix.go +++ b/core/commands2/mount_unix.go @@ -17,25 +17,24 @@ import ( const mountTimeout = time.Second var mountCmd = &cmds.Command{ - Arguments: []cmds.Argument{ - cmds.Argument{Name: "os-path", Type: cmds.ArgString, Required: false, Variadic: false}, - }, + Description: "Mounts IPFS to the filesystem (read-only)", + Help: `Mount ipfs at a read-only mountpoint on the OS. All ipfs objects +will be accessible under that directory. Note that the root will +not be listable, as it is virtual. Accessing known paths directly. +`, + Options: []cmds.Option{ // TODO text: specify a mountpoint for ipfs // TODO longform - cmds.Option{[]string{"f"}, cmds.String}, + cmds.Option{[]string{"f"}, cmds.String, + "The path where IPFS should be mounted (default is '/ipfs')"}, // TODO text: specify a mountpoint for ipns // TODO longform - cmds.Option{[]string{"n"}, cmds.String}, + cmds.Option{[]string{"n"}, cmds.String, + "The path where IPNS should be mounted (default is '/ipns')"}, }, - Help: `ipfs mount - Mount an ipfs read-only mountpoint. - - Mount ipfs at a read-only mountpoint on the OS. All ipfs objects - will be accessible under that directory. Note that the root will - not be listable, as it is virtual. Accessing known paths directly. -`, Run: func(res cmds.Response, req cmds.Request) { ctx := req.Context() diff --git a/core/commands2/mount_windows.go b/core/commands2/mount_windows.go index 2660605c2..278192c6d 100644 --- a/core/commands2/mount_windows.go +++ b/core/commands2/mount_windows.go @@ -7,7 +7,9 @@ import ( ) var ipfsMount = &cmds.Command{ - Help: `Not yet implemented on Windows.`, + Description: "Not yet implemented on Windows", + Help: `Not yet implemented on Windows. :(`, + Run: func(res cmds.Response, req cmds.Request) { res.SetError(errors.New("Mount isn't compatible with Windows yet"), cmds.ErrNormal) }, diff --git a/core/commands2/name.go b/core/commands2/name.go index 7066641f8..33971d9ca 100644 --- a/core/commands2/name.go +++ b/core/commands2/name.go @@ -8,14 +8,8 @@ type IpnsEntry struct { } var nameCmd = &cmds.Command{ - // TODO UsageLine: "name [publish | resolve]", - // TODO Short: "ipfs namespace (ipns) tool", - Help: `ipfs name - Get/Set ipfs config values. - - ipfs name publish [] - Assign the to - ipfs name resolve [] - Resolve the value of - -IPNS is a PKI namespace, where names are the hashes of public keys, and + Description: "IPFS namespace (IPNS) tool", + Help: `IPNS is a PKI namespace, where names are the hashes of public keys, and the private key enables publishing new (signed) values. In both publish and resolve, the default value of is your own identity public key. @@ -37,12 +31,13 @@ Resolve the value of your identity: > ipfs name resolve QmatmE9msSfkKxoffpHwNLNKgwZG8eT9Bud6YoPab52vpy -Resolve te value of another name: +Resolve the value of another name: > ipfs name resolve QmbCMUZw6JFeZ7Wp9jkzbye3Fzp2GGcPgC3nmeUjfVF87n QmatmE9msSfkKxoffpHwNLNKgwZG8eT9Bud6YoPab52vpy `, + Subcommands: map[string]*cmds.Command{ "publish": publishCmd, "resolve": resolveCmd, diff --git a/core/commands2/pin.go b/core/commands2/pin.go index 2852c5b9f..076d252c8 100644 --- a/core/commands2/pin.go +++ b/core/commands2/pin.go @@ -10,10 +10,8 @@ import ( ) var pinCmd = &cmds.Command{ - // TODO UsageLine: "pin", - // TODO Short: "", - Help: `ipfs pin [add|rm] - object pinning commands - `, + Description: "Keeps objects stored locally", + Subcommands: map[string]*cmds.Command{ "add": addPinCmd, "rm": rmPinCmd, @@ -21,19 +19,18 @@ var pinCmd = &cmds.Command{ } var addPinCmd = &cmds.Command{ - // TODO UsageLine: "add", - // TODO Short: "pin an ipfs object to local storage.", - Help: `ipfs pin add - pin ipfs object to local storage. - - Retrieves the object named by and stores it locally - on disk. + Description: "Pins objects to local storage", + Help: `Keeps the object(s) named by in local storage. If the object +isn't already being stored, IPFS retrieves it. `, - Options: []cmds.Option{ - cmds.Option{[]string{"recursive", "r"}, cmds.Bool}, - cmds.Option{[]string{"depth", "d"}, cmds.Uint}, - }, + Arguments: []cmds.Argument{ - cmds.Argument{"object", cmds.ArgString, true, true}, + cmds.Argument{"ipfs-path", cmds.ArgString, true, true, + "Path to object(s) to be pinned"}, + }, + Options: []cmds.Option{ + cmds.Option{[]string{"recursive", "r"}, cmds.Bool, + "Recursively pin the object linked to by the specified object(s)"}, }, Run: func(res cmds.Response, req cmds.Request) { n := req.Context().Node @@ -58,18 +55,18 @@ var addPinCmd = &cmds.Command{ } var rmPinCmd = &cmds.Command{ - // TODO UsageLine: "rm", - // TODO Short: "unpin an ipfs object from local storage.", - Help: `ipfs pin rm - unpin ipfs object from local storage. - - Removes the pin from the given object allowing it to be garbage + Description: "Unpin an object from local storage", + Help: `Removes the pin from the given object allowing it to be garbage collected if needed. `, - Options: []cmds.Option{ - cmds.Option{[]string{"recursive", "r"}, cmds.Bool}, - }, + Arguments: []cmds.Argument{ - cmds.Argument{"object", cmds.ArgString, true, true}, + cmds.Argument{"ipfs-path", cmds.ArgString, true, true, + "Path to object(s) to be unpinned"}, + }, + Options: []cmds.Option{ + cmds.Option{[]string{"recursive", "r"}, cmds.Bool, + "Recursively unpin the object linked to by the specified object(s)"}, }, Run: func(res cmds.Response, req cmds.Request) { n := req.Context().Node diff --git a/core/commands2/publish.go b/core/commands2/publish.go index f442b3636..59c6f9072 100644 --- a/core/commands2/publish.go +++ b/core/commands2/publish.go @@ -14,13 +14,9 @@ import ( var errNotOnline = errors.New("This command must be run in online mode. Try running 'ipfs daemon' first.") var publishCmd = &cmds.Command{ - // TODO UsageLine: "publish", - // TODO Short: "publish a to ipns.", - Help: `ipfs name publish [] - publish a to ipns. - -IPNS is a PKI namespace, where names are the hashes of public keys, and -the private key enables publishing new (signed) values. In publish, the -default value of is your own identity public key. + Description: "Publish an object to IPNS", + Help: `IPNS is a PKI namespace, where names are the hashes of public keys, and +the private key enables publishing new (signed) values. Examples: @@ -35,9 +31,12 @@ Publish a to another public key: published name QmbCMUZw6JFeZ7Wp9jkzbye3Fzp2GGcPgC3nmeUjfVF87n to QmatmE9msSfkKxoffpHwNLNKgwZG8eT9Bud6YoPab52vpy `, + Arguments: []cmds.Argument{ - cmds.Argument{"name", cmds.ArgString, false, false}, - cmds.Argument{"object", cmds.ArgString, true, false}, + cmds.Argument{"name", cmds.ArgString, false, false, + "The IPNS name to publish to. Defaults to your node's peerID"}, + cmds.Argument{"ipfs-path", cmds.ArgString, true, false, + "IPFS path of the obejct to be published at "}, }, Run: func(res cmds.Response, req cmds.Request) { n := req.Context().Node diff --git a/core/commands2/resolve.go b/core/commands2/resolve.go index d04d0a0bf..ecb6e276e 100644 --- a/core/commands2/resolve.go +++ b/core/commands2/resolve.go @@ -12,13 +12,9 @@ type ResolveOutput struct { } var resolveCmd = &cmds.Command{ - // TODO UsageLine: "resolve", - // TODO Short: "resolve an ipns name to a ", - Help: `ipfs name resolve [] - Resolve an ipns name to a . - -IPNS is a PKI namespace, where names are the hashes of public keys, and -the private key enables publishing new (signed) values. In resolve, the -default value of is your own identity public key. + Description: "Gets the value currently published at an IPNS name", + Help: `IPNS is a PKI namespace, where names are the hashes of public keys, and +the private key enables publishing new (signed) values. Examples: @@ -36,7 +32,8 @@ Resolve te value of another name: `, Arguments: []cmds.Argument{ - cmds.Argument{"name", cmds.ArgString, false, true}, + cmds.Argument{"name", cmds.ArgString, false, true, + "The IPNS name to resolve. Defaults to your node's peerID."}, }, Run: func(res cmds.Response, req cmds.Request) { diff --git a/core/commands2/root.go b/core/commands2/root.go index f41b54b86..f6a2a1898 100644 --- a/core/commands2/root.go +++ b/core/commands2/root.go @@ -1,9 +1,6 @@ package commands import ( - "fmt" - "strings" - cmds "github.com/jbenet/go-ipfs/commands" u "github.com/jbenet/go-ipfs/util" ) @@ -16,15 +13,8 @@ type TestOutput struct { } var Root = &cmds.Command{ - Options: []cmds.Option{ - cmds.Option{[]string{"config", "c"}, cmds.String}, - cmds.Option{[]string{"debug", "D"}, cmds.Bool}, - cmds.Option{[]string{"help", "h"}, cmds.Bool}, - cmds.Option{[]string{"local", "L"}, cmds.Bool}, - }, - Help: `ipfs - global versioned p2p merkledag file system - -Basic commands: + Description: "Global P2P Merkle-DAG filesystem", + Help: `Basic commands: init Initialize ipfs local configuration. add Add an object to ipfs. @@ -53,6 +43,17 @@ Plumbing commands: Use "ipfs help " for more information about a command. `, + + Options: []cmds.Option{ + cmds.Option{[]string{"config", "c"}, cmds.String, + "Path to the configuration file to use"}, + cmds.Option{[]string{"debug", "D"}, cmds.Bool, + "Operate in debug mode"}, + cmds.Option{[]string{"help", "h"}, cmds.Bool, + "Show the command help text"}, + cmds.Option{[]string{"local", "L"}, cmds.Bool, + "Run the command locally, instead of using the daemon"}, + }, } var rootSubcommands = map[string]*cmds.Command{ diff --git a/core/commands2/update.go b/core/commands2/update.go index 9e1edd186..8702e0154 100644 --- a/core/commands2/update.go +++ b/core/commands2/update.go @@ -15,14 +15,10 @@ type UpdateOutput struct { } var updateCmd = &cmds.Command{ - Help: `ipfs update - check for updates and apply them - - ipfs update - apply - ipfs update check - just check - ipfs update log - list the changelogs - -ipfs update is a utility command used to check for updates and apply them. + Description: "Downloads and installs updates for IPFS", + Help: `ipfs update is a utility command used to check for updates and apply them. `, + Run: func(res cmds.Response, req cmds.Request) { n := req.Context().Node @@ -55,7 +51,12 @@ ipfs update is a utility command used to check for updates and apply them. } var updateCheckCmd = &cmds.Command{ - Help: `ipfs update check `, + Description: "Checks if updates are available", + Help: `'ipfs update check' checks if any updates are available for IPFS. + +Nothing will be downloaded or installed. +`, + Run: func(res cmds.Response, req cmds.Request) { n := req.Context().Node @@ -84,7 +85,10 @@ var updateCheckCmd = &cmds.Command{ } var updateLogCmd = &cmds.Command{ - Help: `ipfs update log - list the last versions and their changelog`, + Description: "List the changelog for the latest versions of IPFS", + Help: `This command is not yet implemented. +`, + Run: func(res cmds.Response, req cmds.Request) { n := req.Context().Node @@ -151,5 +155,6 @@ func updateCheck(n *core.IpfsNode) (*UpdateOutput, error) { // updateLog lists the version available online func updateLog(n *core.IpfsNode) (interface{}, error) { + // TODO return nil, errors.New("Not yet implemented") } diff --git a/core/commands2/version.go b/core/commands2/version.go index 019c6959b..9d085dd61 100644 --- a/core/commands2/version.go +++ b/core/commands2/version.go @@ -12,13 +12,14 @@ type VersionOutput struct { } var versionCmd = &cmds.Command{ - Options: []cmds.Option{ - cmds.Option{[]string{"number", "n"}, cmds.Bool}, - }, - Help: `ipfs version - Show ipfs version information. + Description: "Outputs the current version of IPFS", + Help: `Returns the version number of IPFS. +`, - Returns the current version of ipfs and exits. - `, + Options: []cmds.Option{ + cmds.Option{[]string{"number", "n"}, cmds.Bool, + "Only output the version number"}, + }, Run: func(res cmds.Response, req cmds.Request) { res.SetOutput(&VersionOutput{ Version: config.CurrentVersionNumber,