mirror of
https://github.com/microsoft/PowerToys.git
synced 2025-12-16 03:37:59 +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.9 KiB
PowerShell
79 lines
2.9 KiB
PowerShell
<#!
|
|
.SYNOPSIS
|
|
Create (or reuse) a worktree for an existing local or remote (origin) branch.
|
|
|
|
.DESCRIPTION
|
|
Normalizes origin/<name> to <name>. If the branch does not exist locally (and -NoFetch is not
|
|
provided) it will fetch and create a tracking branch from origin. Reuses any existing worktree
|
|
bound to the branch; otherwise creates a new one adjacent to the repository root.
|
|
|
|
.PARAMETER Branch
|
|
Branch name (local or origin/<name> form) to materialize as a worktree.
|
|
|
|
.PARAMETER VSCodeProfile
|
|
VS Code profile to open (Default).
|
|
|
|
.PARAMETER NoFetch
|
|
Skip fetch if branch missing locally; script will error instead of creating it.
|
|
|
|
.EXAMPLE
|
|
./New-WorktreeFromBranch.ps1 -Branch feature/login
|
|
|
|
.EXAMPLE
|
|
./New-WorktreeFromBranch.ps1 -Branch origin/bugfix/nullref
|
|
|
|
.EXAMPLE
|
|
./New-WorktreeFromBranch.ps1 -Branch release/v1 -NoFetch
|
|
|
|
.NOTES
|
|
Manual recovery:
|
|
git fetch origin && git checkout <branch>
|
|
git worktree add ../RepoName-XX <branch>
|
|
code ../RepoName-XX --profile Default
|
|
#>
|
|
|
|
param(
|
|
[string] $Branch,
|
|
[Alias('Profile')][string] $VSCodeProfile = 'Default',
|
|
[switch] $NoFetch,
|
|
[switch] $Help
|
|
)
|
|
. "$PSScriptRoot/WorktreeLib.ps1"
|
|
|
|
if ($Help -or -not $Branch) { Show-FileEmbeddedHelp -ScriptPath $MyInvocation.MyCommand.Path; return }
|
|
|
|
# Normalize origin/<name> to <name>
|
|
if ($Branch -match '^(origin|upstream|main|master)/.+') {
|
|
if ($Branch -match '^(origin|upstream)/(.+)$') { $Branch = $Matches[2] }
|
|
}
|
|
|
|
try {
|
|
git show-ref --verify --quiet "refs/heads/$Branch"
|
|
if ($LASTEXITCODE -ne 0) {
|
|
if (-not $NoFetch) {
|
|
Warn "Local branch '$Branch' not found; attempting remote fetch..."
|
|
git fetch --all --prune 2>$null | Out-Null
|
|
$remoteRef = "origin/$Branch"
|
|
git show-ref --verify --quiet "refs/remotes/$remoteRef"
|
|
if ($LASTEXITCODE -eq 0) {
|
|
git branch --track $Branch $remoteRef 2>$null | Out-Null
|
|
if ($LASTEXITCODE -ne 0) { throw "Failed to create tracking branch '$Branch' from $remoteRef" }
|
|
Info "Created local tracking branch '$Branch' from $remoteRef."
|
|
} else { throw "Branch '$Branch' not found locally or on origin. Use git fetch or specify a valid branch." }
|
|
} else { throw "Branch '$Branch' does not exist locally (remote fetch disabled with -NoFetch)." }
|
|
}
|
|
|
|
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 $Branch (or: git branch --track $Branch origin/$Branch)"
|
|
Info ' git worktree add ../<Repo>-XX <branch>'
|
|
Info ' code ../<Repo>-XX'
|
|
exit 1
|
|
}
|