-
Notifications
You must be signed in to change notification settings - Fork 2.8k
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.
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
Documenting a positional argument and suppressing [flags]
when appropriate
#395
Comments
Fixing the default template to not say |
I think you meant the third problem, but yes! That would work. Looking at the default template I linked, my guess is using |
Yes, the third problem. |
#284 is one approach to the second problem |
That looks great! I would prefer to use the main source, but it looks like that PR has been hanging out for awhile. Would you mind merging upstream master into your fork again? If not, no worries, I can maintain my own fork if necessary.
|
I've rebased it with master |
|
Nice. It sounds like the current solutions to the three problems mentioned in the ticket are:
I think once the behavior on master satisfies these points, I'll add a comment with a new |
#284 will not solve first problem. Only second |
@kofalt, is your problem solved? |
Yes! Give or take. Thank you for reminding me. The first problem is handled by manually typing a positional argument in the usage string, the second problem is handled by #284 landing, and the third problem is small enough to be ignored. Thanks to everyone who helped. Here is a complete solution for anyone who was following along: package main
import (
. "fmt"
"os"
"github.com/spf13/cobra"
)
func main() {
RootCmd := &cobra.Command{
Use: "example",
Short: "An example cobra command",
}
var bare bool
CloneCmd := &cobra.Command{
Use: "clone [URL]",
Short: "Clone a repository into a new directory",
Args: cobra.ExactArgs(1),
Run: func(cmd *cobra.Command, args []string) {
// This is guaranteed to work, due to ExactArgs above
url := args[0]
Println("Cloning from", url, "with bare =", bare)
},
}
CloneCmd.Flags().BoolVar(&bare, "bare", false, "Make a bare Git repository.")
RootCmd.AddCommand(CloneCmd)
err := RootCmd.Execute()
if err != nil {
Println(err)
os.Exit(1)
}
} In action:
|
To 1.) Documentation of positional arguments in an automated manner is tracked in #378 |
Documenting positional arguments must be done manually, still: spf13/cobra#395
- updated README getting started section to work with new cobra CLI - updated subcommand use section, short descriptions and long descriptions to provide more information - particularly, they now show the positional arguments in "Usage" - added descriptions of the positional arguments in the long description - these are kind of inelegant, see these issues in cobra for why this had to be done - spf13/cobra#395 - spf13/cobra#378
The readme references an example command that has a positional argument:
To document that in Hugo, here's what I would start with:
Which produces:
This stub could use a few improvements:
URL
is not specified in the help.args
array forURL
, invent some error messages, etc.[flags]
, but there are no flags!Any ideas on how I could tackle these improvements?
The first one could probably be fixed by setting
Use
to"clone [URL]"
, but the third one is the real pickle. As far as I can tell I'd have to copy and modify the default template, at which point I'm detached from the official version and I'd have to maintain my "fork" of the template, which I'd rather avoid.The text was updated successfully, but these errors were encountered: