feat: support SHA refs for plugin specs

Author: theZMC

docs/getting-started/configuration.md

@@ -61,12 +61,14 @@ Press ++prefix+shift+i++ to fetch and install all declared plugins.
 | Format | Example | Description |
 |---|---|---|
 | `user/repo` | `tmux-plugins/tmux-sensible` | GitHub shorthand |
-| `user/repo#branch` | `tmux-plugins/tmux-sensible#main` | Specific branch or tag |
+| `user/repo#ref` | `tmux-plugins/tmux-sensible#main` | Branch, tag, or commit SHA |
 | `https://github.com/user/repo.git` | `https://github.com/user/tmux-sensible.git` | Full HTTPS URL |
 | `[email protected]:user/plugin` | `[email protected]:tmux-plugins/tmux-sensible` | Full git SSH URL (GitHub) |
 | `[email protected]:user/plugin` | `[email protected]:user/tmux-plugin` | Non-GitHub git hosts |
 | `user/plugin alias=name` | `tmux-plugins/tmux-sensible alias=sensible` | Custom directory name |
 
+Branches track upstream and fast-forward on update. Tags and commit SHAs are pinned (detached HEAD; no automatic updates).
+
 For a list of compatible plugins, see the [tmux-plugins list](https://github.com/tmux-plugins/list).
 
 ## Next step

docs/usage/managing-plugins.md

@@ -23,6 +23,17 @@ See [Interactive TUI — Browse Screen](interactive-tui.md#browse-screen) for th
 !!! tip
     You can also install plugins directly from the [browse screen](interactive-tui.md#browse-screen) without manually editing your config.
 
+## Pinning a plugin
+
+Append `#<ref>` to pin a plugin to a tag or commit SHA. Pinned plugins are not fast-forwarded on update.
+
+```bash
+set -g @plugin 'catppuccin/tmux#v2.1.3'
+set -g @plugin 'tmux-plugins/tmux-sensible#abc1234'
+```
+
+To move to a new version, edit the ref in your config and run an update.
+
 ## Updating plugins
 
 Press ++prefix+shift+u++ to update plugins. The TUI opens and you can select which plugins to update.

internal/git/cli/cloner.go

@@ -2,6 +2,7 @@ package cli
 
 import (
 	"context"
+	"fmt"
 	"os/exec"
 	"strconv"
 	"strings"
@@ -18,12 +19,17 @@ func NewCloner() *Cloner {
 }
 
 func (c *Cloner) Clone(ctx context.Context, opts git.CloneOptions) error {
-	args := []string{"clone", "--single-branch"}
-	if opts.Depth > 0 {
-		args = append(args, "--depth", strconv.Itoa(opts.Depth))
-	}
-	if opts.Branch != "" {
-		args = append(args, "-b", opts.Branch)
+	isSHA := opts.Branch != "" && looksLikeCommitSHA(opts.Branch)
+
+	args := []string{"clone"}
+	if !isSHA {
+		args = append(args, "--single-branch")
+		if opts.Depth > 0 {
+			args = append(args, "--depth", strconv.Itoa(opts.Depth))
+		}
+		if opts.Branch != "" {
+			args = append(args, "-b", opts.Branch)
+		}
 	}
 	args = append(args, opts.URL, opts.Dir)
 
@@ -33,6 +39,15 @@ func (c *Cloner) Clone(ctx context.Context, opts git.CloneOptions) error {
 		return err
 	}
 
+	if isSHA {
+		checkoutCmd := exec.CommandContext(ctx, "git", "checkout", opts.Branch)
+		checkoutCmd.Dir = opts.Dir
+		checkoutCmd.Env = append(checkoutCmd.Environ(), "GIT_TERMINAL_PROMPT=0")
+		if out, err := checkoutCmd.CombinedOutput(); err != nil {
+			return fmt.Errorf("git checkout %s: %w: %s", opts.Branch, err, strings.TrimSpace(string(out)))
+		}
+	}
+
 	// Submodules are best-effort: a plugin whose submodule references an
 	// unreachable commit (see issue #14) should still install. The failure
 	// is surfaced via OnWarning so callers can notify the user.

internal/git/cli/cloner_test.go

@@ -68,6 +68,79 @@ func TestCloner_CloneWithBranch(t *testing.T) {
 	}
 }
 
+func TestCloner_CloneWithTag(t *testing.T) {
+	if testing.Short() {
+		t.Skip("skipping git CLI test in short mode")
+	}
+
+	bare := initBareRepo(t)
+
+	// Tag the bare repo's HEAD via a temporary working copy.
+	work := cloneLocal(t, bare)
+	runGit(t, work, "tag", "v1.0.0")
+	runGit(t, work, "push", "origin", "v1.0.0")
+
+	dst := filepath.Join(t.TempDir(), "cloned-tag")
+	cloner := gitcli.NewCloner()
+	err := cloner.Clone(context.Background(), git.CloneOptions{
+		URL:    bare,
+		Dir:    dst,
+		Branch: "v1.0.0",
+	})
+	if err != nil {
+		t.Fatalf("Clone with tag returned error: %v", err)
+	}
+
+	// README from the initial (tagged) commit must exist.
+	if _, err := os.Stat(filepath.Join(dst, "README")); err != nil {
+		t.Fatalf("expected README in cloned repo: %v", err)
+	}
+
+	// HEAD should be detached when cloning a tag.
+	symCmd := exec.CommandContext(context.Background(), "git", "-C", dst, "symbolic-ref", "-q", "HEAD")
+	if err := symCmd.Run(); err == nil {
+		t.Fatal("expected detached HEAD after cloning a tag")
+	}
+}
+
+func TestCloner_CloneWithCommitSHA(t *testing.T) {
+	if testing.Short() {
+		t.Skip("skipping git CLI test in short mode")
+	}
+
+	bare := initBareRepo(t)
+
+	// Capture the commit SHA of the bare repo's HEAD.
+	work := cloneLocal(t, bare)
+	revOut, err := exec.CommandContext(context.Background(),
+		"git", "-C", work, "rev-parse", "HEAD").Output()
+	if err != nil {
+		t.Fatalf("rev-parse HEAD failed: %v", err)
+	}
+	sha := strings.TrimSpace(string(revOut))
+
+	dst := filepath.Join(t.TempDir(), "cloned-sha")
+	cloner := gitcli.NewCloner()
+	err = cloner.Clone(context.Background(), git.CloneOptions{
+		URL:    bare,
+		Dir:    dst,
+		Branch: sha,
+	})
+	if err != nil {
+		t.Fatalf("Clone with commit SHA returned error: %v", err)
+	}
+
+	// HEAD must match the requested SHA exactly.
+	headOut, err := exec.CommandContext(context.Background(),
+		"git", "-C", dst, "rev-parse", "HEAD").Output()
+	if err != nil {
+		t.Fatalf("rev-parse HEAD on cloned repo failed: %v", err)
+	}
+	if got := strings.TrimSpace(string(headOut)); got != sha {
+		t.Fatalf("HEAD = %s, want %s", got, sha)
+	}
+}
+
 func TestCloner_CloneInvalidURL(t *testing.T) {
 	if testing.Short() {
 		t.Skip("skipping git CLI test in short mode")

internal/git/cli/fetcher.go

@@ -2,6 +2,7 @@ package cli
 
 import (
 	"context"
+	"errors"
 	"fmt"
 	"os/exec"
 	"strings"
@@ -15,6 +16,16 @@ func NewFetcher() *Fetcher {
 }
 
 func (c *Fetcher) IsOutdated(ctx context.Context, dir string) (bool, error) {
+	// Detached HEAD (exit 1) means the plugin is pinned to a tag/SHA; never outdated.
+	symCmd := exec.CommandContext(ctx, "git", "symbolic-ref", "-q", "HEAD")
+	symCmd.Dir = dir
+	if err := symCmd.Run(); err != nil {
+		var exitErr *exec.ExitError
+		if errors.As(err, &exitErr) && exitErr.ExitCode() == 1 {
+			return false, nil
+		}
+	}
+
 	fetchCmd := exec.CommandContext(ctx, "git", "fetch")
 	fetchCmd.Dir = dir
 	fetchCmd.Env = append(fetchCmd.Environ(), "GIT_TERMINAL_PROMPT=0")

internal/git/cli/fetcher_test.go

@@ -8,6 +8,29 @@ import (
 	gitcli "github.com/tmuxpack/tpack/internal/git/cli"
 )
 
+func TestFetcher_IsOutdatedDetachedHEAD(t *testing.T) {
+	if testing.Short() {
+		t.Skip("skipping git CLI test in short mode")
+	}
+
+	bare := initBareRepo(t)
+	clone := cloneLocal(t, bare)
+	sha := revParse(t, clone, "HEAD")
+	runGit(t, clone, "checkout", sha)
+
+	// Upstream moves forward; pinned plugin must still report not outdated.
+	addCommitToBare(t, bare, "after-pin.txt")
+
+	fetcher := gitcli.NewFetcher()
+	outdated, err := fetcher.IsOutdated(context.Background(), clone)
+	if err != nil {
+		t.Fatalf("IsOutdated returned error: %v", err)
+	}
+	if outdated {
+		t.Fatal("expected pinned (detached HEAD) repo to report not outdated")
+	}
+}
+
 func TestFetcher_IsOutdatedUpToDate(t *testing.T) {
 	if testing.Short() {
 		t.Skip("skipping git CLI test in short mode")

internal/git/cli/helpers_test.go

@@ -21,6 +21,13 @@ var (
 	_ git.Logger    = (*gitcli.Logger)(nil)
 )
 
+// Isolate git from the developer's user/system config.
+func TestMain(m *testing.M) {
+	os.Setenv("GIT_CONFIG_GLOBAL", "/dev/null")
+	os.Setenv("GIT_CONFIG_SYSTEM", "/dev/null")
+	os.Exit(m.Run())
+}
+
 // initBareRepo creates a bare git repository with a single commit on the
 // default branch. It returns the path to the bare repo directory.
 func initBareRepo(t *testing.T) string {

internal/git/cli/puller.go

@@ -17,22 +17,40 @@ func NewPuller() *Puller {
 }
 
 func (c *Puller) Pull(ctx context.Context, opts git.PullOptions) (string, error) {
+	pinned := false
 	if opts.Branch != "" {
+		// Best-effort: surface newly-published tags before checkout.
+		fetchCmd := exec.CommandContext(ctx, "git", "fetch", "--tags", "--force")
+		fetchCmd.Dir = opts.Dir
+		fetchCmd.Env = append(fetchCmd.Environ(), "GIT_TERMINAL_PROMPT=0")
+		_ = fetchCmd.Run()
+
 		checkoutCmd := exec.CommandContext(ctx, "git", "checkout", opts.Branch)
 		checkoutCmd.Dir = opts.Dir
 		checkoutCmd.Env = append(checkoutCmd.Environ(), "GIT_TERMINAL_PROMPT=0")
 		if err := checkoutCmd.Run(); err != nil {
 			return "", fmt.Errorf("git checkout %s: %w", opts.Branch, err)
 		}
+
+		// Detached HEAD means a tag/SHA pin; skip pull so HEAD stays put.
+		symCmd := exec.CommandContext(ctx, "git", "symbolic-ref", "-q", "HEAD")
+		symCmd.Dir = opts.Dir
+		symCmd.Env = append(symCmd.Environ(), "GIT_TERMINAL_PROMPT=0")
+		pinned = symCmd.Run() != nil
 	}
 
-	// git pull
-	pullCmd := exec.CommandContext(ctx, "git", "pull", "--rebase=false")
-	pullCmd.Dir = opts.Dir
-	pullCmd.Env = append(pullCmd.Environ(), "GIT_TERMINAL_PROMPT=0")
-	out, err := pullCmd.CombinedOutput()
-	if err != nil {
-		return strings.TrimSpace(string(out)), err
+	var out []byte
+	if pinned {
+		out = []byte(fmt.Sprintf("pinned to %s", opts.Branch))
+	} else {
+		pullCmd := exec.CommandContext(ctx, "git", "pull", "--rebase=false")
+		pullCmd.Dir = opts.Dir
+		pullCmd.Env = append(pullCmd.Environ(), "GIT_TERMINAL_PROMPT=0")
+		var err error
+		out, err = pullCmd.CombinedOutput()
+		if err != nil {
+			return strings.TrimSpace(string(out)), err
+		}
 	}
 
 	// Submodules are best-effort: a plugin whose submodule references an

internal/git/cli/puller_test.go

@@ -3,7 +3,9 @@ package cli_test
 import (
 	"context"
 	"os"
+	"os/exec"
 	"path/filepath"
+	"strings"
 	"testing"
 
 	"github.com/tmuxpack/tpack/internal/git"
@@ -103,3 +105,87 @@ func TestPuller_PullWithBranch(t *testing.T) {
 		t.Fatalf("expected feature.txt after pull with branch: %v", err)
 	}
 }
+
+// revParse returns the resolved SHA of HEAD (or any ref) for a repo.
+func revParse(t *testing.T, dir, ref string) string {
+	t.Helper()
+	out, err := exec.CommandContext(context.Background(),
+		"git", "-C", dir, "rev-parse", ref).Output()
+	if err != nil {
+		t.Fatalf("rev-parse %s in %s: %v", ref, dir, err)
+	}
+	return strings.TrimSpace(string(out))
+}
+
+func TestPuller_PullSkippedOnTag(t *testing.T) {
+	if testing.Short() {
+		t.Skip("skipping git CLI test in short mode")
+	}
+
+	bare := initBareRepo(t)
+
+	// Tag the initial commit and push the tag upstream.
+	tagger := cloneLocal(t, bare)
+	runGit(t, tagger, "tag", "v1.0.0")
+	runGit(t, tagger, "push", "origin", "v1.0.0")
+	tagSHA := revParse(t, tagger, "v1.0.0")
+
+	// Clone fresh, then check out the tag so HEAD is detached.
+	clone := cloneLocal(t, bare)
+	runGit(t, clone, "fetch", "--tags")
+	runGit(t, clone, "checkout", "v1.0.0")
+
+	// Push a new commit upstream so a naive `git pull` would fast-forward.
+	addCommitToBare(t, bare, "after-tag.txt")
+
+	puller := gitcli.NewPuller()
+	_, err := puller.Pull(context.Background(), git.PullOptions{
+		Dir:    clone,
+		Branch: "v1.0.0",
+	})
+	if err != nil {
+		t.Fatalf("Pull pinned to tag returned error: %v", err)
+	}
+
+	if got := revParse(t, clone, "HEAD"); got != tagSHA {
+		t.Fatalf("HEAD moved off tag: HEAD=%s, want %s", got, tagSHA)
+	}
+
+	// The new file must NOT be present; pull should have been skipped.
+	if _, err := os.Stat(filepath.Join(clone, "after-tag.txt")); err == nil {
+		t.Fatal("after-tag.txt should not exist; pull should have been skipped on detached HEAD")
+	}
+}
+
+func TestPuller_PullSkippedOnCommitSHA(t *testing.T) {
+	if testing.Short() {
+		t.Skip("skipping git CLI test in short mode")
+	}
+
+	bare := initBareRepo(t)
+
+	// Capture the initial commit SHA and check it out (detached HEAD).
+	clone := cloneLocal(t, bare)
+	sha := revParse(t, clone, "HEAD")
+	runGit(t, clone, "checkout", sha)
+
+	// Push a new commit upstream so a naive `git pull` would fast-forward.
+	addCommitToBare(t, bare, "after-sha.txt")
+
+	puller := gitcli.NewPuller()
+	_, err := puller.Pull(context.Background(), git.PullOptions{
+		Dir:    clone,
+		Branch: sha,
+	})
+	if err != nil {
+		t.Fatalf("Pull pinned to SHA returned error: %v", err)
+	}
+
+	if got := revParse(t, clone, "HEAD"); got != sha {
+		t.Fatalf("HEAD moved off pinned SHA: HEAD=%s, want %s", got, sha)
+	}
+
+	if _, err := os.Stat(filepath.Join(clone, "after-sha.txt")); err == nil {
+		t.Fatal("after-sha.txt should not exist; pull should have been skipped on detached HEAD")
+	}
+}

internal/git/cli/refs.go

@@ -0,0 +1,9 @@
+package cli
+
+import "regexp"
+
+var commitSHArgx = regexp.MustCompile(`^[0-9a-fA-F]{7,40}$`)
+
+func looksLikeCommitSHA(ref string) bool {
+	return commitSHArgx.MatchString(ref)
+}