docs: improve documentation and command descriptions for clarity

- Update flag descriptions for better clarity and consistency
- Change commit message descriptions to be more descriptive
- Improve comments for better readability and understanding
- Modify prompt command to include detailed usage and flag information
- Refine hook command descriptions for better clarity
- Update version command to include commit information

Signed-off-by: Bo-Yi Wu <[email protected]>

Author: appleboy

cmd/commit.go

@@ -43,34 +43,34 @@ var (
 )
 
 func init() {
-	commitCmd.PersistentFlags().StringP("file", "f", "", "commit message file")
-	commitCmd.PersistentFlags().BoolVar(&preview, "preview", false, "preview commit message")
+	commitCmd.PersistentFlags().StringP("file", "f", "", "output file for commit message")
+	commitCmd.PersistentFlags().BoolVar(&preview, "preview", false, "preview commit message before committing")
 	commitCmd.PersistentFlags().IntVar(&diffUnified, "diff_unified", 3,
-		"generate diffs with <n> lines of context, default is 3")
-	commitCmd.PersistentFlags().StringVar(&commitModel, "model", "gpt-4o", "select openai model")
-	commitCmd.PersistentFlags().StringVar(&commitLang, "lang", "en", "summarizing language uses English by default")
+		"generate diffs with <n> lines of context (default: 3)")
+	commitCmd.PersistentFlags().StringVar(&commitModel, "model", "gpt-4o", "OpenAI model to use for generation")
+	commitCmd.PersistentFlags().StringVar(&commitLang, "lang", "en", "output language for the commit message (default: English)")
 	commitCmd.PersistentFlags().StringSliceVar(&excludeList, "exclude_list", []string{},
-		"exclude file from git diff command")
-	commitCmd.PersistentFlags().StringVar(&httpsProxy, "proxy", "", "http proxy")
-	commitCmd.PersistentFlags().StringVar(&socksProxy, "socks", "", "socks proxy")
-	commitCmd.PersistentFlags().StringVar(&templateFile, "template_file", "", "git commit message file")
-	commitCmd.PersistentFlags().StringVar(&templateString, "template_string", "", "git commit message string")
-	commitCmd.PersistentFlags().StringSliceVar(&templateVars, "template_vars", []string{}, "template variables")
-	commitCmd.PersistentFlags().StringVar(&templateVarsFile, "template_vars_file", "", "template variables file")
+		"files to exclude from git diff")
+	commitCmd.PersistentFlags().StringVar(&httpsProxy, "proxy", "", "HTTP proxy URL")
+	commitCmd.PersistentFlags().StringVar(&socksProxy, "socks", "", "SOCKS proxy URL")
+	commitCmd.PersistentFlags().StringVar(&templateFile, "template_file", "", "template file for commit message format")
+	commitCmd.PersistentFlags().StringVar(&templateString, "template_string", "", "inline template string for commit message format")
+	commitCmd.PersistentFlags().StringSliceVar(&templateVars, "template_vars", []string{}, "custom variables for templates")
+	commitCmd.PersistentFlags().StringVar(&templateVarsFile, "template_vars_file", "", "file containing template variables")
 	commitCmd.PersistentFlags().BoolVar(&commitAmend, "amend", false,
-		"replace the tip of the current branch by creating a new commit.")
-	commitCmd.PersistentFlags().DurationVarP(&timeout, "timeout", "t", defaultTimeout, "request timeout")
+		"amend the previous commit instead of creating a new one")
+	commitCmd.PersistentFlags().DurationVarP(&timeout, "timeout", "t", defaultTimeout, "API request timeout duration")
 	commitCmd.PersistentFlags().BoolVar(&promptOnly, "prompt_only", false,
-		"show prompt only, don't send request to openai")
+		"display the prompt without sending to OpenAI")
 	commitCmd.PersistentFlags().BoolVar(&noConfirm, "no_confirm", false,
-		"skip confirmation prompt")
+		"skip all confirmation prompts")
 	_ = viper.BindPFlag("output.file", commitCmd.PersistentFlags().Lookup("file"))
 }
 
 // commitCmd represents the commit command.
 var commitCmd = &cobra.Command{
 	Use:   "commit",
-	Short: "Auto generate commit message",
+	Short: "Automatically generate commit message",
 	RunE: func(cmd *cobra.Command, args []string) error {
 		if err := check(); err != nil {
 			return err
@@ -92,25 +92,25 @@ var commitCmd = &cobra.Command{
 			viper.Set("openai.timeout", timeout)
 		}
 
-		// check provider
+		// Check provider
 		provider := core.Platform(viper.GetString("openai.provider"))
 		client, err := GetClient(cmd.Context(), provider)
 		if err != nil && !promptOnly {
 			return err
 		}
 
 		currentModel := viper.GetString("openai.model")
-		color.Green("Summarize the commit message use " + currentModel + " model")
+		color.Green("Summarizing commit message using " + currentModel + " model")
 
 		data := util.Data{}
-		// add template vars
+		// Add template variables
 		if vars := util.ConvertToMap(templateVars); len(vars) > 0 {
 			for k, v := range vars {
 				data[k] = v
 			}
 		}
 
-		// add template vars from file
+		// Add template variables from file
 		if templateVarsFile != "" {
 			allENV, err := godotenv.Read(templateVarsFile)
 			if err != nil {
@@ -121,7 +121,7 @@ var commitCmd = &cobra.Command{
 			}
 		}
 
-		// Get code review message from diff datas
+		// Get code review message from diff data
 		if _, ok := data[prompt.SummarizeMessageKey]; !ok {
 			out, err := util.GetTemplateByString(
 				prompt.SummarizeFileDiffTemplate,
@@ -133,16 +133,16 @@ var commitCmd = &cobra.Command{
 				return err
 			}
 
-			// determine if the user wants to use the prompt only
+			// Determine if the user wants to use the prompt only
 			if promptOnly {
 				color.Yellow("====================Prompt========================")
 				color.Yellow("\n" + strings.TrimSpace(out) + "\n\n")
 				color.Yellow("==================================================")
 				return nil
 			}
 
-			// Get summarize comment from diff datas
-			color.Cyan("We are trying to summarize a git diff")
+			// Get summarized comment from diff data
+			color.Cyan("Summarizing git diff...")
 			resp, err := client.Completion(cmd.Context(), out)
 			if err != nil {
 				return err
@@ -151,7 +151,7 @@ var commitCmd = &cobra.Command{
 			color.Magenta(resp.Usage.String())
 		}
 
-		// Get summarize title from diff datas
+		// Get summarized title from diff data
 		if _, ok := data[prompt.SummarizeTitleKey]; !ok {
 			out, err := util.GetTemplateByString(
 				prompt.SummarizeTitleTemplate,
@@ -163,16 +163,16 @@ var commitCmd = &cobra.Command{
 				return err
 			}
 
-			// Get summarize title from diff datas
-			color.Cyan("We are trying to summarize a title for pull request")
+			// Generate title for pull request
+			color.Cyan("Generating title for pull request...")
 			resp, err := client.Completion(cmd.Context(), out)
 			if err != nil {
 				return err
 			}
 			summarizeTitle := resp.Content
 			color.Magenta(resp.Usage.String())
 
-			// lowercase the first character of first word of the commit message and remove last period
+			// Lowercase the first character of first word of the commit message and remove the trailing period
 			summarizeTitle = strings.TrimRight(strings.ToLower(string(summarizeTitle[0]))+summarizeTitle[1:], ".")
 			data[prompt.SummarizeTitleKey] = strings.TrimSpace(summarizeTitle)
 		}
@@ -187,7 +187,7 @@ var commitCmd = &cobra.Command{
 			if err != nil {
 				return err
 			}
-			message := "We are trying to get conventional commit prefix"
+			message := "Generating conventional commit prefix"
 			summaryPrix := ""
 			color.Cyan(message + " (Tools)")
 			resp, err := client.GetSummaryPrefix(cmd.Context(), out)
@@ -244,8 +244,8 @@ var commitCmd = &cobra.Command{
 				return err
 			}
 
-			// translate a git commit message
-			color.Cyan("We are trying to translate a git commit message to " + prompt.GetLanguage(viper.GetString("output.lang")) + " language")
+			// Translate git commit message
+			color.Cyan("Translating git commit message to " + prompt.GetLanguage(viper.GetString("output.lang")))
 			resp, err := client.Completion(cmd.Context(), out)
 			if err != nil {
 				return err
@@ -254,7 +254,7 @@ var commitCmd = &cobra.Command{
 			commitMessage = resp.Content
 		}
 
-		// unescape html entities in commit message
+		// Unescape HTML entities in commit message
 		commitMessage = html.UnescapeString(commitMessage)
 		commitMessage = strings.TrimSpace(commitMessage)
 
@@ -271,8 +271,8 @@ var commitCmd = &cobra.Command{
 			}
 			outputFile = path.Join(strings.TrimSpace(out), "COMMIT_EDITMSG")
 		}
-		color.Cyan("Write the commit message to " + outputFile + " file")
-		// write commit message to git staging file
+		color.Cyan("Writing commit message to " + outputFile)
+		// Write commit message to git staging file
 		err = os.WriteFile(outputFile, []byte(commitMessage), 0o600)
 		if err != nil {
 			return err
@@ -283,7 +283,7 @@ var commitCmd = &cobra.Command{
 			if noConfirm {
 				return nil
 			}
-			if ready, err := confirmation.New("Commit preview summary?", confirmation.Yes).RunPrompt(); err != nil || !ready {
+			if ready, err := confirmation.New("Commit this preview summary?", confirmation.Yes).RunPrompt(); err != nil || !ready {
 				if err != nil {
 					return err
 				}
@@ -293,7 +293,7 @@ var commitCmd = &cobra.Command{
 
 		// Handle commit message change prompt when confirmation is enabled
 		if !noConfirm {
-			if change, err := confirmation.New("Do you want to change the commit message?", confirmation.No).RunPrompt(); err != nil {
+			if change, err := confirmation.New("Do you want to modify the commit message?", confirmation.No).RunPrompt(); err != nil {
 				return err
 			} else if change {
 				m := initialPrompt(commitMessage)
@@ -306,8 +306,8 @@ var commitCmd = &cobra.Command{
 			}
 		}
 
-		// git commit automatically
-		color.Cyan("Git record changes to the repository")
+		// Commit changes to repository
+		color.Cyan("Recording changes to the repository")
 		output, err := g.Commit(commitMessage)
 		if err != nil {
 			return err

cmd/hook.go

@@ -12,24 +12,24 @@ func init() {
 	hookCmd.AddCommand(hookUninstallCmd)
 }
 
-// hookCmd represents the command for installing/uninstalling the prepare-commit-msg hook.
+// hookCmd represents the command for managing the prepare-commit-msg git hook.
 var hookCmd = &cobra.Command{
 	Use:   "hook",
-	Short: "install/uninstall git prepare-commit-msg hook",
+	Short: "Manage git prepare-commit-msg hook",
 }
 
 // hookInstallCmd installs the prepare-commit-msg hook.
 var hookInstallCmd = &cobra.Command{
 	Use:   "install",
-	Short: "install git prepare-commit-msg hook",
+	Short: "Install git prepare-commit-msg hook",
 	RunE: func(cmd *cobra.Command, args []string) error {
 		g := git.New()
 
 		if err := g.InstallHook(); err != nil {
 			return err
 		}
-		color.Green("Install git hook: prepare-commit-msg successfully")
-		color.Green("You can see the hook file: .git/hooks/prepare-commit-msg")
+		color.Green("Git hook 'prepare-commit-msg' installed successfully")
+		color.Green("Hook file location: .git/hooks/prepare-commit-msg")
 
 		return nil
 	},
@@ -38,14 +38,14 @@ var hookInstallCmd = &cobra.Command{
 // hookUninstallCmd uninstalls the prepare-commit-msg hook.
 var hookUninstallCmd = &cobra.Command{
 	Use:   "uninstall",
-	Short: "uninstall git prepare-commit-msg hook",
+	Short: "Uninstall git prepare-commit-msg hook",
 	RunE: func(cmd *cobra.Command, args []string) error {
 		g := git.New()
 
 		if err := g.UninstallHook(); err != nil {
 			return err
 		}
-		color.Green("Remove git hook: prepare-commit-msg successfully")
+		color.Green("Git hook 'prepare-commit-msg' removed successfully")
 		return nil
 	},
 }

cmd/prompt.go

@@ -15,7 +15,7 @@ var loadPromptData bool
 
 func init() {
 	promptCmd.PersistentFlags().BoolVar(&loadPromptData, "load", false,
-		"load default prompt data")
+		"Load default prompt templates into your configuration")
 }
 
 var defaultPromptDataKeys = []string{
@@ -25,15 +25,32 @@ var defaultPromptDataKeys = []string{
 	prompt.ConventionalCommitTemplate,
 }
 
-// promptCmd represents the command to load default prompt data.
-// It uses the "prompt" keyword and provides a short description: "load default prompt data".
-// The command executes the RunE function which checks if the loadPromptData flag is set.
-// If set, it prompts the user for confirmation to load the default prompt data, which will overwrite existing data.
-// Upon confirmation, it retrieves the prompt folder path from the configuration and saves the default prompt data keys to the specified folder.
-// If any error occurs during the process, it returns the error.
+// promptCmd is a Cobra command to load default prompt data into a specified folder.
+// It provides functionality to populate the prompt folder with predefined templates.
+//
+// Usage:
+//
+//	codegpt prompt [flags]
+//
+// Flags:
+//
+//	-l, --load    load default prompt data into the specified folder (required to execute)
+//
+// This command will:
+// 1. Check if the load flag is enabled
+// 2. Get the prompt folder path from configuration
+// 3. Ask for user confirmation before proceeding with data loading
+// 4. Save all default prompt templates to the specified folder
+//
+// The command requires explicit confirmation from the user as it may overwrite existing prompt data.
 var promptCmd = &cobra.Command{
 	Use:   "prompt",
-	Short: "load default prompt data",
+	Short: "Load default prompt templates",
+	Long: `Load default prompt templates into your configuration directory.
+	
+This command allows you to initialize or update your prompt templates with the default set provided by CodeGPT.
+When executed with the --load flag, it will copy all standard templates to your configured prompt folder.`,
+	Example: "  codegpt prompt --load",
 	RunE: func(cmd *cobra.Command, args []string) error {
 		if !loadPromptData {
 			return nil

cmd/review.go

@@ -19,16 +19,16 @@ var maxTokens int
 
 func init() {
 	reviewCmd.PersistentFlags().IntVar(&diffUnified, "diff_unified", 3,
-		"generate diffs with <n> lines of context, default is 3")
+		"Generate diffs with <n> lines of context (default: 3)")
 	reviewCmd.PersistentFlags().IntVar(&maxTokens, "max_tokens", 300,
-		"the maximum number of tokens to generate in the chat completion.")
-	reviewCmd.PersistentFlags().StringVar(&commitModel, "model", "gpt-4o", "select openai model")
-	reviewCmd.PersistentFlags().StringVar(&commitLang, "lang", "en", "summarizing language uses English by default")
-	reviewCmd.PersistentFlags().StringSliceVar(&excludeList, "exclude_list", []string{}, "exclude file from git diff command")
+		"Maximum number of tokens to generate in the chat completion")
+	reviewCmd.PersistentFlags().StringVar(&commitModel, "model", "gpt-4o", "OpenAI model to use")
+	reviewCmd.PersistentFlags().StringVar(&commitLang, "lang", "en", "Language for summarization (default: English)")
+	reviewCmd.PersistentFlags().StringSliceVar(&excludeList, "exclude_list", []string{}, "Files to exclude from git diff")
 	reviewCmd.PersistentFlags().BoolVar(&commitAmend, "amend", false,
-		"replace the tip of the current branch by creating a new commit.")
+		"Replace the tip of the current branch by creating a new commit")
 	reviewCmd.PersistentFlags().BoolVar(&promptOnly, "prompt_only", false,
-		"show prompt only, don't send request to openai")
+		"Show prompt only without sending request to OpenAI")
 }
 
 var reviewCmd = &cobra.Command{

cmd/textarea.go

@@ -84,8 +84,8 @@ func (m model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
 
 func (m model) View() string {
 	return fmt.Sprintf(
-		"Please confirm the following commit message:\n\n%s\n\n%s",
+		"Please review and confirm your commit message:\n\n%s\n\n%s",
 		m.textarea.View(),
-		"(Press Ctrl+C to continue.)",
+		"(Press Ctrl+C to continue)",
 	) + "\n\n"
 }

cmd/version.go

@@ -13,7 +13,7 @@ var (
 
 var versionCmd = &cobra.Command{
 	Use:   "version",
-	Short: "Print the version number",
+	Short: "Print the application version and commit information",
 	Run: func(cmd *cobra.Command, args []string) {
 		fmt.Println("version:", Version, "commit:", Commit)
 	},