docs(submit): Adjust some messaging to be more forge-agnostic

Author: arxanas

git-branchless-opts/src/lib.rs

@@ -361,11 +361,12 @@ pub struct SmartlogArgs {
 /// The Git hosting provider to use, called a "forge".
 #[derive(Clone, Debug, ValueEnum)]
 pub enum ForgeKind {
-    /// Force-push branches to the default push remote.
+    /// Force-push branches to the default push remote. You can configure the
+    /// default push remote with `git config remote.pushDefault <remote>`.
     Branch,
 
     /// Force-push branches to the remote and create a pull request for each
-    /// branch using the `gh` command-line tool.
+    /// branch using the `gh` command-line tool. WARNING: likely buggy!
     Github,
 
     /// Submit code reviews to Phabricator using the `arc` command-line tool.
@@ -375,42 +376,45 @@ pub enum ForgeKind {
 /// Push commits to a remote.
 #[derive(Debug, Parser)]
 pub struct SubmitArgs {
-    /// If there is no remote branch for a given local branch, create the
-    /// remote branch by pushing the local branch to the default push
-    /// remote.
-    ///
-    /// You can configure the default push remote with `git config
-    /// remote.pushDefault <remote>`.
-    #[clap(action, short = 'c', long = "create")]
-    pub create: bool,
-
-    /// If the remote supports it, create code reviews in "draft" mode.
-    #[clap(action, short = 'd', long = "draft")]
-    pub draft: bool,
-
-    /// What kind of execution strategy to use for tools which need access to the working copy.
-    #[clap(short = 's', long = "strategy")]
-    pub strategy: Option<TestExecutionStrategy>,
-
-    /// The commits to push. All branches attached to those commits will be
-    /// pushed.
+    /// The commits to push to the forge. Unless `--create` is passed, this will
+    /// only push commits that already have associated remote objects on the
+    /// forge.
     #[clap(value_parser, default_value = "stack()")]
     pub revsets: Vec<Revset>,
 
     /// Options for resolving revset expressions.
     #[clap(flatten)]
     pub resolve_revset_options: ResolveRevsetOptions,
 
-    /// The Git hosting provider to use.
+    /// The Git hosting provider to use, called a "forge". If not provided, an
+    /// attempt will be made to automatically detect the forge used by the
+    /// repository. If no forge can be detected, will fall back to the "branch"
+    /// forge.
     #[clap(short = 'F', long = "forge")]
-    pub forge: Option<ForgeKind>,
+    pub forge_kind: Option<ForgeKind>,
 
-    /// An optional message to include with the create or update operation.
+    /// If there is no associated remote commit or code review object for a
+    /// given local commit, create the remote object by pushing the local commit
+    /// to the forge.
+    #[clap(action, short = 'c', long = "create")]
+    pub create: bool,
+
+    /// If the forge supports it, create code reviews in "draft" mode.
+    #[clap(action, short = 'd', long = "draft")]
+    pub draft: bool,
+
+    /// If the forge supports it, an optional message to include with the create
+    /// or update operation.
     #[clap(short = 'm', long = "message")]
     pub message: Option<String>,
 
+    /// If the forge supports it and uses a tool that needs access to the
+    /// working copy, what kind of execution strategy to use.
+    #[clap(short = 's', long = "strategy")]
+    pub execution_strategy: Option<TestExecutionStrategy>,
+
     /// Don't push or create anything. Instead, report what would be pushed or
-    /// created. (Still triggers a fetch.)
+    /// created. (This may still trigger fetching information from the forge.)
     #[clap(short = 'n', long = "dry-run")]
     pub dry_run: bool,
 }

git-branchless-submit/src/lib.rs

@@ -186,25 +186,25 @@ pub fn command_main(ctx: CommandContext, args: SubmitArgs) -> EyreExitOr<()> {
         git_run_info,
     } = ctx;
     let SubmitArgs {
-        create,
-        draft,
-        strategy,
         revsets,
         resolve_revset_options,
-        forge,
+        forge_kind,
+        create,
+        draft,
         message,
+        execution_strategy,
         dry_run,
     } = args;
     submit(
         &effects,
         &git_run_info,
         revsets,
         &resolve_revset_options,
+        forge_kind,
         create,
         draft,
-        strategy,
-        forge,
         message,
+        execution_strategy,
         dry_run,
     )
 }
@@ -214,11 +214,11 @@ fn submit(
     git_run_info: &GitRunInfo,
     revsets: Vec<Revset>,
     resolve_revset_options: &ResolveRevsetOptions,
+    forge_kind: Option<ForgeKind>,
     create: bool,
     draft: bool,
-    execution_strategy: Option<TestExecutionStrategy>,
-    forge_kind: Option<ForgeKind>,
     message: Option<String>,
+    execution_strategy: Option<TestExecutionStrategy>,
     dry_run: bool,
 ) -> EyreExitOr<()> {
     let repo = Repo::from_current_dir()?;