Merge branch 'trunk' into git-tag-release-notes

pkg/cmd/repo/list/list.go

@@ -6,6 +6,7 @@ import (
 	"strings"
 	"time"
 
+	"github.com/MakeNowJust/heredoc"
 	"github.com/spf13/cobra"
 
 	"github.com/cli/cli/v2/api"
@@ -52,9 +53,16 @@ func NewCmdList(f *cmdutil.Factory, runF func(*ListOptions) error) *cobra.Comman
 	)
 
 	cmd := &cobra.Command{
-		Use:     "list [<owner>]",
-		Args:    cobra.MaximumNArgs(1),
-		Short:   "List repositories owned by user or organization",
+		Use:   "list [<owner>]",
+		Args:  cobra.MaximumNArgs(1),
+		Short: "List repositories owned by user or organization",
+		Long: heredoc.Docf(`
+			List repositories owned by a user or organization.
+
+			Note that the list will only include repositories owned by the provided argument,
+			and the %[1]s--fork%[1]s or %[1]s--source%[1]s flags will not traverse ownership boundaries. For example,
+			when listing the forks in an organization, the output would not include those owned by individual users.
+		`, "`"),
 		Aliases: []string{"ls"},
 		RunE: func(c *cobra.Command, args []string) error {
 			if opts.Limit < 1 {