From c8a20a16bafa2dc85d304b59b2e677c7f75a73a6 Mon Sep 17 00:00:00 2001
From: Luiz Carvalho <luizcarvalho85@gmail.com>
Date: Thu, 16 Mar 2023 21:03:29 -0400
Subject: [PATCH] Document suggested layout for subcommands (#1930)

Signed-off-by: Luiz Carvalho <lucarval@redhat.com>
---
 user_guide.md | 31 +++++++++++++++++++++++++++++++
 1 file changed, 31 insertions(+)

diff --git a/user_guide.md b/user_guide.md
index 00b53d03..85201d84 100644
--- a/user_guide.md
+++ b/user_guide.md
@@ -188,6 +188,37 @@ var versionCmd = &cobra.Command{
 }
 ```
 
+### Organizing subcommands
+
+A command may have subcommands which in turn may have other subcommands. This is achieved by using
+`AddCommand`. In some cases, especially in larger applications, each subcommand may be defined in
+its own go package.
+
+The suggested approach is for the parent command to use `AddCommand` to add its most immediate
+subcommands. For example, consider the following directory structure:
+
+```text
+├── cmd
+│   ├── root.go
+│   └── sub1
+│       ├── sub1.go
+│       └── sub2
+│           ├── leafA.go
+│           ├── leafB.go
+│           └── sub2.go
+└── main.go
+```
+
+In this case:
+
+* The `init` function of `root.go` adds the command defined in `sub1.go` to the root command.
+* The `init` function of `sub1.go` adds the command defined in `sub2.go` to the sub1 command.
+* The `init` function of `sub2.go` adds the commands defined in `leafA.go` and `leafB.go` to the
+  sub2 command.
+
+This approach ensures the subcommands are always included at compile time while avoiding cyclic
+references.
+
 ### Returning and handling errors
 
 If you wish to return an error to the caller of a command, `RunE` can be used.