From 872a94d1c58e086674fa70caf31d91e66aee4204 Mon Sep 17 00:00:00 2001
From: Ilya Grigoriev <ilyagr@users.noreply.github.com>
Date: Mon, 11 Dec 2023 22:00:03 -0800
Subject: [PATCH] cli `branch track`, `branch untrack`: document remote
 branches in `jj help`

This tries to clarify the fact that the branches must be remote and the syntax
for specifying them as globs.

Cc @yuja, https://github.com/martinvonz/jj/pull/2625#discussion_r1423379351

Here is the result (excerpt):

```
$ jj branch track --help
Start tracking given remote branches

A tracking remote branch will be imported as a local branch of the same name. Changes to it
will propagate to the existing local branch on future pulls.

Usage: jj branch track [OPTIONS] <BRANCH@REMOTE>...

Arguments:
  <BRANCH@REMOTE>...
          Remote branches to track

          By default, the specified name matches exactly. Use `glob:` prefix to select
          branches by wildcard pattern. For details, see
          https://github.com/martinvonz/jj/blob/main/docs/revsets.md#string-patterns.

          Examples: branch@remote, glob:main@*, glob:jjfan-*@upstream
```
---
 cli/src/commands/branch.rs       | 8 ++++++--
 cli/tests/test_branch_command.rs | 2 +-
 2 files changed, 7 insertions(+), 3 deletions(-)

diff --git a/cli/src/commands/branch.rs b/cli/src/commands/branch.rs
index a06273407..ffbf684a5 100644
--- a/cli/src/commands/branch.rs
+++ b/cli/src/commands/branch.rs
@@ -150,7 +150,9 @@ pub struct BranchTrackArgs {
     /// By default, the specified name matches exactly. Use `glob:` prefix to
     /// select branches by wildcard pattern. For details, see
     /// https://github.com/martinvonz/jj/blob/main/docs/revsets.md#string-patterns.
-    #[arg(required = true)]
+    ///
+    /// Examples: branch@remote, glob:main@*, glob:jjfan-*@upstream
+    #[arg(required = true, value_name = "BRANCH@REMOTE")]
     pub names: Vec<RemoteBranchNamePattern>,
 }
 
@@ -165,7 +167,9 @@ pub struct BranchUntrackArgs {
     /// By default, the specified name matches exactly. Use `glob:` prefix to
     /// select branches by wildcard pattern. For details, see
     /// https://github.com/martinvonz/jj/blob/main/docs/revsets.md#string-patterns.
-    #[arg(required = true)]
+    ///
+    /// Examples: branch@remote, glob:main@*, glob:jjfan-*@upstream
+    #[arg(required = true, value_name = "BRANCH@REMOTE")]
     pub names: Vec<RemoteBranchNamePattern>,
 }
 
diff --git a/cli/tests/test_branch_command.rs b/cli/tests/test_branch_command.rs
index 16c78892c..43fd21a7b 100644
--- a/cli/tests/test_branch_command.rs
+++ b/cli/tests/test_branch_command.rs
@@ -812,7 +812,7 @@ fn test_branch_track_untrack_patterns() {
     test_env.jj_cmd_ok(&repo_path, &["branch", "create", "main"]);
     insta::assert_snapshot!(
         test_env.jj_cmd_cli_error(&repo_path, &["branch", "track", "main"]), @r###"
-    error: invalid value 'main' for '<NAMES>...': remote branch must be specified in branch@remote form
+    error: invalid value 'main' for '<BRANCH@REMOTE>...': remote branch must be specified in branch@remote form
 
     For more information, try '--help'.
     "###);