doc (#83)

* add documentation parts

* add badge for go reference

---------

Co-authored-by: Dawid Ciepiela <71898979-sarumaj@users.noreply.github.com>

README.md

@@ -3,6 +3,7 @@
 [![Go Report Card](https://goreportcard.com/badge/github.com/sarumaj/gh-gr)](https://goreportcard.com/report/github.com/sarumaj/gh-gr)
 [![Maintainability](https://img.shields.io/codeclimate/maintainability-percentage/sarumaj/gh-gr.svg)](https://codeclimate.com/github/sarumaj/gh-gr/maintainability)
 [![Test Coverage](https://api.codeclimate.com/v1/badges/0c9cdd86241d58f97085/test_coverage)](https://codeclimate.com/github/sarumaj/gh-gr/test_coverage)
+[![Go Reference](https://pkg.go.dev/badge/github.com/sarumaj/gh-gr.svg)](https://pkg.go.dev/github.com/sarumaj/gh-gr)
 
 ---
 
@@ -29,33 +30,33 @@ $ gh extension install https://github.com/sarumaj/gh-gr
 ```console
 $ gh gr --help
 
->> gr is a gh cli extension allowing management of multiple repositories at once
->>
->> Usage:
->>   gr [flags]
->>   gr [command]
->>
->> Available Commands:
->>   cleanup     Clean up untracked local repositories
->>   completion  Generate the autocompletion script for the specified shell
->>   export      Export current configuration to stdout
->>   help        Help about any command
->>   import      Import configuration from stdin or a file
->>   init        Initialize repository mirror
->>   pull        Pull all repositories
->>   push        Push all repositories
->>   remove      Remove current configuration
->>   status      Show status for all repositories
->>   update      Update configuration
->>   version     Display version information
->>   view        Display current configuration
->>
->> Flags:
->>   -c, --concurrency uint   Concurrency for concurrent jobs (default 12)
->>   -h, --help               help for gr
->>   -t, --timeout duration   Set timeout for long running jobs (default 10m0s)
->>
->> Use "gr [command] --help" for more information about a command.
+> gr is a gh cli extension allowing management of multiple repositories at once
+>
+> Usage:
+>   gr [flags]
+>   gr [command]
+>
+> Available Commands:
+>   cleanup     Clean up untracked local repositories
+>   completion  Generate the autocompletion script for the specified shell
+>   export      Export current configuration to stdout
+>   help        Help about any command
+>   import      Import configuration from stdin or a file
+>   init        Initialize repository mirror
+>   pull        Pull all repositories
+>   push        Push all repositories
+>   remove      Remove current configuration
+>   status      Show status for all repositories
+>   update      Update configuration
+>   version     Display version information
+>   view        Display current configuration
+>
+> Flags:
+>   -c, --concurrency uint   Concurrency for concurrent jobs (default 12)
+>   -h, --help               help for gr
+>   -t, --timeout duration   Set timeout for long running jobs (default 10m0s)
+>
+> Use "gr [command] --help" for more information about a command.
 ```
 
 First, create the configuration:

cmd/gh-gr/main.go

@@ -1,3 +1,36 @@
+/*
+	gh-gr is a CLI tool to manage GitHub repositories.
+	The tool is designed to work with multiple GitHub accounts and organizations.
+  It utilizes the GitHub API to retrieve the list of repositories and their metadata.
+  Futhermore, it plugs into the GitHub CLI to provide a seamless experience.
+
+	Usage:
+    gr [flags]
+    gr [command]
+
+  Available Commands:
+    cleanup     Clean up untracked local repositories
+    completion  Generate the autocompletion script for the specified shell
+    export      Export current configuration to stdout
+    help        Help about any command
+    import      Import configuration from stdin or a file
+    init        Initialize repository mirror
+    pull        Pull all repositories
+    push        Push all repositories
+    remove      Remove current configuration
+    status      Show status for all repositories
+    update      Update configuration
+    version     Display version information
+    view        Display current configuration
+
+  Flags:
+    -c, --concurrency uint   Concurrency for concurrent jobs (default 12)
+    -h, --help               help for gr
+    -t, --timeout duration   Set timeout for long running jobs (default 10m0s)
+
+  Use "gr [command] --help" for more information about a command.
+*/
+
 package main
 
 import (

pkg/commands/command_cleanup.go

@@ -7,6 +7,7 @@ import (
 	cobra "github.com/spf13/cobra"
 )
 
+// cleanupCmd represents the cleanup command
 var cleanupCmd = &cobra.Command{
 	Use:     "cleanup",
 	Aliases: []string{"clean", "cl"},

pkg/commands/command_export.go

@@ -10,9 +10,13 @@ import (
 	cobra "github.com/spf13/cobra"
 )
 
-var exportCmd = func() *cobra.Command {
-	var formatOption string
+// exportFlags contains flags for import command
+var exportFlags struct {
+	formatOption string
+}
 
+// exportCmd represents the export command
+var exportCmd = func() *cobra.Command {
 	exportCmd := &cobra.Command{
 		Use:   "export",
 		Short: "Export current configuration to stdout",
@@ -28,14 +32,14 @@ var exportCmd = func() *cobra.Command {
 			logger := loggerEntry.WithField("command", "export")
 			conf := configfile.Load()
 
-			logger.Debugf("Export format: %s", formatOption)
-			conf.Display(formatOption, true)
+			logger.Debugf("Export format: %s", exportFlags.formatOption)
+			conf.Display(exportFlags.formatOption, true)
 		},
 	}
 
 	flags := exportCmd.Flags()
 	supportedFormats := strings.Join(configfile.GetListOfSupportedFormats(true), ", ")
-	flags.StringVarP(&formatOption, "format", "f", "yaml", fmt.Sprintf("Change output format, supported formats: [%s]", supportedFormats))
+	flags.StringVarP(&exportFlags.formatOption, "format", "f", "yaml", fmt.Sprintf("Change output format, supported formats: [%s]", supportedFormats))
 
 	return exportCmd
 }()

pkg/commands/command_import.go

@@ -8,9 +8,13 @@ import (
 	cobra "github.com/spf13/cobra"
 )
 
-var importCmd = func() *cobra.Command {
-	var formatOption string
+// importFlags contains flags for import command
+var importFlags struct {
+	formatOption string
+}
 
+// importCmd represents the import command
+var importCmd = func() *cobra.Command {
 	importCmd := &cobra.Command{
 		Use:   "import",
 		Short: "Import configuration from stdin or a file",
@@ -21,9 +25,9 @@ var importCmd = func() *cobra.Command {
 		Example: "cat export.yaml | gh gr import --format yaml",
 		Run: func(*cobra.Command, []string) {
 			logger := loggerEntry.WithField("command", "import")
-			logger.Debugf("Import format: %s", formatOption)
+			logger.Debugf("Import format: %s", importFlags.formatOption)
 
-			configfile.Import(formatOption)
+			configfile.Import(importFlags.formatOption)
 		},
 		PostRun: func(*cobra.Command, []string) {
 			updateConfigFlags()
@@ -32,7 +36,7 @@ var importCmd = func() *cobra.Command {
 
 	flags := importCmd.Flags()
 	supportedFormats := strings.Join(configfile.GetListOfSupportedFormats(true), ", ")
-	flags.StringVarP(&formatOption, "format", "f", "yaml", fmt.Sprintf("Change input format, supported formats: [%s]", supportedFormats))
+	flags.StringVarP(&importFlags.formatOption, "format", "f", "yaml", fmt.Sprintf("Change input format, supported formats: [%s]", supportedFormats))
 
 	return importCmd
 }()

pkg/commands/command_init.go

@@ -4,6 +4,7 @@ import (
 	cobra "github.com/spf13/cobra"
 )
 
+// initCmd represents the init command
 var initCmd = func() *cobra.Command {
 	initCmd := &cobra.Command{
 		Use:     "init",

pkg/commands/command_pull.go

@@ -12,6 +12,7 @@ import (
 	pool "gopkg.in/go-playground/pool.v3"
 )
 
+// pullCmd represents the pull command
 var pullCmd = &cobra.Command{
 	Use:     "pull",
 	Short:   "Pull all repositories",

pkg/commands/command_push.go

@@ -12,6 +12,7 @@ import (
 	pool "gopkg.in/go-playground/pool.v3"
 )
 
+// pullCmd represents the pull command
 var pushCmd = &cobra.Command{
 	Use:     "push",
 	Short:   "Push all repositories",

pkg/commands/command_remove.go

@@ -7,9 +7,13 @@ import (
 	cobra "github.com/spf13/cobra"
 )
 
-var removeCmd = func() *cobra.Command {
-	var purge bool
+// removeFlags represents the flags for remove command
+var removeFlags struct {
+	purge bool
+}
 
+// removeCmd represents the remove command
+var removeCmd = func() *cobra.Command {
 	removeCmd := &cobra.Command{
 		Use:     "remove",
 		Aliases: []string{"reset", "rm", "delete", "del"},
@@ -26,13 +30,13 @@ var removeCmd = func() *cobra.Command {
 			logger := loggerEntry.WithField("command", "remove")
 			conf := configfile.Load()
 
-			logger.Debugf("Removing config, purge: %t", purge)
-			conf.Remove(purge)
+			logger.Debugf("Removing config, purge: %t", removeFlags.purge)
+			conf.Remove(removeFlags.purge)
 		},
 	}
 
 	flags := removeCmd.Flags()
-	flags.BoolVar(&purge, "purge", false, "DANGER!!! Purge directory with local repositories")
+	flags.BoolVar(&removeFlags.purge, "purge", false, "DANGER!!! Purge directory with local repositories")
 
 	return removeCmd
 }()

pkg/commands/command_root.go

@@ -10,9 +10,13 @@ import (
 	cobra "github.com/spf13/cobra"
 )
 
+// configFlags is a global variable holding configuration flags
 var configFlags = &configfile.Configuration{}
+
+// loggerEntry is a global variable holding logger entry at package level
 var loggerEntry = util.Logger.WithFields(logrus.Fields{"mod": "commands"})
 
+// rootCmd represents the base command when called without any subcommands
 var rootCmd = func() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "gr",
@@ -26,13 +30,15 @@ var rootCmd = func() *cobra.Command {
 				configFlags = configfile.Load()
 			}
 
+			logger := util.Logger
 			if util.GetenvBool(util.Verbose) {
-				util.Logger.SetLevel(logrus.DebugLevel)
+				logger.SetLevel(logrus.DebugLevel)
 			}
 
-			util.Logger.Debug("Running in verbose mode")
+			logger.Debugf("Version: %s, build date: %s, executable path: %s", versionFlags.internalVersion, versionFlags.internalBuildDate, util.GetExecutablePath())
+			logger.Debug("Running in verbose mode")
 		},
-		Version: internalVersion,
+		Version: versionFlags.internalVersion,
 	}
 
 	flags := cmd.PersistentFlags()
@@ -46,10 +52,8 @@ var rootCmd = func() *cobra.Command {
 
 // Execute executes the root command.
 func Execute(version, buildDate string) {
-	internalVersion, internalBuildDate = version, buildDate
-
+	versionFlags.internalVersion, versionFlags.internalBuildDate = version, buildDate
 	logger := util.Logger
-	logger.Debugf("Version: %s, build date: %s, executable path: %s", internalVersion, internalBuildDate, util.GetExecutablePath())
 
 	defer util.AcquireProcessIDLock().Unlock()
 

pkg/commands/command_status.go

@@ -10,6 +10,7 @@ import (
 	pool "gopkg.in/go-playground/pool.v3"
 )
 
+// statusCmd represents the status command
 var statusCmd = &cobra.Command{
 	Use:   "status",
 	Short: "Show status for all repositories",

pkg/commands/command_update.go

@@ -4,6 +4,7 @@ import (
 	cobra "github.com/spf13/cobra"
 )
 
+// updateCmd represents the update command
 var updateCmd = &cobra.Command{
 	Use:     "update",
 	Short:   "Update configuration",

pkg/commands/command_version.go

@@ -15,13 +15,16 @@ import (
 // Address of remote repository where the newest version of gh-gr is released.
 const remoteRepository = "sarumaj/gh-gr"
 
-// Version holds the application version.
-// It gets filled automatically at build time.
-var internalVersion string
-
-// BuildDate holds the date and time at which the application was build.
-// It gets filled automatically at build time.
-var internalBuildDate string
+// versionFlags holds the application version and build date.
+var versionFlags struct {
+	// Version holds the application version.
+	// It gets filled automatically at build time.
+	internalVersion string
+
+	// BuildDate holds the date and time at which the application was build.
+	// It gets filled automatically at build time.
+	internalBuildDate string
+}
 
 var versionCmd = &cobra.Command{
 	Use:     "version",
@@ -30,7 +33,7 @@ var versionCmd = &cobra.Command{
 	Run: func(*cobra.Command, []string) {
 		c := util.Console()
 
-		current := supererrors.ExceptFn(supererrors.W(semver.ParseTolerant(internalVersion)))
+		current := supererrors.ExceptFn(supererrors.W(semver.ParseTolerant(versionFlags.internalVersion)))
 		latest, found, err := selfupdate.DetectLatest(context.Background(), selfupdate.ParseSlug(remoteRepository))
 
 		var vSuffix string
@@ -43,8 +46,8 @@ var versionCmd = &cobra.Command{
 
 		}
 
-		_ = supererrors.ExceptFn(supererrors.W(fmt.Fprintln(c.Stdout(), c.CheckColors(color.BlueString, "Version: %s", internalVersion+vSuffix))))
-		_ = supererrors.ExceptFn(supererrors.W(fmt.Fprintln(c.Stdout(), c.CheckColors(color.BlueString, "Built at: %s", internalBuildDate))))
+		_ = supererrors.ExceptFn(supererrors.W(fmt.Fprintln(c.Stdout(), c.CheckColors(color.BlueString, "Version: %s", versionFlags.internalVersion+vSuffix))))
+		_ = supererrors.ExceptFn(supererrors.W(fmt.Fprintln(c.Stdout(), c.CheckColors(color.BlueString, "Built at: %s", versionFlags.internalBuildDate))))
 		_ = supererrors.ExceptFn(supererrors.W(fmt.Fprintln(c.Stdout(), c.CheckColors(color.BlueString, "Executable path: %s", util.GetExecutablePath()))))
 	},
 }

pkg/commands/command_view.go

@@ -10,10 +10,14 @@ import (
 	cobra "github.com/spf13/cobra"
 )
 
-var viewCmd = func() *cobra.Command {
-	var formatOption string
-	var filters []string
+// viewFlags represents the flags for view command
+var viewFlags struct {
+	formatOption string
+	filters      []string
+}
 
+// viewCmd represents the view command
+var viewCmd = func() *cobra.Command {
 	viewCmd := &cobra.Command{
 		Aliases: []string{"show", "list", "ls"},
 		Use:     "view",
@@ -31,14 +35,14 @@ var viewCmd = func() *cobra.Command {
 			conf := configfile.Load()
 
 			logger.Debug("Streaming")
-			conf.Display(formatOption, false, filters...)
+			conf.Display(viewFlags.formatOption, false, viewFlags.filters...)
 		},
 	}
 
 	flags := viewCmd.Flags()
 	supportedFormats := strings.Join(configfile.GetListOfSupportedFormats(true), ", ")
-	flags.StringVarP(&formatOption, "format", "f", "yaml", fmt.Sprintf("Change output format, supported formats: [%s]", supportedFormats))
-	flags.StringArrayVarP(&filters, "match", "m", []string{}, "Glob pattern(s) to filter repositories")
+	flags.StringVarP(&viewFlags.formatOption, "format", "f", "yaml", fmt.Sprintf("Change output format, supported formats: [%s]", supportedFormats))
+	flags.StringArrayVarP(&viewFlags.filters, "match", "m", []string{}, "Glob pattern(s) to filter repositories")
 
 	return viewCmd
 }()