feat: add tag selection for worktree creation

Author: wasabeef

CLAUDE.md

@@ -76,10 +76,11 @@ source /path/to/git-workers/shell/gw.sh
 - Security validation to prevent path traversal attacks
 - Follows same discovery priority as configuration files
 
-### Branch Option Simplification
+### Branch Option Enhancement
 
-- Reduced from 3 options to 2: "Create from current HEAD" and "Select branch (smart mode)"
-- Smart mode automatically handles branch conflicts and offers appropriate actions
+- Enhanced from 2 options to 3: "Create from current HEAD", "Select branch", and "Select tag"
+- Branch selection automatically handles conflicts and offers appropriate actions
+- Tag selection allows creating worktrees from specific versions
 
 ### Custom Path Support
 
@@ -96,11 +97,13 @@ source /path/to/git-workers/shell/gw.sh
 
 - **`get_branch_worktree_map()`**: Maps branch names to worktree names, including main worktree detection
 - **`list_all_branches()`**: Returns both local and remote branches (remote without "origin/" prefix)
+- **`list_all_tags()`**: Returns all tags with optional messages for annotated tags
 - **`create_worktree_with_new_branch()`**: Creates worktree with new branch from base branch (supports git-flow style workflows)
+- **`create_worktree_with_branch()`**: Enhanced to handle tag references for creating worktrees at specific versions
 - **`copy_configured_files()`**: Copies files specified in config to new worktrees
 - **`create_worktree_from_head()`**: Fixed path resolution for non-bare repositories (converts relative paths to absolute)
 - **`validate_custom_path()`**: Validates custom paths for security and compatibility
-- **`create_worktree_internal()`**: Enhanced with custom path input option
+- **`create_worktree_internal()`**: Enhanced with custom path input option and tag selection
 
 ## Architecture
 
@@ -198,6 +201,7 @@ Since Git lacks native rename functionality:
 - New test files added:
   - `worktree_path_test.rs`: Tests for path resolution and edge cases
   - `create_worktree_integration_test.rs`: Integration tests for worktree creation
+  - `create_worktree_from_tag_test.rs`: Tests for tag listing and worktree creation from tags
 
 ### String Formatting
 
@@ -332,3 +336,7 @@ The following test files have been added/updated for v0.3.0:
 - `tests/worktree_lock_test.rs`: 5 tests for concurrent access control
 - `tests/validate_custom_path_test.rs`: 9 tests for custom path validation including security checks
 - Enhanced `tests/create_worktree_integration_test.rs`: 2 additional tests for custom path creation
+- `tests/create_worktree_from_tag_test.rs`: 3 tests for tag functionality:
+  - `test_list_all_tags`: Tests tag listing with both lightweight and annotated tags
+  - `test_create_worktree_from_tag`: Tests creating worktree from tag with new branch
+  - `test_create_worktree_from_tag_detached`: Tests creating detached HEAD worktree from tag

README.md

