feat: add ability to checkout a repo at a certain commit (#2555)

This is needed for the `update-image` logic -- we plan to checkout the
protos repo at the previously generated commit.

Towards #2546

Author: chingor13

internal/gitrepo/gitrepo.go

@@ -54,6 +54,7 @@ type Repository interface {
 	Restore(paths []string) error
 	CleanUntracked(paths []string) error
 	pushRefSpec(refSpec string) error
+	Checkout(commitHash string) error
 }
 
 const RootPath = "."
@@ -651,3 +652,14 @@ func (r *LocalRepository) CleanUntracked(paths []string) error {
 
 	return nil
 }
+
+// Checkout checks out the local repository at the provided git SHA.
+func (r *LocalRepository) Checkout(commitSha string) error {
+	worktree, err := r.repo.Worktree()
+	if err != nil {
+		return err
+	}
+	return worktree.Checkout(&git.CheckoutOptions{
+		Hash: plumbing.NewHash(commitSha),
+	})
+}

system_test.go

@@ -20,6 +20,7 @@ import (
 	"log/slog"
 	"os"
 	"path"
+	"path/filepath"
 	"strings"
 	"testing"
 	"time"
@@ -438,3 +439,59 @@ func TestCreateRelease(t *testing.T) {
 		t.Fatalf("release body mismatch (-want + got):\n%s", diff)
 	}
 }
+
+func TestGitCheckout(t *testing.T) {
+	t.Parallel()
+	for _, test := range []struct {
+		name    string
+		sha     string
+		want    string
+		wantErr bool
+	}{
+		{
+			name: "known SHA",
+			// v0.3.0 release
+			sha:  "2e230f309505db42ce8becb0f3946d608a11a61c",
+			want: "chore: librarian release pull request: 20250925T070206Z (#2356)",
+		},
+		{
+			name:    "unknown SHA",
+			sha:     "should not exist",
+			wantErr: true,
+		},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			t.Parallel()
+			repo, err := gitrepo.NewRepository(&gitrepo.RepositoryOptions{
+				Dir:          filepath.Join(t.TempDir(), "librarian"),
+				MaybeClone:   true,
+				RemoteURL:    "https://github.com/googleapis/librarian",
+				RemoteBranch: "main",
+			})
+			if err != nil {
+				t.Fatalf("error cloning repository, %v", err)
+			}
+
+			err = repo.Checkout(test.sha)
+
+			if test.wantErr {
+				if err == nil {
+					t.Fatal("Checkout() expected to return error")
+				}
+				return
+			}
+
+			if err != nil {
+				t.Fatalf("Checkout() unexpected error: %v", err)
+			}
+
+			headSha, err := repo.HeadHash()
+			if diff := cmp.Diff(test.sha, headSha); diff != "" {
+				t.Fatalf("Checkout() mismatch (-want +got):\n%s", diff)
+			}
+			if err != nil {
+				t.Fatalf("Checkout() unexpected error fetching HeadHash: %v", err)
+			}
+		})
+	}
+}