Merge pull request cli#12710 from cli/kw/document-gist-edit-file-replacement

Add usage examples to `gh gist edit` command

Author: BagToad

pkg/cmd/gist/edit/edit.go

@@ -12,6 +12,7 @@ import (
 	"sort"
 	"strings"
 
+	"github.com/MakeNowJust/heredoc"
 	"github.com/cli/cli/v2/api"
 	"github.com/cli/cli/v2/internal/gh"
 	"github.com/cli/cli/v2/internal/prompter"
@@ -58,6 +59,28 @@ func NewCmdEdit(f *cmdutil.Factory, runF func(*EditOptions) error) *cobra.Comman
 	cmd := &cobra.Command{
 		Use:   "edit {<id> | <url>} [<filename>]",
 		Short: "Edit one of your gists",
+		Example: heredoc.Doc(`
+			# Select a gist to edit interactively
+			$ gh gist edit
+
+			# Edit a gist file in the default editor
+			$ gh gist edit 1234567890abcdef1234567890abcdef
+
+			# Edit a specific file in the gist
+			$ gh gist edit 1234567890abcdef1234567890abcdef --filename hello.py
+
+			# Replace a gist file with content from a local file
+			$ gh gist edit 1234567890abcdef1234567890abcdef --filename hello.py hello.py
+
+			# Add a new file to the gist
+			$ gh gist edit 1234567890abcdef1234567890abcdef --add newfile.py
+
+			# Change the description of the gist
+			$ gh gist edit 1234567890abcdef1234567890abcdef --desc "new description"
+
+			# Remove a file from the gist
+			$ gh gist edit 1234567890abcdef1234567890abcdef --remove hello.py
+		`),
 		Args: func(cmd *cobra.Command, args []string) error {
 			if len(args) > 2 {
 				return cmdutil.FlagErrorf("too many arguments")