diff --git a/CHANGELOG.md b/CHANGELOG.md index 509a6ed..d545153 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -13,6 +13,15 @@ No changes yet. --- +## [1.0.2] - 2026-03-22 + +### Changed + +- README restructured as a concise overview with demos and key highlights; detailed feature specifications moved to a new `docs/MANUAL.md` reference document. +- Updated marketplace keywords and description for better discoverability. + +--- + ## [1.0.1] - 2026-03-15 ### Fixed diff --git a/README.md b/README.md index 78590db..b3b0594 100644 --- a/README.md +++ b/README.md @@ -7,291 +7,140 @@ --- -**Git Worklists** is a Visual Studio Code extension that provides a lightweight, Git-focused workflow for organizing changes, staging files, **partially staging selected lines**, committing, pushing, and managing stashes, all through a dedicated, predictable UI. +## IntelliJ-style changelists for VS Code -It is designed for developers who want **explicit control over staging, commits, amend, push, and stash workflows**, without relying on VS Code’s built-in Source Control view. +Git Worklists brings structured changelists to VS Code, allowing you to organize changes into clear, independent work units instead of managing a flat list of modified files. ---- - -## Demo - -![Git Worklists demo](media/demo.gif) - ---- +It provides explicit control over: -### Multi-Repository Workspace Support - -Switch between repositories directly from the status bar when working inside a workspace that contains multiple Git repositories. +- staging +- partial staging (line-level) +- commits and amend +- push workflows +- stash management -![Multi repo demo](media/demo_multi_repo.gif) +All through a predictable UI built directly on top of the Git CLI. ---- +Designed for developers who: -### Rename, Drag & Drop, Activity Badge, Stash Improvements - -![v0.7.0 new features demo](media/demo_dnd.gif) +- miss IntelliJ changelists +- find VS Code’s default Source Control limiting +- want precise and explicit control over commits --- -### Conventional Commits Integration - -Generate structured commit messages directly from the Commit Panel using the Conventional Commits extension. +## Why Git Worklists? -![Conventional Commits integration demo](media/demo-conventional.gif) +VS Code presents all changes in a flat list. ---- +Git Worklists lets you: -# Features +- group related changes into changelists +- stage and commit them independently +- keep your work organized and intentional --- -## Workspace Support +## Demo -Git Worklists supports workspaces that contain multiple Git repositories. +### Core Workflow -- Supports workspaces containing multiple Git repositories -- Active repository can be switched from the status bar -- Repository discovery is cached for faster switching -- Only one repository is active in the UI at a time +![Git Worklists demo](media/demo.gif) --- -## Changelists View - -A structured way to organize and stage changes. - -- Displays **Changes** and **Unversioned** files clearly - -- Shows **file count badges** per worklist and a total badge on the Activity Bar icon - -- Unversioned files are detected via `git ls-files --others --exclude-standard` - -- Untracked directories are not shown as placeholder entries - -- Files are displayed in Source Control style: - - **File name** as primary label - - **Folder path** shown as description - -- Create, move, **rename**, and delete **custom changelists** - -- Move files between changelists (per file or per group) +## Additional Features -- **Drag and drop** files or entire changelist groups onto another changelist - -- Move selected files to another changelist - -- File-level and group-level **checkboxes** for staging / unstaging - -- State-aware inline action: - - Shows **Stage** when file is unstaged - - Shows **Unstage** when file is staged - - **Partial staging support** - - Stage only selected lines directly from the editor or diff view - - Files with partially staged changes are visually indicated - -- Stage All / Unstage All per changelist - -- Visual file decorations (badges) - -- Decorations are automatically refreshed after commit or push (no stale indicators) - -- File context menu actions: - - **Open Diff** (HEAD <-> Working Tree) - - **Open Source File** (jump directly to the working tree file) - - **Discard** - - **Move to Changelist** - - **Move Staged Files to Another Changelist…** - - From a changelist: only staged files in that changelist - - From a staged file: all staged files +### Multi-Repository Workspace Support - - **Move Staged Files into Stash…** - - From a changelist: only staged files in that changelist - - From a staged file: all staged files - - Aborts safely if the message dialog is cancelled +Switch between repositories directly from the status bar in multi-repo workspaces. -- Staged-only actions: - - Only staged files are affected - - Unstaged files remain untouched +![Multi repo demo](media/demo_multi_repo.gif) --- -### Diff Integration - -- Click a file row to open a **HEAD <-> Working Tree diff** - -- Clicking a file does NOT change staging state +### Drag & Drop and Changelist Management -- Diff view works correctly for: - - Initial commit (no parent commit) - - Newly added files - - Renamed files - - Missing parent references +Organize files quickly using drag and drop across changelists. -- Dedicated **Close Diff Tabs** button in the view title - -- Optional automatic closing of diff tabs after: - - Commit - - Push - -- Automatic reconciliation with Git status +![v0.7.0 new features demo](media/demo_dnd.gif) -- Files move automatically between: - - **Unversioned** when newly created - - **Changes** when tracked / modified +--- -- Optional prompt when new files are created: - - **Add to Git** (stages file and moves it to Changes) - - **Keep Unversioned** - - **Disable prompt** +### Conventional Commits Integration -- Safe behavior when staging / unstaging newly created files +Generate structured commit messages directly from the Commit Panel using the Conventional Commits extension. -- Newly added (staged) files require confirmation before permanent deletion -- Changelist-level **Discard All Changes** action: - - Categorized confirmation (unversioned / newly added / tracked) - - Safe bulk restore using `git restore` - - Permanent deletion confirmation for unversioned files +![Conventional Commits integration demo](media/demo-conventional.gif) -All staging state reflects the actual Git index. +--- ### Partial Line Staging -![Partial line staging demo](media/demo_partial_stage.gif) - -Git Worklists supports staging individual lines directly from the editor or diff view. +Stage selected lines directly from the editor or diff view. -1. Open a file diff or source file -2. Select the lines you want to stage -3. Right-click -> **GW: Stage Selected Lines** - -Only the selected changes are staged. The rest of the file remains unstaged. - -Files that contain both staged and unstaged changes are automatically marked as **Partially Staged** in the changelist view. +![Partial line staging demo](media/demo_partial_stage.gif) --- -## Commit Panel - -A focused commit experience separate from VS Code SCM. - -- Custom **Commit Message** field - -- Commit message draft is automatically preserved -- **Conventional Commits integration** - - ◯ button next to Amend to generate structured commit messages - - Automatically syncs generated message into the custom commit panel - - Button is hidden if the extension is not installed - - Prevents Source Control view from stealing focus - -- Live staged file counter +### Stash Preview and Management -- Inline warning when attempting to commit with no staged files +Inspect and manage stashed changes with file-level previews. -- **Amend support** - - Supports message-only amend (no staged files required) - - Handles empty-amend edge cases safely - - Amend checkbox automatically resets after a successful commit or commit & push - -- **Commit** - -- **Commit & Push** - -- **Push-only support** (push existing local commits even if nothing is staged) - -- Safe confirmation before force-with-lease push - -- Automatic upstream setup for new local branches - -- Push preview panel when multiple outgoing commits exist: - - Shows commit hashes and subjects before pushing - - Requires explicit confirmation - -- Clear and actionable error feedback - -Commit behavior is predictable and aligned with Git CLI behavior. - -> Conventional Commits integration works with the -> [Conventional Commits extension](https://marketplace.visualstudio.com/items?itemName=vivaxy.vscode-conventional-commits). -> The integration is optional and activates automatically when the extension is installed. +![Stash diff preview demo](media/demo-stash-diff.gif) --- -## Stash Management - -Integrated Git stash support directly inside Git Worklists. +## Key Features -### Create Stash (Per Changelist) +- IntelliJ-style changelists +- Move files between changelists +- Partial line staging +- Dedicated commit panel (commit, amend, push) +- Built-in stash management +- Drag and drop organization +- Explicit Git workflow with no hidden behavior -- Stash all tracked changes from a selected changelist -- Stash the **Unversioned changelist** - Untracked files are stashed using `git stash push --include-untracked`. - - **Note:** Git may include additional untracked files in the repository when creating the stash. A confirmation warning is shown before executing this operation. - Automatically tags stashes with their originating changelist +--- -- Optional custom stash message -- Immediate UI refresh after stash +## Feature Overview -### Stash List View +### Changelists -- Dedicated **Stashes** view -- Stashes are displayed as expandable (accordion-style) nodes -- Expanding a stash reveals the list of files contained within it -- Status-aware file nodes (A / M / D / R / C) -- Clean, readable labels (no raw `stash@{0}` noise) -- Displays originating changelist (e.g. `[CL:changes]`) -- Shows branch context -- Hover tooltip includes full Git reference +- Create, rename, and delete changelists +- Move files between changelists +- Drag and drop support +- Stage and unstage per file or per group -### Stash File Preview +### Partial Staging -- Click a stashed file to open a **diff preview** - - Compares stash base commit (`stash^1`) with stash contents -- Newly added files in a stash open as single-file preview -- Large files are handled safely to prevent editor crashes -- Preview behavior is consistent with the main diff integration +- Stage selected lines from editor or diff +- Clear indication of partially staged files -![Stash diff preview demo](media/demo-stash-diff.gif) +### Commit Workflow -### Stash Actions +- Dedicated commit panel +- Commit, amend, commit & push +- Push-only support +- Optional Conventional Commits integration -Per-stash context actions: +### Stash Management -- **Apply Stash** restore changes without removing stash; files are returned to their originating changelist -- **Pop Stash** restore changes and remove stash; files are returned to their originating changelist -- **Delete Stash** drop stash with confirmation -- Refresh support +- Create stash per changelist +- Inspect stash contents +- Apply, pop, and delete stashes --- -## Git Integration +## Documentation -Uses **Git CLI directly** (no VS Code SCM provider). +For full details, advanced workflows, and edge-case behavior: -Supported operations: - -- `git add` -- `git apply --cached` -- `git restore --staged` -- `git restore --staged --worktree` -- `git commit` -- `git commit --amend` -- `git push` -- `git push --force-with-lease` -- `git stash push` -- `git stash push --include-untracked` -- `git stash list` -- `git stash apply` -- `git stash pop` -- `git stash drop` -- `git diff --name-status` -- `git ls-files --others --exclude-standard` - -All operations are executed per repository using repo-relative paths. +See the manual: [docs/MANUAL.md](docs/MANUAL.md) --- -# Requirements +## Requirements - Git installed and available in PATH - Workspace opened inside a Git repository @@ -299,102 +148,15 @@ All operations are executed per repository using repo-relative paths. --- -# Usage - ---- - -## Changelists & Commits - -1. Open a Git repository in VS Code -2. Open **Git Worklists** from the Activity Bar -3. Stage or unstage files using checkboxes -4. Organize files into custom changelists -5. Enter a commit message -6. (Optional) enable **Amend** -7. Click: - - **Commit** - - **Commit & Push** - - Or push existing commits without staging new changes - ---- - -## Stashes - -1. Right-click a changelist -> **Stash changes…** -2. Enter an optional stash message -3. Open the **Stashes** view -4. Expand a stash to inspect its files -5. Click a file to preview its diff -6. Apply, Pop, or Delete stashes as needed - ---- - -# Extension Settings - -This extension contributes the following settings: - -### `gitWorklists.promptOnNewFile` - -- **Type:** boolean -- **Default:** `true` -- Shows a prompt when new files are created: - - Add to Git - - Keep Unversioned - - Disable prompt - ---- - -### `gitWorklists.ui.closeDiffTabsAfterCommit` - -- **Type:** boolean -- **Default:** `false` -- Automatically closes diff tabs opened by Git Worklists after a successful commit. - ---- - -### `gitWorklists.ui.closeDiffTabsAfterPush` - -- **Type:** boolean -- **Default:** `false` -- Automatically closes diff tabs opened by Git Worklists after a successful push. - ---- - -# Known Limitations - -- Only one active repository is shown at a time in the UI -- In workspaces containing multiple Git repositories, use the status bar to switch the active repository -- Merge conflicts must be resolved manually -- GitHub / GitLab PR features are not included - ---- - -# Roadmap - -Planned improvements: - -- Improve refresh performance for large repositories -- UI/UX refinements for changelist view - ---- - -# Release Notes - -See full changelog in [CHANGELOG.md](CHANGELOG.md) - ---- - -# Development Philosophy - -Git Worklists intentionally avoids VS Code’s built-in SCM provider. +## Development Philosophy -Instead, it builds a focused, predictable workflow using: +Git Worklists avoids VS Code’s built-in SCM provider and instead builds a focused workflow using: - Tree Views - Commit UI - Git CLI -The goal is **clarity, explicit control, and zero hidden magic**. +The goal is clarity, explicit control, and predictable behavior. --- diff --git a/docs/MANUAL.md b/docs/MANUAL.md new file mode 100644 index 0000000..3c6dbe9 --- /dev/null +++ b/docs/MANUAL.md @@ -0,0 +1,362 @@ +# Git Worklists Manual + +This document provides detailed behavior, workflows, and advanced usage. + +--- + +## Workspace Support + +Git Worklists supports workspaces that contain multiple Git repositories. + +- Supports workspaces containing multiple Git repositories +- Active repository can be switched from the status bar +- Repository discovery is cached for faster switching +- Only one repository is active in the UI at a time + +--- + +## Changelists View + +A structured way to organize and stage changes. + +- Displays **Changes** and **Unversioned** files clearly +- Shows **file count badges** per worklist and a total badge on the Activity Bar icon +- Unversioned files are detected via `git ls-files --others --exclude-standard` +- Untracked directories are not shown as placeholder entries + +### File Presentation + +- **File name** as primary label +- **Folder path** shown as description + +### Changelist Operations + +- Create, move, **rename**, and delete **custom changelists** +- Move files between changelists (per file or per group) +- **Drag and drop** files or entire changelist groups onto another changelist +- Move selected files to another changelist + +### Staging + +- File-level and group-level **checkboxes** for staging / unstaging + +- State-aware inline action: + - Shows **Stage** when file is unstaged + - Shows **Unstage** when file is staged + +- **Partial staging support** + - Stage only selected lines directly from the editor or diff view + - Files with partially staged changes are visually indicated + +- Stage All / Unstage All per changelist + +### Decorations + +- Visual file decorations (badges) +- Decorations are automatically refreshed after commit or push + +--- + +## File Context Menu + +- **Open Diff** (HEAD <-> Working Tree) +- **Open Source File** +- **Discard** +- **Move to Changelist** + +### Move Staged Files + +- **Move Staged Files to Another Changelist** + - From a changelist: only staged files in that changelist + - From a staged file: all staged files + +- **Move Staged Files into Stash** + - From a changelist: only staged files in that changelist + - From a staged file: all staged files + - Aborts safely if the message dialog is cancelled + +### Staged-only Behavior + +- Only staged files are affected +- Unstaged files remain untouched + +--- + +## Diff Integration + +- Click a file row to open a **HEAD <-> Working Tree diff** +- Clicking a file does NOT change staging state + +### Supported Cases + +- Initial commit (no parent commit) +- Newly added files +- Renamed files +- Missing parent references + +### Diff Controls + +- Dedicated **Close Diff Tabs** button +- Optional automatic closing after: + - Commit + - Push + +### Git Synchronization + +- Automatic reconciliation with Git status + +- Files move automatically between: + - **Unversioned** when newly created + - **Changes** when tracked / modified + +### New File Handling + +Optional prompt when new files are created: + +- Add to Git +- Keep Unversioned +- Disable prompt + +### Safety + +- Safe behavior when staging / unstaging newly created files +- Newly added (staged) files require confirmation before permanent deletion + +- Changelist-level **Discard All Changes**: + - Categorized confirmation (unversioned / newly added / tracked) + - Safe bulk restore using `git restore` + - Permanent deletion confirmation for unversioned files + +All staging state reflects the actual Git index. + +--- + +## Partial Line Staging + +Stage individual lines directly from the editor or diff view. + +1. Open a file diff or source file +2. Select the lines you want to stage +3. Right-click → Stage Selected Lines + +Only the selected changes are staged. + +Files with mixed state are marked as **Partially Staged**. + +--- + +## Commit Panel + +A focused commit experience separate from VS Code SCM. + +### Core Behavior + +- Custom **Commit Message** field +- Commit message draft is automatically preserved + +### Conventional Commits Integration + +- Generate structured commit messages +- Automatically syncs into commit panel +- Button hidden if extension is not installed +- Prevents Source Control view from stealing focus + +### Commit Actions + +- **Commit** +- **Commit & Push** +- **Push-only support** + +### Amend + +- Supports message-only amend (no staged files required) +- Handles empty-amend edge cases safely +- Automatically resets after successful operation + +### Push Behavior + +- Safe confirmation before force-with-lease push +- Automatic upstream setup for new branches + +- Push preview panel: + - Shows commit hashes and subjects + - Requires explicit confirmation + +### Feedback + +- Live staged file counter +- Inline warning when committing with no staged files +- Clear and actionable error feedback + +Commit behavior aligns with Git CLI. + +--- + +## Stash Management + +Integrated Git stash support. + +### Create Stash (Per Changelist) + +- Stash all tracked changes from a selected changelist +- Supports **Unversioned changelist** + +Untracked files are stashed using: + +``` + +git stash push --include-untracked + +``` + +Note: +Git may include additional untracked files. A confirmation warning is shown. + +- Automatically tags stashes with originating changelist +- Optional custom message +- Immediate UI refresh + +--- + +### Stash List View + +- Dedicated **Stashes view** +- Expandable stash entries +- Shows file list per stash + +- Status-aware nodes (A / M / D / R / C) +- Clean labels (no raw `stash@{0}`) +- Displays originating changelist +- Shows branch context +- Hover tooltip includes full Git reference + +--- + +### Stash File Preview + +- Click a file to open diff preview +- Compares: + - stash base commit (`stash^1`) + - stash contents + +- Newly added files open as single-file preview +- Safe handling of large files + +--- + +### Stash Actions + +- Apply (restore without removing stash) +- Pop (restore and remove) +- Delete (drop stash) +- Refresh + +Files return to their originating changelist. + +--- + +## Git Integration + +Uses **Git CLI directly**. + +Supported operations: + +- `git add` +- `git apply --cached` +- `git restore --staged` +- `git restore --staged --worktree` +- `git commit` +- `git commit --amend` +- `git push` +- `git push --force-with-lease` +- `git stash push` +- `git stash push --include-untracked` +- `git stash list` +- `git stash apply` +- `git stash pop` +- `git stash drop` +- `git diff --name-status` +- `git ls-files --others --exclude-standard` + +All operations use repo-relative paths. + +--- + +## Usage + +### Changelists & Commits + +1. Open a Git repository in VS Code +2. Open Git Worklists from the Activity Bar +3. Stage or unstage files +4. Organize files into changelists +5. Enter a commit message +6. (Optional) enable Amend +7. Commit or push + +--- + +### Stashes + +1. Right-click a changelist → Stash changes +2. Enter optional message +3. Open Stashes view +4. Expand stash +5. Preview files +6. Apply, Pop, or Delete + +--- + +## Settings + +### gitWorklists.promptOnNewFile + +- Type: boolean +- Default: true + +Shows prompt when new files are created. + +--- + +### gitWorklists.ui.closeDiffTabsAfterCommit + +- Type: boolean +- Default: false + +Auto-closes diff tabs after commit. + +--- + +### gitWorklists.ui.closeDiffTabsAfterPush + +- Type: boolean +- Default: false + +Auto-closes diff tabs after push. + +--- + +## Known Limitations + +- Only one active repository in UI +- Must switch repositories via status bar +- Merge conflicts handled manually +- No PR integration + +--- + +## Roadmap + +- Improve refresh performance for large repositories +- UI/UX refinements + +--- + +## Design Principles + +- Explicit over implicit behavior +- No hidden Git state changes +- Alignment with Git CLI +- Predictable workflows + +--- diff --git a/package.json b/package.json index bcce858..6780483 100644 --- a/package.json +++ b/package.json @@ -1,7 +1,7 @@ { "name": "git-worklists", "displayName": "Git Worklists", - "description": "IntelliJ-like changelists, explicit Git staging, commits, and stash management inside VS Code.", + "description": "IntelliJ-style changelists for VS Code. Organize changes into work units, stage selectively, and commit with full control.", "publisher": "ozgen", "version": "1.0.1", "icon": "media/icon.png", @@ -23,27 +23,30 @@ ], "keywords": [ "git", - "changelist", - "changelists", - "staging", + "git workflow", + "git staging", + "explicit staging", "partial staging", "stage selected lines", - "git staging", + "line staging", + "changelist", + "changelists", + "intellij changelist", + "intellij changelists", + "intellij", + "organize changes", + "group changes", + "work units", "stash", + "stash management", "commit", - "push", "amend", - "intellij", - "intellij-like", - "git workflow", - "organize changes", - "group staging", + "commit and push", "source control", - "version control", + "diff view", "diff preview", "conventional commits", "commit message", - "commit generator", "semantic commits" ], "activationEvents": [],