From c2bbfaa12d512a2ebaa34009ce3cab65e153bbc1 Mon Sep 17 00:00:00 2001
From: Jake Dodd <jake@usedopamine.com>
Date: Mon, 5 Feb 2018 11:53:53 -0800
Subject: [PATCH] Add usage example for required flags (#627)

* Add usage example for required flags

* Explain new behavior in MarkFlagRequired godocs
---
 README.md           | 13 +++++++++++--
 bash_completions.go |  9 ++++++---
 2 files changed, 17 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index f887d603..42aad4bb 100644
--- a/README.md
+++ b/README.md
@@ -337,8 +337,8 @@ rootCmd.Flags().StringVarP(&Source, "source", "s", "", "Source directory to read
 
 ### Local Flag on Parent Commands
 
-By default Cobra only parses local flags on the target command, any local flags on 
-parent commands are ignored. By enabling `Command.TraverseChildren` Cobra will 
+By default Cobra only parses local flags on the target command, any local flags on
+parent commands are ignored. By enabling `Command.TraverseChildren` Cobra will
 parse local flags on each command before executing the target command.
 
 ```go
@@ -366,6 +366,15 @@ when the `--author` flag is not provided by user.
 
 More in [viper documentation](https://github.com/spf13/viper#working-with-flags).
 
+### Required flags
+
+Flags are optional by default. If instead you wish your command to report an error
+when a flag has not been set, mark it as required:
+```go
+rootCmd.Flags().StringVarP(&Region, "region", "r", "", "AWS region (required)")
+rootCmd.MarkFlagRequired("region")
+```
+
 ## Positional and Custom Arguments
 
 Validation of positional arguments can be specified using the `Args` field
diff --git a/bash_completions.go b/bash_completions.go
index 81bfb613..2076b454 100644
--- a/bash_completions.go
+++ b/bash_completions.go
@@ -494,17 +494,20 @@ func (c *Command) GenBashCompletionFile(filename string) error {
 	return c.GenBashCompletion(outFile)
 }
 
-// MarkFlagRequired adds the BashCompOneRequiredFlag annotation to the named flag, if it exists.
+// MarkFlagRequired adds the BashCompOneRequiredFlag annotation to the named flag if it exists,
+// and causes your command to report an error if invoked without the flag.
 func (c *Command) MarkFlagRequired(name string) error {
 	return MarkFlagRequired(c.Flags(), name)
 }
 
-// MarkPersistentFlagRequired adds the BashCompOneRequiredFlag annotation to the named persistent flag, if it exists.
+// MarkPersistentFlagRequired adds the BashCompOneRequiredFlag annotation to the named persistent flag if it exists,
+// and causes your command to report an error if invoked without the flag.
 func (c *Command) MarkPersistentFlagRequired(name string) error {
 	return MarkFlagRequired(c.PersistentFlags(), name)
 }
 
-// MarkFlagRequired adds the BashCompOneRequiredFlag annotation to the named flag in the flag set, if it exists.
+// MarkFlagRequired adds the BashCompOneRequiredFlag annotation to the named flag if it exists,
+// and causes your command to report an error if invoked without the flag.
 func MarkFlagRequired(flags *pflag.FlagSet, name string) error {
 	return flags.SetAnnotation(name, BashCompOneRequiredFlag, []string{"true"})
 }