feat(init): add -b/--branch option

Author: jpgrayson

completion/stgit.zsh

@@ -732,6 +732,7 @@ _stg-import() {
 _stg-init() {
     local -a subcmd_args
     __stg_add_args_help
+    __stg_add_args_branch
     _arguments -s $subcmd_args
 }
 

src/cmd/init.rs

@@ -6,6 +6,8 @@ use anyhow::Result;
 use clap::ArgMatches;
 
 use crate::{
+    argset,
+    branchloc::BranchLocator,
     ext::RepositoryExtended,
     stack::{InitializationPolicy, Stack},
 };
@@ -19,25 +21,36 @@ pub(super) const STGIT_COMMAND: super::StGitCommand = super::StGitCommand {
 
 fn make() -> clap::Command {
     clap::Command::new(STGIT_COMMAND.name)
-        .about("Initialize a StGit stack on current branch")
+        .about("Initialize a StGit stack on a branch")
         .long_about(
-            "Initialize a StGit stack on the current branch.\n\
+            "Initialize a StGit stack on a branch.\n\
              \n\
-             A branch must be initialized with a StGit stack before patches may be \
-             created with 'stg new', imported with 'stg import', or picked with 'stg \
-             pick'.\n\
+             Initializing a branch with a StGit stack commits initial, empty stack \
+             state for the branch to the repository. Theses stack metadata commits are \
+             tracked by the `refs/stacks/<branch>` reference. Updated stack state is \
+             committed by each StGit command that modifies the stack. StGit users do \
+             not have to do anything with the `refs/stacks/<branch>` ref directly.\n\
              \n\
-             The branch and its git repository must already exist and contain at least \
-             one commit before initializing a StGit stack. Branches created with `stg \
-             branch --create` are automatically initialized.\n\
+             Some StGit commands, such as `stg new` and `stg uncommit`, will \
+             automatically initialize the stack, so it is often not necessary to \
+             explicitly initialize the stack on a branch. Also, branches created with \
+             `stg branch --create` are automatically initialized.\n\
+             \n\
+             The branch must already exist and point to a commit before initializing a \
+             StGit stack.\n\
              \n\
              StGit stack metadata can be deinitialized from a branch using `stg branch \
              --cleanup`. See 'stg branch' for more details.",
         )
+        .arg(argset::branch_arg())
 }
 
-fn run(_: &ArgMatches) -> Result<()> {
+fn run(matches: &ArgMatches) -> Result<()> {
     let repo = gix::Repository::open()?;
-    Stack::current(&repo, InitializationPolicy::MustInitialize)?;
+    Stack::from_branch_locator(
+        &repo,
+        matches.get_one::<BranchLocator>("branch"),
+        InitializationPolicy::MustInitialize,
+    )?;
     Ok(())
 }