ipfs / ipfs/kubo

Document global flags on sub-commands

Open
#6,640 3 comments 2 reactions 0 assignees View on GitHub
help wanted kind/enhancement topic/docs-ipfs
Dominant language
Go
Stars
17.1k
Forks
3.2k
Avg merge
3d 18h
Merged PRs (30d)
11

Description

Global flags (flags on the root `ipfs` commands) are now documented in `ipfs --help`. However, they _aren't_ documented in, e.g., `ipfs add --help`.

Given that command help is already pretty long, we should probably shouldn't just _copy_ the documentation by default. Instead, we should consider adding a section that lists parent commands that define their own options. For example, given `ipfs files ls --help`, we should extend the options section as follows.

```
OPTIONS

-l, --long bool - Use long listing format.
-U bool - Do not sort; list entries in directory order.

Inherits options from: 'ipfs files --help', 'ipfs --help'

DESCRIPTION
...
```

However, if the user specifies `ipfs files ls --help-all`, we should include the options directly:

```
OPTIONS
...

OPTIONS

-l, --long bool - Use long listing format.
-U bool - Do not sort; list entries in directory order.

ipfs files
-f, --flush bool - Flush target and ancestors after write. Default: true.

ipfs
-c, --config string - Path to the configuration file to use.
-D, --debug bool - Operate in debug mode.
--help bool - Show the full command help text.
-h bool - Show a short version of the command help text.
-L, --local bool - Run the command locally, instead of using the daemon. DEPRECATED: use
--offline.
--offline bool - Run the command offline.
--api string - Use a specific API instance (defaults to /ip4/127.0.0.1/tcp/5001).
--cid-base string - Multibase encoding used for version 1 CIDs in output.
--upgrade-cidv0-in-output bool - Upgrade version 0 to version 1 CIDs in output.
--enc, --encoding string - The encoding type the output should be encoded with (json, xml, or text).
Default: text.
--stream-channels bool - Stream channel output.

DESCRIPTION
...
```

Picks up where https://github.com/ipfs/go-ipfs/issues/4432 left off.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.