Merge pull request #13 from BHFock/unstage

Add unstage command and improve flag consistency

Author: BHFock

docs/tutorial.md

@@ -21,7 +21,7 @@ git-cl: A Git subcommand to manage changelists in Git. Group files by intent, ma
     - [Git Status codes](#git-status-codes)
     - [Color Key](#color-key)
   - [2.3 Diff a changelist](#23-diff-a-changelist) 
-  - [2.4 Stage a changelist](#24-stage-a-changelist)
+  - [2.4 Stage and unstage a changelist](#24-stage-and-unstage-a-changelist)
   - [2.5 Commit a changelist](#25-commit-a-changelist)
   - [2.6 Remove files from changelists](#26-remove-files-from-changelists)
   - [2.7 Delete changelists](#27-delete-changelists)
@@ -229,15 +229,17 @@ git cl diff docs tests    # Show combined diff for both 'docs' and 'tests'
 git cl diff docs --staged # Show staged changes for 'docs' changelist
 ```
 
-### 2.4 Stage a changelist
+### 2.4 Stage and Unstage a Changelist
+
+#### Stage a changelist
 
 ```
 git cl stage <changelist-name>
 ```
 
-- Stages all tracked files from the changelist.
-- Only files already tracked by Git will be staged. Untracked files ([??]) in the changelist are safely ignored and remain untracked unless you add them with `git add` first.
-- Changelist is deleted after staging.
+- Stages all tracked files in the changelist.
+- Untracked files ([??]) are ignored unless added with git add.
+- The changelist is deleted after staging, unless --keep is used.
 
 #### Example
 
@@ -248,6 +250,24 @@ git commit -m "Refactor docs"
 
 Tip: Run `git cl diff` first if you want to review the changes before staging.
 
+#### Unstage a changelist
+
+```
+git cl unstage <changelist-name>
+```
+
+- Unstages files from the changelist (i.e. removes them from the index).
+- Only applies to staged files — unchanged or unstaged files are ignored.
+- Files remain in the changelist and your working directory.
+
+#### Example
+
+```
+git cl unstage docs
+```
+
+This is useful when you've staged something too early and want to pull it back without losing the changelist group.
+
 ### 2.5 Commit a changelist
 
 ```
@@ -412,7 +432,8 @@ This will show all files, including those with status codes like `[UU]` (unmerge
 | View grouped status            | `git cl status` / `git cl st`                  | `git cl st`  | 
 | View all statuses, no color    | `git cl status --all --no-color`               |              |
 | Show diff for changelist(s)    | `git cl diff <name1> [<name2> ...] [--staged]` |              |
-| Stage a changelist             | `git cl stage <name> [--keep]`                 |              |
+| Stage a changelist             | `git cl stage <name> [--delete]`               |              |
+| Unstage a changelist           | `git cl unstage <name> [--delete]`             |              |
 | Commit with inline message     | `git cl commit <name> -m "Message" [--keep]`   | `git cl ci`  |
 | Commit using message from file | `git cl commit <name> -F message.txt [--keep]` |              |
 | Remove files from changelists  | `git cl remove <file1> <file2> ...`            | `git cl rm`  |

git-cl

@@ -585,7 +585,7 @@ def cl_stage(args: argparse.Namespace) -> None:
     deletes the changelist.
 
     Args:
-        args: argparse.Namespace with 'name' and 'keep' attributes.
+        args: argparse.Namespace with 'name' and 'delete' attributes.
     """
     changelists = clutil_load()
     name = args.name
@@ -624,13 +624,71 @@ def cl_stage(args: argparse.Namespace) -> None:
         print(f"Error staging files: {error}")
         return
 
-    # Only delete if --keep flag is not set
-    if not args.keep:
+    # Only delete if --delete flag is set
+    if args.delete:
+        del changelists[name]
+        clutil_save(changelists)
+        print(f"Deleted changelist '{name}'")
+
+
+def cl_unstage(args: argparse.Namespace) -> None:
+    """
+    Unstages all staged files in the specified changelist, moving them back
+    to the working directory as unstaged changes.
+
+    Args:
+        args: argparse.Namespace with 'name' and 'keep' attributes.
+    """
+    changelists = clutil_load()
+    name = args.name
+    if name not in changelists:
+        print(f"Changelist '{name}' not found.")
+        return
+
+    git_root = clutil_get_git_root()
+    to_unstage = []
+
+    # Get current status to identify staged files
+    status_map = clutil_get_file_status_map(show_all=True)
+
+    for stored_path in changelists[name]:
+        # Convert stored path (relative to git root) to absolute path
+        abs_path = (git_root / stored_path).resolve()
+
+        if not abs_path.exists():
+            print(f"Warning: '{stored_path}' does not exist.")
+            continue
+
+        # Convert to path relative to current working directory for Git command
+        rel_to_cwd = os.path.relpath(abs_path, Path.cwd())
+
+        # Check if this file has staged changes
+        rel_to_git_root = abs_path.relative_to(git_root).as_posix()
+        status = status_map.get(rel_to_git_root, "  ")
+
+        # File has staged changes if first character is not space
+        if status[0] != " ":
+            to_unstage.append(rel_to_cwd)
+
+    if not to_unstage:
+        print(f"No staged files to unstage in changelist '{name}'.")
+        return
+
+    try:
+        # Use git reset HEAD to unstage files
+        subprocess.run(["git", "reset", "HEAD", "--"] + to_unstage, check=True)
+        print(f"Unstaged files from changelist '{name}':")
+        for file in to_unstage:
+            print(f"  {file}")
+    except subprocess.CalledProcessError as error:
+        print(f"Error unstaging files: {error}")
+        return
+
+    # Only delete if --delete flag is set
+    if args.delete:
         del changelists[name]
         clutil_save(changelists)
         print(f"Deleted changelist '{name}'")
-    else:
-        print(f"Kept changelist '{name}' (use --keep flag to preserve)")
 
 
 def cl_status(args: argparse.Namespace) -> None:
@@ -995,22 +1053,40 @@ def main() -> None:
     # stage
     stage_parser = subparsers.add_parser('stage',
                                          help=("Stage tracked files from a "
-                                               "changelist (ignores "
-                                               "untracked)"),
+                                               "changelist"),
                                          description=(
                                              "Stage all tracked files from "
-                                             "the specified changelist. "
-                                             "Untracked files in the "
-                                             "changelist are ignored and "
-                                             "remain untracked. By default, "
-                                             "the changelist is deleted after "
-                                             "staging unless --keep is used."))
+                                             "the specified changelist. Only "
+                                             "files already tracked by Git "
+                                             "will be staged. Untracked files "
+                                             "in the changelist are safely "
+                                             "ignored and remain untracked. "
+                                             "By default, the changelist is "
+                                             "kept unless --delete is used."))
     stage_parser.add_argument('name', metavar='CHANGELIST',
                               help='Name of the changelist to stage')
-    stage_parser.add_argument('--keep', action='store_true',
-                              help='Keep the changelist after staging')
+    stage_parser.add_argument('--delete', action='store_true',
+                              help='Delete the changelist after staging')
     stage_parser.set_defaults(func=cl_stage)
 
+    # unstage
+    unstage_parser = subparsers.add_parser('unstage',
+                                           help=("Unstage tracked files from "
+                                                 "a changelist"),
+                                           description=(
+                                               "Unstage all staged files from "
+                                               "the specified changelist, "
+                                               "moving them back to unstaged "
+                                               "state in the working "
+                                               "directory. By default, the "
+                                               "changelist is kept unless "
+                                               "--delete is used."))
+    unstage_parser.add_argument('name', metavar='CHANGELIST',
+                                help='Name of the changelist to unstage')
+    unstage_parser.add_argument('--delete', action='store_true',
+                                help='Delete the changelist after unstaging')
+    unstage_parser.set_defaults(func=cl_unstage)
+
     # commit / ci
     commit_parser = subparsers.add_parser('commit', aliases=['ci'],
                                           help=("Commit tracked files from a "