opensource/kubo
1
0
Fork 0
mirror of https://github.com/ipfs/kubo.git synced 2025-05-20 00:18:12 +08:00
Code Issues Projects Releases Wiki Activity

CLI: discoverability and consistency (#2542)

Browse Source 
* reduces help indent from 4 to 2 spaces

License: MIT
Signed-off-by: Stephen Whitmore <noffle@ipfs.io>

* reduces horz/vert space taken by "ipfs" cmd

License: MIT
Signed-off-by: Stephen Whitmore <noffle@ipfs.io>

* show subcommands on shorthelp

License: MIT
Signed-off-by: Stephen Whitmore <noffle@ipfs.io>

* Drops colons at the end of cmd headings.

This makes command headings consistent with the output of 'ipfs', which
does not include colons.

License: MIT
Signed-off-by: Stephen Whitmore <noffle@ipfs.io>

* more consistent output between short-/long-help

License: MIT
Signed-off-by: Stephen Whitmore <noffle@ipfs.io>

* Puts DESCRIPTION before SUBCOMMANDS.

Users likely want to understand what a command does before worrying
about its subcommands.

License: MIT
Signed-off-by: Stephen Whitmore <noffle@ipfs.io>

* Keeps ipfs cmd from outputting its subcmds twice.

License: MIT
Signed-off-by: Stephen Whitmore <noffle@ipfs.io>

* Removes redundant synopsis from "file"

License: MIT
Signed-off-by: Stephen Whitmore <noffle@ipfs.io>

* Removes extra whitespace from longhelp

License: MIT
Signed-off-by: Stephen Whitmore <noffle@ipfs.io>

* Consistent spacing whether SUBCMDS or not.

License: MIT
Signed-off-by: Stephen Whitmore <noffle@ipfs.io>

* Removes redundant SUBCMD output from ipfs object.

License: MIT
Signed-off-by: Stephen Whitmore <noffle@ipfs.io>

* Removes redundant synopsis from "name"

License: MIT
Signed-off-by: Stephen Whitmore <noffle@ipfs.io>

* Newline after Description only if it exists.

License: MIT
Signed-off-by: Stephen Whitmore <noffle@ipfs.io>

* Removes redundant synopsis from "bootstrap"

License: MIT
Signed-off-by: Stephen Whitmore <noffle@ipfs.io>

* Removes redundant synopsis from "swarm"

License: MIT
Signed-off-by: Stephen Whitmore <noffle@ipfs.io>

* Removes trailing newline in ping help.

License: MIT
Signed-off-by: Stephen Whitmore <noffle@ipfs.io>

* Prints shorthelp on parse error.

License: MIT
Signed-off-by: Stephen Whitmore <noffle@ipfs.io>

* tiny comment fixes

License: MIT
Signed-off-by: Stephen Whitmore <noffle@ipfs.io>

* updates README usage

License: MIT
Signed-off-by: Stephen Whitmore <noffle@ipfs.io>

* Don't include extra whitespace if no .MoreHelp

License: MIT
Signed-off-by: Stephen Whitmore <noffle@ipfs.io>

* description improvements

License: MIT
Signed-off-by: Stephen Whitmore <noffle@ipfs.io>

* Hides the obscure 'file' subcommand.

License: MIT
Signed-off-by: Stephen Whitmore <noffle@ipfs.io>

* Splits 'ipfs daemon' into Short and Long help.

License: MIT
Signed-off-by: Stephen Whitmore <noffle@ipfs.io>

* Removes redundant synopsis from "config"

License: MIT
Signed-off-by: Stephen Whitmore <noffle@ipfs.io>

* Wraps lines to keep from going over 80.

License: MIT
Signed-off-by: Stephen Whitmore <noffle@ipfs.io>

* specify repo separately

License: MIT
Signed-off-by: Stephen Whitmore <noffle@ipfs.io>

* s/structure/hierarchy

License: MIT
Signed-off-by: Stephen Whitmore <noffle@ipfs.io>

* missing .

License: MIT
Signed-off-by: Stephen Whitmore <noffle@ipfs.io>

* Removes trailing colon from 'usage' test.

License: MIT
Signed-off-by: Stephen Whitmore <noffle@ipfs.io>

* Updates sharness test error messages.

License: MIT
Signed-off-by: Stephen Whitmore <noffle@ipfs.io>

* Removes trailing colon from 'usage' test.

License: MIT
Signed-off-by: Stephen Whitmore <noffle@ipfs.io>

* Updates add-symlink to use /bin/sh.

License: MIT
Signed-off-by: Stephen Whitmore <noffle@ipfs.io>

* Removes "hierarchy".

License: MIT
Signed-off-by: Stephen Whitmore <noffle@ipfs.io>

* Updates "ipfs ping" synopsis.

* Updates t0040 with latest wording.

* Removes unnecessary daemon setup.

License: MIT
Signed-off-by: Stephen Whitmore <noffle@ipfs.io>
This commit is contained in:
Stephen Whitmore
2016-04-28 14:08:32 -07:00
committed by Jeromy Johnson
parent 1b50a9d2a5
commit 0a45ada4ed
21 changed files with 112 additions and 151 deletions
Download Patch File Download Diff File Expand all files Collapse all files

19
README.md
View File

@ -122,39 +122,34 @@ or install it from source with `go get -u github.com/ipfs/ipfs-update`.
## Usage
```
USAGE:
ipfs - global p2p merkle-dag filesystem
ipfs - Global p2p merkle-dag filesystem.
ipfs [<flags>] <command> [<arg>] ...
SUBCOMMANDS
BASIC COMMANDS
init Initialize ipfs local configuration
add <path> Add an object to ipfs
add <path> Add a file to ipfs
cat <ref> Show ipfs object data
get <ref> Download ipfs objects
ls <ref> List links from an object
refs <ref> List hashes of links from an object
DATA STRUCTURE COMMANDS
block Interact with raw blocks in the datastore
object Interact with raw dag nodes
file Interact with Unix filesystem objects
files Interact with objects as if they were a unix filesystem
ADVANCED COMMANDS
daemon Start a long-running daemon process
mount Mount an ipfs read-only mountpoint
resolve Resolve any type of name
name Publish or resolve IPNS names
dns Resolve DNS links
pin Pin objects to local storage
repo gc Garbage collect unpinned objects
repo Manipulate an IPFS repository
NETWORK COMMANDS
id Show info about ipfs peers
bootstrap Add or remove bootstrap peers
swarm Manage connections to the p2p network
@ -163,7 +158,6 @@ USAGE:
diag Print diagnostics
TOOL COMMANDS
config Manage configuration
version Show ipfs version information
update Download and apply go-ipfs updates
@ -171,7 +165,10 @@ USAGE:
Use 'ipfs <command> --help' to learn more about each command.
ipfs uses a repository in the local file system. By default, the repo is located
at ~/.ipfs. To change the repo location, set the $IPFS_PATH environment variable:
export IPFS_PATH=/path/to/ipfsrepo
```
## Getting Started

3
cmd/ipfs/daemon.go
View File

@ -55,7 +55,8 @@ over the network. Most applications that use IPFS will do so by
communicating with a daemon over the HTTP API. While the daemon is
running, calls to 'ipfs' commands will be sent over the network to
the daemon.
`,
LongDescription: `
The daemon will start listening on ports on the network, which are
documented in (and can be modified through) 'ipfs config Addresses'.
For example, to change the 'Gateway' port:

2
cmd/ipfs/init.go
View File

@ -24,8 +24,6 @@ var initCmd = &cmds.Command{
ShortDescription: `
Initializes IPFS configuration files and generates a new keypair.
IPFS_PATH environment variable
ipfs uses a repository in the local file system. By default, the repo is located
at ~/.ipfs. To change the repo location, set the $IPFS_PATH environment variable:

2
cmd/ipfs/main.go
View File

@ -132,7 +132,7 @@ func main() {
if invoc.cmd != nil {
// we need a newline space.
fmt.Fprintf(os.Stderr, "\n")
printMetaHelp(os.Stderr)
printHelp(false, os.Stderr)
}
os.Exit(1)
}

38
commands/cli/helptext.go
View File

@ -74,38 +74,38 @@ func (f *helpFields) IndentAll() {
const usageFormat = "{{if .Usage}}{{.Usage}}{{else}}{{.Path}}{{if .ArgUsage}} {{.ArgUsage}}{{end}} - {{.Tagline}}{{end}}"
const longHelpFormat = `
const longHelpFormat = `USAGE
{{.Indent}}{{template "usage" .}}
{{if .Arguments}}ARGUMENTS:
{{if .Arguments}}ARGUMENTS
{{.Arguments}}
{{end}}{{if .Options}}OPTIONS:
{{end}}{{if .Options}}OPTIONS
{{.Options}}
{{end}}{{if .Subcommands}}SUBCOMMANDS:
{{.Subcommands}}
{{.Indent}}Use '{{.Path}} <subcmd> --help' for more information about each command.
{{end}}{{if .Description}}DESCRIPTION:
{{end}}{{if .Description}}DESCRIPTION
{{.Description}}
{{end}}{{if .Subcommands}}SUBCOMMANDS
{{.Subcommands}}
{{.Indent}}Use '{{.Path}} <subcmd> --help' for more information about each command.
{{end}}
`
const shortHelpFormat = `USAGE:
const shortHelpFormat = `USAGE
{{.Indent}}{{template "usage" .}}
{{if .Synopsis}}
{{.Synopsis}}
{{end}}{{if .Description}}
{{.Description}}
{{end}}
{{if .MoreHelp}}Use '{{.Path}} --help' for more information about this command.
{{end}}{{if .Subcommands}}
SUBCOMMANDS
{{.Subcommands}}
{{end}}{{if .MoreHelp}}
Use '{{.Path}} --help' for more information about this command.
{{end}}
`
@ -119,7 +119,7 @@ func init() {
shortHelpTemplate = template.Must(usageTemplate.New("shortHelp").Parse(shortHelpFormat))
}
// LongHelp returns a formatted CLI helptext string, generated for the given command
// LongHelp writes a formatted CLI helptext string to a Writer for the given command
func LongHelp(rootName string, root *cmds.Command, path []string, out io.Writer) error {
cmd, err := root.Get(path)
if err != nil {
@ -169,7 +169,7 @@ func LongHelp(rootName string, root *cmds.Command, path []string, out io.Writer)
return longHelpTemplate.Execute(out, fields)
}
// ShortHelp returns a formatted CLI helptext string, generated for the given command
// ShortHelp writes a formatted CLI helptext string to a Writer for the given command
func ShortHelp(rootName string, root *cmds.Command, path []string, out io.Writer) error {
cmd, err := root.Get(path)
if err != nil {
@ -193,10 +193,16 @@ func ShortHelp(rootName string, root *cmds.Command, path []string, out io.Writer
Tagline: cmd.Helptext.Tagline,
Synopsis: cmd.Helptext.Synopsis,
Description: cmd.Helptext.ShortDescription,
Subcommands: cmd.Helptext.Subcommands,
Usage: cmd.Helptext.Usage,
MoreHelp: (cmd != root),
}
// autogen fields that are empty
if len(fields.Subcommands) == 0 {
fields.Subcommands = strings.Join(subcommandText(cmd, rootName, path), "\n")
}
// trim the extra newlines (see TrimNewlines doc)
fields.TrimNewlines()

6
core/commands/add.go
View File

@ -30,11 +30,9 @@ const (
var AddCmd = &cmds.Command{
Helptext: cmds.HelpText{
Tagline: "Add a file to ipfs.",
Tagline: "Add a file or directory to ipfs.",
ShortDescription: `
Adds contents of <path> to ipfs. Use -r to add directories.
Note that directories are added recursively, to form the ipfs
MerkleDAG.
Adds contents of <path> to ipfs. Use -r to add directories (recursively).
`,
LongDescription: `
Adds contents of <path> to ipfs. Use -r to add directories.

5
core/commands/bootstrap.go
View File

@ -22,11 +22,6 @@ var peerOptionDesc = "A peer to add to the bootstrap list (in the format '<multi
var BootstrapCmd = &cmds.Command{
Helptext: cmds.HelpText{
Tagline: "Show or edit the list of bootstrap peers.",
Synopsis: `
ipfs bootstrap list - Show peers in the bootstrap list
ipfs bootstrap add <peer>... - Add peers to the bootstrap list
ipfs bootstrap rm <peer>... - Removes peers from the bootstrap list
`,
ShortDescription: `
Running 'ipfs bootstrap' with no arguments will run 'ipfs bootstrap list'.
` + bootstrapSecurityWarning,

7
core/commands/config.go
View File

@ -25,13 +25,6 @@ type ConfigField struct {
var ConfigCmd = &cmds.Command{
Helptext: cmds.HelpText{
Tagline: "Get and set IPFS config values.",
Synopsis: `
ipfs config <key> - Get value of <key>
ipfs config <key> <value> - Set value of <key> to <value>
ipfs config show - Show config file
ipfs config edit - Edit config file in $EDITOR
ipfs config replace <file> - Replaces the config file with <file>
`,
ShortDescription: `
'ipfs config' controls configuration variables. It works like 'git config'.
The configuration values are stored in a config file inside your IPFS

4
core/commands/name.go
View File

@ -10,10 +10,6 @@ type IpnsEntry struct {
var NameCmd = &cmds.Command{
Helptext: cmds.HelpText{
Tagline: "IPFS namespace (IPNS) tool.",
Synopsis: `
ipfs name publish [<name>] <ipfs-path> - Publish an object to IPNS
ipfs name resolve [<name>] - Gets the value currently published at an IPNS name
`,
ShortDescription: `
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

10
core/commands/object/object.go
View File

@ -47,16 +47,6 @@ var ObjectCmd = &cmds.Command{
ShortDescription: `
'ipfs object' is a plumbing command used to manipulate DAG objects
directly.`,
Synopsis: `
ipfs object data <key> - Outputs raw bytes in an object
ipfs object diff <key1> <key2> - Diffs two given objects
ipfs object get <key> - Get the DAG node named by <key>
ipfs object links <key> - Outputs links pointed to by object
ipfs object new <template> - Create new ipfs objects
ipfs object patch <args> - Create new object from old ones
ipfs object put <data> - Stores input, outputs its key
ipfs object stat <key> - Outputs statistics of object
`,
},
Subcommands: map[string]*cmds.Command{

2
core/commands/pin.go
View File

@ -94,7 +94,7 @@ var addPinCmd = &cmds.Command{
var rmPinCmd = &cmds.Command{
Helptext: cmds.HelpText{
Tagline: "Removes the pinned object from local storage. (By default, recursively. Use -r=false for direct pins).",
Tagline: "Removes the pinned object from local storage.",
ShortDescription: `
Removes the pin from the given object allowing it to be garbage
collected if needed. (By default, recursively. Use -r=false for direct pins)

4
core/commands/ping.go
View File

@ -28,9 +28,7 @@ type PingResult struct {
var PingCmd = &cmds.Command{
Helptext: cmds.HelpText{
Tagline: "Send echo request packets to IPFS hosts.",
Synopsis: `
Send pings to a peer using the routing system to discover its address
`,
Synopsis: "Send pings to a peer to verify connectivity and determine latency.",
ShortDescription: `
'ipfs ping' is a tool to test sending data to other nodes. It finds nodes
via the routing system, sends pings, waits for pongs, and prints out round-

3
core/commands/refs.go
View File

@ -35,7 +35,8 @@ var RefsCmd = &cmds.Command{
Helptext: cmds.HelpText{
Tagline: "Lists links (references) from an object.",
ShortDescription: `
Displays the link hashes an IPFS or IPNS object(s) contains, with the following format:
Lists the hashes of all the links an IPFS or IPNS object(s) contains,
with the following format:
<link base58 hash>

10
core/commands/root.go
View File

@ -23,9 +23,8 @@ var Root = &cmds.Command{
Synopsis: `
ipfs [<flags>] <command> [<arg>] ...
`,
ShortDescription: `
Subcommands: `
BASIC COMMANDS
init Initialize ipfs local configuration
add <path> Add a file to ipfs
cat <ref> Show ipfs object data
@ -34,24 +33,20 @@ BASIC COMMANDS
refs <ref> List hashes of links from an object
DATA STRUCTURE COMMANDS
block Interact with raw blocks in the datastore
object Interact with raw dag nodes
files Interact with objects as if they were a unix filesystem
file Interact with Unix filesystem objects
ADVANCED COMMANDS
daemon Start a long-running daemon process
mount Mount an ipfs read-only mountpoint
resolve Resolve any type of name
name Publish or resolve IPNS names
dns Resolve DNS links
pin Pin objects to local storage
repo gc Garbage collect unpinned objects
repo Manipulate the IPFS repository
NETWORK COMMANDS
id Show info about ipfs peers
bootstrap Add or remove bootstrap peers
swarm Manage connections to the p2p network
@ -60,7 +55,6 @@ NETWORK COMMANDS
diag Print diagnostics
TOOL COMMANDS
config Manage configuration
version Show ipfs version information
update Download and apply go-ipfs updates

7
core/commands/swarm.go
View File

@ -28,13 +28,6 @@ type addrMap struct {
var SwarmCmd = &cmds.Command{
Helptext: cmds.HelpText{
Tagline: "Swarm inspection tool.",
Synopsis: `
ipfs swarm addrs - List known addresses. Useful for debugging.
ipfs swarm connect <address> - Open connection to a given address
ipfs swarm disconnect <address> - Close connection to a given address
ipfs swarm filters - Manipulate filters addresses
ipfs swarm peers - List peers with open connections
`,
ShortDescription: `
'ipfs swarm' is a tool to manipulate the network swarm. The swarm is the
component that opens, listens for, and maintains connections to other

3
core/commands/unixfs/unixfs.go
View File

@ -9,9 +9,6 @@ var UnixFSCmd = &cmds.Command{
'ipfs file' provides a familiar interface to file systems represented
by IPFS objects, which hides IPFS implementation details like layout
objects (e.g. fanout and chunking).
`,
Synopsis: `
ipfs file ls <path>... - List directory contents for <path>...
`,
},

2
test/sharness/t0010-basic-commands.sh
View File

@ -26,7 +26,7 @@ test_expect_success "ipfs help succeeds" '
'
test_expect_success "ipfs help output looks good" '
egrep -i "^Usage:" help.txt >/dev/null &&
egrep -i "^Usage" help.txt >/dev/null &&
egrep "ipfs .* <command>" help.txt >/dev/null ||
test_fsh cat help.txt
'

13
test/sharness/t0040-add-and-cat.sh
View File

@ -8,8 +8,15 @@ test_description="Test add and cat commands"
. lib/test-lib.sh
client_err() {
printf "$@\n\nUse 'ipfs add --help' for information about this command\n"
client_err_add() {
printf "$@\n\n"
echo 'USAGE
ipfs add <path>... - Add a file or directory to ipfs.
Adds contents of <path> to ipfs. Use -r to add directories (recursively).
Use '"'"'ipfs add --help'"'"' for more information about this command.
'
}
test_add_cat_file() {
@ -156,7 +163,7 @@ test_add_named_pipe() {
test_expect_success "useful error message when adding a named pipe" '
mkfifo named-pipe &&
test_expect_code 1 ipfs add named-pipe 2>actual &&
client_err "Error: Unrecognized file type for named-pipe: $(generic_stat named-pipe)" >expected &&
client_err_add "Error: Unrecognized file type for named-pipe: $(generic_stat named-pipe)" >expected &&
rm named-pipe &&
test_cmp expected actual
'

2
test/sharness/t0044-add-symlink.sh
View File

@ -1,4 +1,4 @@
#!/bin/bash
#!/bin/sh
#
# Copyright (c) 2014 Christian Couder
# MIT Licensed; see the LICENSE file in this repository.

2
test/sharness/t0060-daemon.sh
View File

@ -69,7 +69,7 @@ test_expect_success "ipfs help succeeds" '
'
test_expect_success "ipfs help output looks good" '
egrep -i "^Usage:" help.txt >/dev/null &&
egrep -i "^Usage" help.txt >/dev/null &&
egrep "ipfs .* <command>" help.txt >/dev/null ||
test_fsh cat help.txt
'

3
test/sharness/t0235-cli-request.sh
View File

@ -9,7 +9,6 @@ test_description="test http requests made by cli"
. lib/test-lib.sh
test_init_ipfs
test_launch_ipfs_daemon
test_expect_success "can make http request against nc server" '
go-sleep 0.5s | nc -l 5005 > nc_out &
@ -28,6 +27,4 @@ test_expect_success "api flag does not appear in request" '
test_expect_code 1 grep "api=/ip4" nc_out
'
test_kill_ipfs_daemon
test_done