@@ -3,22 +3,22 @@
 [![CI](https://github.com/wasabeef/git-workers/actions/workflows/ci.yml/badge.svg)](https://github.com/wasabeef/git-workers/actions/workflows/ci.yml)
 [![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
-An interactive CLI tool for managing Git worktrees with ease.
+An interactive CLI tool for managing Git worktrees.
 
 https://github.com/user-attachments/assets/fb5f0213-4a9f-43e2-9557-416070d7e122
 
 ## Features
 
-- 📋 List worktrees with detailed status information (branch, changes, ahead/behind)
-- 🔍 Fuzzy search through worktrees and branches
-- ➕ Create new worktrees from branches or HEAD
-- 📄 Automatically copy gitignored files (like .env) to new worktrees
-- ➖ Delete single or multiple worktrees
-- 🔄 Switch worktrees with automatic directory change
-- ✏️ Rename worktrees and optionally their branches
-- 🧹 Cleanup old worktrees by age
-- 🪝 Execute hooks on worktree lifecycle events
-- 📝 Edit and manage hooks through the interface
+- List worktrees with detailed status information (branch, changes, ahead/behind)
+- Fuzzy search through worktrees and branches
+- Create new worktrees from branches, tags, or HEAD
+- Automatically copy gitignored files (.env) to new worktrees
+- Delete single or multiple worktrees
+- Switch worktrees with automatic directory change
+- Rename worktrees and optionally their branches
+- Cleanup old worktrees by age
+- Execute hooks on worktree lifecycle events
+- Edit and manage hooks through the interface
 
 ## Installation
 
@@ -55,22 +55,26 @@ gw
 
 Git Workers provides an interactive menu-driven interface. Simply run `gw` and navigate through the options:
 
-- **List worktrees** (`•`): Display all worktrees with branch, changes, and sync status
-- **Search worktrees** (`?`): Fuzzy search through worktree names and branches
-- **Create worktree** (`+`): Create a new worktree with two options:
-  - **Create from current HEAD**: Creates a new worktree with a new branch from the current HEAD
-  - **Select branch (smart mode)**: Choose from local/remote branches with fuzzy search:
+- List worktrees (`•`) - Display all worktrees with branch, changes, and sync status
+- Search worktrees (`?`) - Fuzzy search through worktree names and branches
+- Create worktree (`+`) - Create a new worktree with three options:
+  - Create from current HEAD - Creates a new worktree with a new branch from the current HEAD
+  - Select branch - Choose from local/remote branches with fuzzy search:
     - Shows local branches (💻) and remote branches (⛅️) with usage status
     - Automatically handles branch conflicts (offers to create new branch if already in use)
-    - Fuzzy search enabled when >10 branches for easy navigation
-    - Automatically copies configured files (.env, etc.) to new worktrees
-- **Delete worktree** (`-`): Delete a single worktree with safety checks
-- **Batch delete** (`=`): Select and delete multiple worktrees at once (optionally deletes orphaned branches)
-- **Cleanup old worktrees** (`~`): Remove worktrees older than specified days
-- **Switch worktree** (`→`): Switch to another worktree (automatically changes directory)
-- **Rename worktree** (`*`): Rename worktree directory and optionally its branch
-- **Edit hooks** (`λ`): Configure lifecycle hooks in `.git-workers.toml`
-- **Exit** (`x`): Exit the application
+    - Fuzzy search enabled when >5 branches
+  - Select tag - Choose from tags to create a worktree at a specific version:
+    - Shows all tags (🏷️) with messages for annotated tags
+    - Creates a new branch from the selected tag
+    - Fuzzy search enabled when >5 tags
+  - Automatically copies configured files (.env, etc.) to new worktrees
+- Delete worktree (`-`) - Delete a single worktree with safety checks
+- Batch delete (`=`) - Select and delete multiple worktrees at once (optionally deletes orphaned branches)
+- Cleanup old worktrees (`~`) - Remove worktrees older than specified days
+- Switch worktree (`→`) - Switch to another worktree (automatically changes directory)
+- Rename worktree (`*`) - Rename worktree directory and optionally its branch
+- Edit hooks (`λ`) - Configure lifecycle hooks in `.git-workers.toml`
+- Exit (`x`) - Exit the application
 
 ### Configuration
 

src/commands.rs

@@ -398,7 +398,8 @@ fn search_worktrees_internal(manager: &GitWorktreeManager) -> Result<bool> {
 ///    - Custom path: User-specified relative path (e.g., `../custom/path`)
 /// 3. **Branch Selection**:
 ///    - Create from current HEAD
-///    - Create from existing branch (shows branch list)
+///    - Select branch (shows local/remote branch list)
+///    - Select tag (shows tag list)
 /// 4. **Creation**: Creates the worktree with progress indication
 /// 5. **File Copy**: Copies configured files (e.g., `.env`) from main worktree
 /// 6. **Post-create Hooks**: Executes any configured post-create hooks
@@ -581,7 +582,7 @@ fn create_worktree_internal(manager: &GitWorktreeManager) -> Result<bool> {
 
     // Branch handling
     println!();
-    let branch_options = vec!["Create from current HEAD", "Select branch (smart mode)"];
+    let branch_options = vec!["Create from current HEAD", "Select branch", "Select tag"];
 
     let branch_choice = match Select::with_theme(&get_theme())
         .with_prompt("Select branch option")
@@ -594,7 +595,7 @@ fn create_worktree_internal(manager: &GitWorktreeManager) -> Result<bool> {
 
     let (branch, new_branch_name) = match branch_choice {
         1 => {
-            // Select branch (smart mode)
+            // Select branch
             let (local_branches, remote_branches) = manager.list_all_branches()?;
             if local_branches.is_empty() && remote_branches.is_empty() {
                 utils::print_warning("No branches found, creating from HEAD");
@@ -632,7 +633,7 @@ fn create_worktree_internal(manager: &GitWorktreeManager) -> Result<bool> {
                 println!();
 
                 // Use FuzzySelect for better search experience when there are many branches
-                let selection_result = if branch_items.len() > 10 {
+                let selection_result = if branch_items.len() > 5 {
                     println!("Type to search branches (fuzzy search enabled):");
                     FuzzySelect::with_theme(&get_theme())
                         .with_prompt("Select a branch")
@@ -785,6 +786,58 @@ fn create_worktree_internal(manager: &GitWorktreeManager) -> Result<bool> {
                 }
             }
         }
+        2 => {
+            // Select tag
+            let tags = manager.list_all_tags()?;
+            if tags.is_empty() {
+                utils::print_warning("No tags found, creating from HEAD");
+                (None, None)
+            } else {
+                // Create items for tag selection with message preview
+                let tag_items: Vec<String> = tags
+                    .iter()
+                    .map(|(name, message)| {
+                        if let Some(msg) = message {
+                            // Truncate message to first line for display
+                            let first_line = msg.lines().next().unwrap_or("");
+                            let truncated = if first_line.len() > 50 {
+                                format!("{}...", &first_line[..50])
+                            } else {
+                                first_line.to_string()
+                            };
+                            format!("🏷️  {name} - {truncated}")
+                        } else {
+                            format!("🏷️  {name}")
+                        }
+                    })
+                    .collect();
+
+                println!();
+
+                // Use FuzzySelect for better search experience when there are many tags
+                let selection_result = if tag_items.len() > 5 {
+                    println!("Type to search tags (fuzzy search enabled):");
+                    FuzzySelect::with_theme(&get_theme())
+                        .with_prompt("Select a tag")
+                        .items(&tag_items)
+                        .interact_opt()?
+                } else {
+                    Select::with_theme(&get_theme())
+                        .with_prompt("Select a tag")
+                        .items(&tag_items)
+                        .interact_opt()?
+                };
+
+                match selection_result {
+                    Some(selection) => {
+                        let selected_tag = &tags[selection].0;
+                        // For tags, we always create a new branch named after the worktree
+                        (Some(selected_tag.clone()), Some(name.clone()))
+                    }
+                    None => return Ok(false),
+                }
+            }
+        }
         _ => {
             // Create from current HEAD
             (None, None)
@@ -800,10 +853,22 @@ fn create_worktree_internal(manager: &GitWorktreeManager) -> Result<bool> {
     println!("  {name_label} {name_value}");
     if let Some(new_branch) = &new_branch_name {
         let base_branch_name = branch.as_ref().unwrap();
-        let branch_label = "New Branch:".bright_black();
-        let branch_value = new_branch.yellow();
-        let base_value = base_branch_name.bright_black();
-        println!("  {branch_label} {branch_value} (from {base_value})");
+        // Check if the base branch is a tag
+        if manager
+            .repo()
+            .find_reference(&format!("refs/tags/{base_branch_name}"))
+            .is_ok()
+        {
+            let branch_label = "New Branch:".bright_black();
+            let branch_value = new_branch.yellow();
+            let tag_value = format!("tag: {base_branch_name}").bright_cyan();
+            println!("  {branch_label} {branch_value} (from {tag_value})");
+        } else {
+            let branch_label = "New Branch:".bright_black();
+            let branch_value = new_branch.yellow();
+            let base_value = base_branch_name.bright_black();
+            println!("  {branch_label} {branch_value} (from {base_value})");
+        }
     } else if let Some(branch_name) = &branch {
         let branch_label = "Branch:".bright_black();
         let branch_value = branch_name.yellow();

src/git.rs

@@ -740,18 +740,19 @@ impl GitWorktreeManager {
         self.get_default_worktree_base_path()
     }
 
-    /// Creates a worktree with a specific branch
+    /// Creates a worktree with a specific branch or tag
     ///
     /// Uses the git CLI command for branch-based worktree creation because
     /// git2's worktree API has limitations with branch handling.
     ///
     /// # Arguments
     ///
     /// * `path` - The filesystem path for the new worktree
-    /// * `branch_name` - The branch to check out in the worktree
+    /// * `branch_name` - The branch or tag to check out in the worktree
     ///
     /// # Behavior
     ///
+    /// - If a tag reference: Creates worktree at the tag commit (detached HEAD)
     /// - If the branch exists: Creates worktree with that branch checked out
     /// - If the branch doesn't exist: Creates a new branch and worktree
     ///
@@ -768,8 +769,16 @@ impl GitWorktreeManager {
         let mut cmd = Command::new("git");
         cmd.current_dir(self.get_git_dir()?);
 
-        // Check if this is a remote branch reference (e.g., "origin/feature")
-        if branch_name.starts_with(GIT_REMOTE_PREFIX) {
+        // Check if this is a tag reference
+        if self
+            .repo
+            .find_reference(&format!("refs/tags/{branch_name}"))
+            .is_ok()
+        {
+            // For tags, we need to create a detached HEAD worktree
+            // git worktree add <path> <tag>
+            cmd.arg("worktree").arg("add").arg(path).arg(branch_name);
+        } else if branch_name.starts_with(GIT_REMOTE_PREFIX) {
             // For remote branches, we need to create a local branch
             // Extract the branch name without "origin/" prefix
             let local_branch_name = branch_name
@@ -987,6 +996,68 @@ impl GitWorktreeManager {
         Ok((local_branches, remote_branches))
     }
 
+    /// Lists all tags in the repository
+    ///
+    /// This method retrieves all tags, including both lightweight and annotated tags.
+    /// For annotated tags, it includes the tag message if available.
+    ///
+    /// # Returns
+    ///
+    /// A vector of tuples containing:
+    /// - Tag name (`String`)
+    /// - Tag message (`Option<String>`) - Some for annotated tags, None for lightweight tags
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if tag enumeration fails
+    ///
+    /// # Example
+    ///
+    /// ```no_run
+    /// # use git_workers::git::GitWorktreeManager;
+    /// # let manager = GitWorktreeManager::new().unwrap();
+    /// let tags = manager.list_all_tags().unwrap();
+    /// for (name, message) in tags {
+    ///     if let Some(msg) = message {
+    ///         println!("Tag: {} - {}", name, msg);
+    ///     } else {
+    ///         println!("Tag: {}", name);
+    ///     }
+    /// }
+    /// ```
+    pub fn list_all_tags(&self) -> Result<Vec<(String, Option<String>)>> {
+        let mut tags = Vec::new();
+
+        self.repo.tag_foreach(|oid, name| {
+            if let Ok(name_str) = std::str::from_utf8(name) {
+                // Remove refs/tags/ prefix
+                let tag_name = name_str
+                    .strip_prefix("refs/tags/")
+                    .unwrap_or(name_str)
+                    .to_string();
+
+                // Try to get tag message for annotated tags
+                let tag_message = if let Ok(obj) = self.repo.find_object(oid, None) {
+                    if let Ok(tag) = obj.peel_to_tag() {
+                        tag.message().map(|s| s.to_string())
+                    } else {
+                        None
+                    }
+                } else {
+                    None
+                };
+
+                tags.push((tag_name, tag_message));
+            }
+            true
+        })?;
+
+        // Sort tags by name (reverse order to show newest versions first)
+        tags.sort_by(|a, b| b.0.cmp(&a.0));
+
+        Ok(tags)
+    }
+
     /// Deletes a local branch by name
     ///
     /// # Arguments

src/lib.rs

@@ -14,6 +14,7 @@
 //! - **Rename Support**: Complete worktree renaming including Git metadata
 //! - **Custom Paths**: Flexible worktree placement with validated custom paths
 //! - **File Copying**: Automatically copy configured files to new worktrees
+//! - **Tag Support**: Create worktrees from specific Git tags
 //!
 //! # Architecture
 //!