Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Document global flags on sub-commands #6640

Open
Stebalien opened this issue Sep 12, 2019 · 3 comments
Open

Document global flags on sub-commands #6640

Stebalien opened this issue Sep 12, 2019 · 3 comments
Labels
help wanted Seeking public contribution on this issue kind/enhancement A net-new feature or improvement to an existing feature topic/docs-ipfs Topic docs-ipfs
Milestone
Best Effort Track

Comments

@Stebalien
Copy link
Member

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 #4432 left off.
@Stebalien Stebalien added kind/enhancement A net-new feature or improvement to an existing feature topic/docs-ipfs Topic docs-ipfs help wanted Seeking public contribution on this issue labels Sep 12, 2019
@Stebalien Stebalien mentioned this issue Sep 12, 2019
Closed
eugene-babichenko added a commit to eugene-babichenko/go-ipfs-cmds that referenced this issue Oct 15, 2019
@eugene-babichenko
helptext: display options for parent commands
467c713 
This helps to understand which options are available for the given
subcommand without calling help for parent commands by providing more
informative output.

Resolves ipfs/kubo#6640
@eugene-babichenko eugene-babichenko mentioned this issue Oct 15, 2019
Closed
@eugene-babichenko
Copy link

Just added a pull request that should resolve this issue.

eugene-babichenko added a commit to eugene-babichenko/go-ipfs-cmds that referenced this issue Oct 16, 2019
@eugene-babichenko
helptext: add a separate --help-all flags to display parent options
47a8f95 
Introduce the --help-all flag as specified in ipfs/kubo#6640. This
flag allows to call more verbose help only when it is necessary.
jbouwman pushed a commit to jbouwman/go-ipfs-cmds that referenced this issue Aug 19, 2021
Work in progress: experimentation with console output
c925c16 
Several open issues mention problems with interaction of the
global `--encoding=` flag and the Encoders and PostRun fields of
command structs. This branch contains experimental refactors that
explore approaches to consistent command execution patterns across
offline, online and http modes.

Specific tickets:

- ipfs/kubo#7050 json encoding for `ls`
- ipfs/kubo#1121 json encoding for `add`
- ipfs/kubo#5594 json encoding for `stats bw`
- ipfs#115 postrun design

Possibly related:

- ipfs/kubo#6640 global flags on subcommands

Incomplete PRs:

- ipfs/kubo#5620 json for 'stat'
@jbouwman jbouwman mentioned this issue Aug 19, 2021
Draft
@BigLep BigLep moved this to 🔎 In Review in IPFS Shipyard Team Mar 3, 2022
@BigLep BigLep added this to the Best Effort Track milestone Mar 3, 2022
@BigLep
Copy link
Contributor

BigLep commented Mar 3, 2022

@jbouwman @Stebalien : is it correct to say that ipfs/go-ipfs-cmds#215 fixes this issue?

@aschmahmann aschmahmann mentioned this issue Mar 18, 2022
Open
@Stebalien
Copy link
Member Author

No, these are two different things. The PR to fix this was ipfs/go-ipfs-cmds#179 (but that, unfortunately, needed some work to get into a mergable state).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
help wanted Seeking public contribution on this issue kind/enhancement A net-new feature or improvement to an existing feature topic/docs-ipfs Topic docs-ipfs
Projects
No open projects
IPFS Shipyard Team
Status: 🔎 In Review
Milestone
Best Effort Track
Development

Successfully merging a pull request may close this issue.

helptext: display options for parent commands eugene-babichenko/go-ipfs-cmds
3 participants
@BigLep @Stebalien @eugene-babichenko