292 update docs and cli command documentation (#293)

* updated phlow command documentation

* added roadmap

* fixed typo in readme

Author: groenborg

README.md

@@ -8,7 +8,7 @@ maintainer: groenborg
 | ------------- | --- | ----------------- | ----- |
 | ![integration status](https://concourse.bosh.praqma.cloud/api/v1/teams/main/pipelines/git-phlow/jobs/checkin/badge) | ![build status](https://concourse.bosh.praqma.cloud/api/v1/teams/main/pipelines/git-phlow/jobs/takeoff/badge)  |[![Go Report Card](https://goreportcard.com/badge/github.com/Praqma/git-phlow)](https://goreportcard.com/report/github.com/Praqma/git-phlow) | [![Coverage Status](https://coveralls.io/repos/github/Praqma/git-phlow/badge.svg?branch=master)](https://coveralls.io/github/Praqma/git-phlow?branch=master) 
 
-Git-phlow (pronounced _"git flow"_), is a CLI extension for git, which provides an extra set of commands to easily use our pragmatic workflow by the same name, **g´Git phlow**. It provides a branching model which makes collaboration easy. It also provides automatic issue tracking using [GitHub](https://github.com) issues or Jira.
+Git-phlow (pronounced _"git flow"_), is a CLI extension for git, which provides an extra set of commands to easily use our pragmatic workflow by the same name, **Git phlow**. It provides a branching model which makes collaboration easy. It also provides automatic issue tracking using [GitHub](https://github.com) issues or Jira.
 
 git-phlows core features include:
 

cmd/agent.go

@@ -16,7 +16,6 @@ var agentCmd = &cobra.Command{
 	Long: fmt.Sprintf(`
 %s commands are a set of commands available for ci/cd services. They are meant as a way of services to easily be compatible with %s.
 
-These are not meant to used as part of your local workflow.
 `, ui.Format.Bold("agent"), ui.Format.Bold("the praqmatic workflow")),
 }
 

cmd/auth.go

@@ -3,21 +3,21 @@ package cmd
 import (
 	"fmt"
 
+	"github.com/praqma/git-phlow/options"
 	"github.com/praqma/git-phlow/phlow"
 	"github.com/praqma/git-phlow/ui"
 	"github.com/spf13/cobra"
-	"github.com/praqma/git-phlow/options"
 )
 
 //enable command
 var authCmd = &cobra.Command{
 	Use:   "auth",
 	Short: "authenticate with different services",
 	Long: fmt.Sprintf(`
-%s will authenticate to a service specified in your .phlow or .gitconfig files. It will use the default service if no other is specified.
-Auth supports two services:
-- Jira
-- GitHub
+%s authorizes git-phlow towards a chosen issue management system like GitHub Issues and Jira. 
+The auth command uses the .gitconfig file to figure out which service it tries to authorizes against. Support issue management systems right now are: 
+:: Jira 
+:: GitHub
 `, ui.Format.Bold("auth")),
 	Run: func(cmd *cobra.Command, args []string) {
 

cmd/bootstrap.go

@@ -1,17 +1,21 @@
 package cmd
 
 import (
-	"github.com/spf13/cobra"
+	"fmt"
+
 	"github.com/praqma/git-phlow/phlow"
+	"github.com/praqma/git-phlow/ui"
+	"github.com/spf13/cobra"
 )
 
 // bootstrapCmd represents the bootstrap command
 var bootstrapCmd = &cobra.Command{
 	Use:   "bootstrap",
 	Short: "creates a .gitconfig file",
-	Long: `
-Creates a new .gitconfig file in your local repository
-	`,
+	Long: fmt.Sprintf(`
+%s creates a new .gitconfig file in the current directory, with the default values of a git-phlow configuration. 
+This is a good way to get started with the configuration file. 
+	`, ui.Format.Bold("bootstrap")),
 	Run: func(cmd *cobra.Command, args []string) {
 		phlow.Bootstrap()
 	},

cmd/cleanup.go

@@ -15,8 +15,10 @@ var cleanCmd = &cobra.Command{
 	Use:   "cleanup",
 	Short: "cleanup removes all delivered branches",
 	Long: fmt.Sprintf(`
-%s removes all branches prefixed with 'delivered/'.
-It deletes safely by running 'git branch -d'. By default, both local and remote branches are deleted.
+%s is for tidying up the git workspace. 
+As you follow the workflow a lot of branches prefixed with 'delivered/' will be in the workspace, and should just be deleted if they have been successfully integrated. 
+Running the command will remove these branches locally and remote as well. A local version of this command is available, and will just remove the local branches.
+Some branches can not be deleted, because git cannot detect if they have been integrated into the integration branch. That can be due to a rebase or squash. Those can be deleted with the 'force' flag. 
 `, ui.Format.Bold("cleanup")),
 	PreRun: func(cmd *cobra.Command, args []string) {
 		cmdperm.RequiredCurDirRepository()

cmd/config.go

@@ -1,34 +1,32 @@
 package cmd
 
 import (
+	"fmt"
+
+	"github.com/praqma/git-phlow/ui"
 	"github.com/spf13/cobra"
 )
 
 // configCmd represents the config command
 var configCmd = &cobra.Command{
 	Use:   "config",
 	Short: "bootstrap or show configuration",
-	Long: `
-git phlow uses gits own configuration, so all your configurations can be placed everywhere git config can get them.
-Best practice is to create a .gitconfig in your repository with your won configurations.
-
-Git phlow comes with internal defaults configured to work natively with github. So you can use git phlow
-without any configuration at all. If you want to customize it the default setting create an INI-block
-in a local .gitconfig, and make sure all mandatory fields are set.
+	Long: fmt.Sprintf(`
+%s config is the top-level command for showing and creating git-phlow .gitconfig files.
+Manipulating the individual key-value pairs is done by using git's build in 'git config'.
 
-To use a local .gitconfig file remember to add it to the config path, with this command
-	'git config --local include.path ../.gitconfig'
+When using a local '.gitconfig' file, you need to tell git that it should also look for configuration in the local workspace folder by adding: 
+'git config --local include.path ../.gitconfig'
 
 [phlow] is the default ini block
 
-Default configuration:
-	[phlow]
+[phlow]
     integration_branch = master
     remote = origin
     service = jira
     issue_url = https://my.jira.instance.com
     delivery_branch_prefix = ready
-`,
+`, ui.Format.Bold("config")),
 	Run: func(cmd *cobra.Command, args []string) {
 		cmd.Help()
 	},

cmd/deliver.go

@@ -2,6 +2,7 @@ package cmd
 
 import (
 	"fmt"
+
 	"github.com/praqma/git-phlow/cmd/cmdperm"
 	"github.com/praqma/git-phlow/options"
 	"github.com/praqma/git-phlow/phlow"
@@ -14,11 +15,13 @@ var deliverCmd = &cobra.Command{
 	Use:   "deliver [args]",
 	Short: "deliver changes to remote master",
 	Long: fmt.Sprintf(`
-%s pushes your committed changes to the remote repository.
-Deliver only runs if you are located on an issue branch created with workon.
-The delivered branch's name will prefixed 'ready/', so the integration services supporting the workflow can pick up your changes.
+%s is the command used to hand over the work you just commited with 'wrapup'. 
+checkout the issue branch you need to deliver and run the command. This will push local branch to the repository and prefixed it with 'ready/'. 
+On the repository it is ready to be integrated automatically into the integration branch, if a CI server is configured. 
+
+When delivered, local branches will be prefixed with 'delivered/'
 
-If you deliver with the 'local' option, the issue branch will be merged with your default branch, pushed to your remote's default branch and prefixed with 'delivered/'.
+using the '--local' option will integrate the branch locally and push the changes on the integration branch
 `, ui.Format.Bold("deliver")),
 	PreRun: func(cmd *cobra.Command, args []string) {
 		cmdperm.RequiredCurDirRepository()

cmd/issues.go

@@ -15,8 +15,9 @@ var issueCmd = &cobra.Command{
 	Use:   "issues",
 	Short: "list issues from Task management system",
 	Long: fmt.Sprintf(`
-%s lists the 30 next issues in your management system.
-Uses the configuration to decide target
+%s lists the first 30 issues from the connected issue management system. 
+The are not picked in any specific order, and for Jira they are not picked by any specific project. 
+The command is helpful for getting an overview of the next issues without leaving your terminal. The issue command uses the configuration 'issue-api' key-value pair to fetch the issues.
 `, ui.Format.Bold("issues")),
 	PreRun: func(cmd *cobra.Command, args []string) {
 		cmdperm.RequiredCurDirRepository()

cmd/mkalias.go

@@ -3,18 +3,17 @@ package cmd
 import (
 	"fmt"
 
+	"github.com/praqma/git-phlow/phlow"
 	"github.com/praqma/git-phlow/ui"
 	"github.com/spf13/cobra"
-	"github.com/praqma/git-phlow/phlow"
 )
 
 // mkaliasCmd represents the mkalias command
 var mkaliasCmd = &cobra.Command{
 	Use:   "mkalias",
 	Short: "create aliases for phlow commands",
 	Long: fmt.Sprintf(`
-%s creates aliases for the git phlow commands.
-This allows you to use 'git workon', rather than 'git phlow workon'.
+%s creates aliases for the git phlow commands. This allows you to use 'git workon', rather than 'git phlow workon'.
 The aliases are added to your global .gitconfig file.
 `, ui.Format.Bold("mkalias")),
 	Run: func(cmd *cobra.Command, args []string) {

cmd/show.go

@@ -1,18 +1,22 @@
 package cmd
 
 import (
-	"github.com/spf13/cobra"
+	"fmt"
+
 	"github.com/praqma/git-phlow/phlow"
+	"github.com/praqma/git-phlow/ui"
+	"github.com/spf13/cobra"
 )
 
 // showCmd represents the show command
 var showCmd = &cobra.Command{
 	Use:   "show",
 	Short: "shows configuration",
-	Long: `
-Shows a specified configuration block on your configuration file.
-If no arguments are passed it will show the internal default configuration
-	`,
+	Long: fmt.Sprintf(`
+%s shows the configuration of the specified INI block. 
+If no arguments are passed it will show the default configuration git phlow will use if no '-t' flag is set when a command is executed. 
+This is good to use when debugging. Look for the 'scope: internal', this means that git phlow is using the internal default block, and not one found in a custom .gitconfig file. 
+	`, ui.Format.Bold("show")),
 	Run: func(cmd *cobra.Command, args []string) {
 		phlow.Show(args)
 	},