mirror of
https://github.com/microsoft/PowerToys.git
synced 2025-12-16 11:48:06 +01:00
1e3429dd3a
<!-- Enter a brief description/summary of your PR here. What does it fix/what does it change/how was it tested (even manually, if necessary)? --> ## Summary of the Pull Request This pull request introduces a new suite of helper scripts for managing Git worktrees in the `tools/build` directory, along with comprehensive documentation. The scripts streamline common workflows such as creating, reusing, and deleting worktrees for feature branches, forks, and issue-based development, making it easier for developers to work on multiple changes in parallel without duplicating the repository. Each script is provided as both a PowerShell (`.ps1`) and Windows batch (`.cmd`) wrapper for convenience. A detailed markdown guide explains usage patterns, scenarios, and best practices. **New worktree management scripts:** * Added `New-WorktreeFromFork.ps1`/`.cmd` to create a worktree from a branch in a personal fork, handling remote creation and branch tracking automatically. [[1]](diffhunk://#diff-ea4d43777029cdde7fb9fda8ee6a0ed3dcfd75b22ed6ae566c6a77797c8bef54R1-R111) [[2]](diffhunk://#diff-1314b08f84ac8c2e7d020e5584d9f2f19dbf116bbc13c14de0de432006912cfeR1-R4) * Added `New-WorktreeFromBranch.ps1`/`.cmd` to create or reuse a worktree for an existing local or remote branch, with logic to fetch and track branches as needed. [[1]](diffhunk://#diff-07c08acfb570e1b54647370cae17e663e76ee8cb09614cac7a23a9367f625a3eR1-R69) [[2]](diffhunk://#diff-6297be534792c3e6d1bc377b84bcd20b2eb5b3de84d4376a2592b25fc9a88a88R1-R4) * Added `New-WorktreeFromIssue.ps1`/`.cmd` to create a new issue branch from a base ref (default `origin/main`), slugifying the issue title for branch naming. [[1]](diffhunk://#diff-36cb35f3b814759c60f770fc9cc1cc9fa10ceee53811d95a85881d8e69c1ab07R1-R67) [[2]](diffhunk://#diff-890880241ffc24b5d29ddb69ce4c19697a2fce6be6861d0a24d02ebf65b35694R1-R4) * Added `Delete-Worktree.ps1`/`.cmd` to safely remove a worktree, with options to force removal, keep the local branch, or retain orphan fork remotes. Includes robust error handling and manual recovery guidance. [[1]](diffhunk://#diff-8a335544864c1630d7f9bec6f4113c10d84b8e26054996735da41516ad93e173R1-R120) [[2]](diffhunk://#diff-19a810e57f8b82e1dc2476f35d051eb43f2d31e4f68ca7c011c89fd297718020R1-R4) **Documentation:** * Introduced `Wokrtree-Guidelines.md`, a comprehensive guide covering the purpose, usage, flows, naming conventions, troubleshooting, and best practices for the new worktree scripts.
79 lines
2.4 KiB
PowerShell
79 lines
2.4 KiB
PowerShell
<#!
|
|
.SYNOPSIS
|
|
Create (or reuse) a worktree for a new issue branch derived from a base ref.
|
|
|
|
.DESCRIPTION
|
|
Composes a branch name as issue/<number> or issue/<number>-<slug> (slug from optional -Title).
|
|
If the branch does not already exist, it is created from -Base (default origin/main). Then a
|
|
worktree is created or reused.
|
|
|
|
.PARAMETER Number
|
|
Issue number used to construct the branch name.
|
|
|
|
.PARAMETER Title
|
|
Optional descriptive title; slug into the branch name.
|
|
|
|
.PARAMETER Base
|
|
Base ref to branch from (default origin/main).
|
|
|
|
.PARAMETER VSCodeProfile
|
|
VS Code profile to open (Default).
|
|
|
|
.EXAMPLE
|
|
./New-WorktreeFromIssue.ps1 -Number 1234 -Title "Crash on launch"
|
|
|
|
.EXAMPLE
|
|
./New-WorktreeFromIssue.ps1 -Number 42 -Base origin/develop
|
|
|
|
.NOTES
|
|
Manual recovery:
|
|
git fetch origin
|
|
git checkout -b issue/<num>-<slug> <base>
|
|
git worktree add ../Repo-XX issue/<num>-<slug>
|
|
code ../Repo-XX
|
|
#>
|
|
|
|
param(
|
|
[int] $Number,
|
|
[string] $Title,
|
|
[string] $Base = 'origin/main',
|
|
[Alias('Profile')][string] $VSCodeProfile = 'Default',
|
|
[switch] $Help
|
|
)
|
|
. "$PSScriptRoot/WorktreeLib.ps1"
|
|
$scriptPath = $MyInvocation.MyCommand.Path
|
|
if ($Help -or -not $Number) { Show-FileEmbeddedHelp -ScriptPath $scriptPath; return }
|
|
|
|
# Compose branch name
|
|
if ($Title) {
|
|
$slug = ($Title -replace '[^\w\- ]','').ToLower() -replace ' +','-'
|
|
$branch = "issue/$Number-$slug"
|
|
} else {
|
|
$branch = "issue/$Number"
|
|
}
|
|
|
|
try {
|
|
# Create branch if missing
|
|
git show-ref --verify --quiet "refs/heads/$branch"
|
|
if ($LASTEXITCODE -ne 0) {
|
|
Info "Creating branch $branch from $Base"
|
|
git branch $branch $Base 2>$null | Out-Null
|
|
if ($LASTEXITCODE -ne 0) { throw "Failed to create branch $branch from $Base" }
|
|
} else {
|
|
Info "Branch $branch already exists locally."
|
|
}
|
|
|
|
New-WorktreeForExistingBranch -Branch $branch -VSCodeProfile $VSCodeProfile
|
|
$after = Get-WorktreeEntries | Where-Object { $_.Branch -eq $branch }
|
|
$path = ($after | Select-Object -First 1).Path
|
|
Show-WorktreeExecutionSummary -CurrentBranch $branch -WorktreePath $path
|
|
} catch {
|
|
Err "Error: $($_.Exception.Message)"
|
|
Warn 'Manual steps:'
|
|
Info " git fetch origin"
|
|
Info " git checkout -b $branch $Base (if branch missing)"
|
|
Info " git worktree add ../<Repo>-XX $branch"
|
|
Info ' code ../<Repo>-XX'
|
|
exit 1
|
|
}
|