[{"data":1,"prerenderedAt":724},["ShallowReactive",2],{"navigation_en":3,"-docs-getting-started-how-it-works":153,"-docs-getting-started-how-it-works-surround":719},{"gettingStarted":4,"guides":41,"cli":87,"configuration":123},[5],{"title":6,"icon":7,"path":8,"stem":9,"children":10,"page":7},"Getting Started",false,"\u002Fdocs\u002Fgetting-started","docs\u002Fgetting-started",[11,16,21,26,31,36],{"title":12,"path":13,"stem":14,"icon":15},"Introduction","\u002Fdocs\u002Fgetting-started\u002Fintroduction","docs\u002Fgetting-started\u002F01.introduction","i-lucide-house",{"title":17,"path":18,"stem":19,"icon":20},"Installation","\u002Fdocs\u002Fgetting-started\u002Finstallation","docs\u002Fgetting-started\u002F02.installation","i-lucide-download",{"title":22,"path":23,"stem":24,"icon":25},"Quick Start","\u002Fdocs\u002Fgetting-started\u002Fquick-start","docs\u002Fgetting-started\u002F03.quick-start","i-lucide-zap",{"title":27,"path":28,"stem":29,"icon":30},"How It Works","\u002Fdocs\u002Fgetting-started\u002Fhow-it-works","docs\u002Fgetting-started\u002F04.how-it-works","i-lucide-workflow",{"title":32,"path":33,"stem":34,"icon":35},"Refs","\u002Fdocs\u002Fgetting-started\u002Frefs","docs\u002Fgetting-started\u002F05.refs","i-lucide-git-branch",{"title":37,"path":38,"stem":39,"icon":40},"Workspaces & Worktrees","\u002Fdocs\u002Fgetting-started\u002Fworkspaces","docs\u002Fgetting-started\u002F06.workspaces","i-lucide-folder-tree",[42],{"title":43,"icon":7,"path":44,"stem":45,"children":46,"page":7},"Guides","\u002Fdocs\u002Fguides","docs\u002Fguides",[47,52,57,62,67,72,77,82],{"title":48,"path":49,"stem":50,"icon":51},"Review a Pull Request","\u002Fdocs\u002Fguides\u002Freview-a-pull-request","docs\u002Fguides\u002F01.review-a-pull-request","i-lucide-git-pull-request",{"title":53,"path":54,"stem":55,"icon":56},"Run Dev Servers in Parallel","\u002Fdocs\u002Fguides\u002Frun-dev-servers-in-parallel","docs\u002Fguides\u002F02.run-dev-servers-in-parallel","i-lucide-plug",{"title":58,"path":59,"stem":60,"icon":61},"Seed Local Files","\u002Fdocs\u002Fguides\u002Fseed-local-files","docs\u002Fguides\u002F03.seed-local-files","i-lucide-sprout",{"title":63,"path":64,"stem":65,"icon":66},"Refresh a Workspace","\u002Fdocs\u002Fguides\u002Frefresh-a-workspace","docs\u002Fguides\u002F04.refresh-a-workspace","i-lucide-refresh-cw",{"title":68,"path":69,"stem":70,"icon":71},"Clean Up Workspaces","\u002Fdocs\u002Fguides\u002Fclean-up-workspaces","docs\u002Fguides\u002F05.clean-up-workspaces","i-lucide-trash-2",{"title":73,"path":74,"stem":75,"icon":76},"Script with uxd","\u002Fdocs\u002Fguides\u002Fscript-with-uxd","docs\u002Fguides\u002F06.script-with-uxd","i-lucide-braces",{"title":78,"path":79,"stem":80,"icon":81},"Install Shell Completions","\u002Fdocs\u002Fguides\u002Fshell-completions","docs\u002Fguides\u002F07.shell-completions","i-lucide-keyboard",{"title":83,"path":84,"stem":85,"icon":86},"Troubleshooting","\u002Fdocs\u002Fguides\u002Ftroubleshooting","docs\u002Fguides\u002F08.troubleshooting","i-lucide-stethoscope",[88],{"title":89,"icon":7,"path":90,"stem":91,"children":92,"page":7},"CLI Reference","\u002Fdocs\u002Fcli","docs\u002Fcli",[93,98,103,108,113,118],{"title":94,"path":95,"stem":96,"icon":97},"Command Grammar","\u002Fdocs\u002Fcli\u002Foverview","docs\u002Fcli\u002F01.overview","i-lucide-terminal",{"title":99,"path":100,"stem":101,"icon":102},"Workspace Verbs","\u002Fdocs\u002Fcli\u002Fworkspace-verbs","docs\u002Fcli\u002F02.workspace-verbs","i-lucide-folder-git-2",{"title":104,"path":105,"stem":106,"icon":107},"Project Verbs","\u002Fdocs\u002Fcli\u002Fproject-verbs","docs\u002Fcli\u002F03.project-verbs","i-lucide-boxes",{"title":109,"path":110,"stem":111,"icon":112},"Top-Level Verbs","\u002Fdocs\u002Fcli\u002Ftop-level-verbs","docs\u002Fcli\u002F04.top-level-verbs","i-lucide-wrench",{"title":114,"path":115,"stem":116,"icon":117},"Global Flags","\u002Fdocs\u002Fcli\u002Fglobal-flags","docs\u002Fcli\u002F05.global-flags","i-lucide-flag",{"title":119,"path":120,"stem":121,"icon":122},"Exit Codes","\u002Fdocs\u002Fcli\u002Fexit-codes","docs\u002Fcli\u002F06.exit-codes","i-lucide-circle-alert",[124],{"title":125,"icon":7,"path":126,"stem":127,"children":128,"page":7},"Configuration","\u002Fdocs\u002Fconfiguration","docs\u002Fconfiguration",[129,134,139,144,148],{"title":130,"path":131,"stem":132,"icon":133},"Overview","\u002Fdocs\u002Fconfiguration\u002Foverview","docs\u002Fconfiguration\u002F01.overview","i-lucide-settings",{"title":135,"path":136,"stem":137,"icon":138},"Project File","\u002Fdocs\u002Fconfiguration\u002Fproject-file","docs\u002Fconfiguration\u002F02.project-file","i-lucide-file-code",{"title":140,"path":141,"stem":142,"icon":143},"Commands & Hooks","\u002Fdocs\u002Fconfiguration\u002Fcommands-and-hooks","docs\u002Fconfiguration\u002F03.commands-and-hooks","i-lucide-play",{"title":145,"path":146,"stem":147,"icon":76},"Environment & Templates","\u002Fdocs\u002Fconfiguration\u002Fenvironment-and-templates","docs\u002Fconfiguration\u002F04.environment-and-templates",{"title":149,"path":150,"stem":151,"icon":152},"Editors","\u002Fdocs\u002Fconfiguration\u002Feditors","docs\u002Fconfiguration\u002F05.editors","i-lucide-app-window",{"id":154,"title":27,"body":155,"description":711,"extension":712,"links":713,"meta":714,"navigation":715,"path":28,"seo":716,"stem":29,"__hash__":718},"docs_gettingStarted\u002Fdocs\u002Fgetting-started\u002F04.how-it-works.md",{"type":156,"value":157,"toc":696},"minimark",[158,167,177,204,209,218,226,292,295,299,306,424,453,457,460,550,570,574,662,677,681],[159,160,161,162,166],"p",{},"Every workspace command in ",[163,164,165],"code",{},"uxd"," is the same pipeline:",[168,169,174],"pre",{"className":170,"code":172,"language":173},[171],"language-text","resolve(ref) → materialize(workspace) → act(command)\n","text",[163,175,172],{"__ignoreMap":176},"",[159,178,179,182,183,185,186,185,189,192,193,185,196,199,200,203],{},[163,180,181],{},"checkout"," is the pipeline with a no-op act step. ",[163,184,163],{},", ",[163,187,188],{},"run",[163,190,191],{},"exec",",\n",[163,194,195],{},"shell",[163,197,198],{},"sync",", and ",[163,201,202],{},"diff"," are thin wrappers that swap the act step. Once you\nknow these three stages, you can predict what any verb will do.",[205,206,208],"h2",{"id":207},"resolve","Resolve",[159,210,211,213,214,217],{},[163,212,165],{}," takes the ref you typed and turns it into a concrete git target: a pull\nrequest, a branch, a commit, or an existing working tree to adopt. Resolution\nis ordered and first-match-wins — see ",[215,216,32],"a",{"href":33}," for\nthe full table and the flags that force an interpretation.",[159,219,220,221,225],{},"Resolution produces a ",[222,223,224],"strong",{},"slug",", the stable directory name for the workspace:",[227,228,229,242],"table",{},[230,231,232],"thead",{},[233,234,235,239],"tr",{},[236,237,238],"th",{},"Ref kind",[236,240,241],{},"Slug",[243,244,245,256,272,282],"tbody",{},[233,246,247,251],{},[248,249,250],"td",{},"Pull request",[248,252,253],{},[163,254,255],{},"pr-\u003Cn>",[233,257,258,261],{},[248,259,260],{},"Branch",[248,262,263,264,267,268,271],{},"branch name, sanitized (",[163,265,266],{},"feat\u002Flogin"," → ",[163,269,270],{},"feat-login",")",[233,273,274,277],{},[248,275,276],{},"Commit",[248,278,279],{},[163,280,281],{},"sha-\u003Cfirst 10 chars>",[233,283,284,287],{},[248,285,286],{},"Adopted path",[248,288,289],{},[163,290,291],{},"adopted-\u003Cdirname>-\u003Chash>",[159,293,294],{},"When two branch names sanitize to the same slug, the loser gets a short content\nhash appended, so distinct refs never share a directory.",[205,296,298],{"id":297},"materialize","Materialize",[159,300,301,302,305],{},"Materializing is idempotent. Running it on a workspace that already exists is\ncheap and skips the network entirely — the fast path just reports\n",[163,303,304],{},"worktree ready (reused)",".",[307,308,310,315,326,332,336,345,351,355,370,374,397,401,415,421],"steps",{"level":309},"3",[311,312,314],"h3",{"id":313},"one-bare-clone-per-project","One bare clone per project",[159,316,317,318,321,322,325],{},"The first materialization creates a single ",[222,319,320],{},"bare, partial clone"," at\n",[163,323,324],{},"repo_path",". Every workspace for that project is a git worktree off that one\nclone, so the second ref you check out costs a fetch rather than a full clone.",[168,327,330],{"className":328,"code":329,"language":173},[171],"→ cloning git@github.com:my-org\u002Fmy-project.git (bare, partial)\n",[163,331,329],{"__ignoreMap":176},[311,333,335],{"id":334},"one-worktree-per-ref","One worktree per ref",[159,337,338,340,341,344],{},[163,339,165],{}," fetches the ref and adds a worktree under ",[163,342,343],{},"worktrees_path\u002F\u003Cslug>",":",[168,346,349],{"className":347,"code":348,"language":173},[171],"→ fetching origin\u002Ffeat\u002Flogin\n→ worktree ready: ~\u002Fdev\u002Fuxd\u002Fmy-project\u002Ftrees\u002Ffeat-login\n",[163,350,348],{"__ignoreMap":176},[311,352,354],{"id":353},"ports-get-allocated","Ports get allocated",[159,356,357,358,361,362,365,366,369],{},"Each workspace is assigned a contiguous block of ports, sized by the ",[163,359,360],{},"ports","\nconfig key. Allocation is ",[222,363,364],{},"deterministic first",": the candidate is derived by\nhashing the slug into a 100-stride window above ",[163,367,368],{},"base_port",", then scanning\nupward only if the candidate is already claimed or occupied. The same\nworkspace therefore tends to get the same port every time, which keeps\nbookmarks and OAuth callback URLs working.",[311,371,373],{"id":372},"seed-files-get-copied","Seed files get copied",[159,375,376,377,380,381,384,385,388,389,392,393,396],{},"Files listed in ",[163,378,379],{},"setup.seed_files"," are copied in from\n",[163,382,383],{},"\u003Cconfig-dir>\u002Fseeds\u002F\u003Cproject>\u002F"," (or ",[163,386,387],{},"setup.seed_from","). Existing files are\nnever overwritten unless you pass ",[163,390,391],{},"--reseed",". This is how ",[163,394,395],{},".env.local"," gets\ninto a fresh workspace without you remembering to copy it.",[311,398,400],{"id":399},"setup-runs-cached","Setup runs, cached",[159,402,403,404,407,408,410,411,414],{},"If ",[163,405,406],{},"[setup].run"," is configured, ",[163,409,165],{}," hashes the files matched by\n",[163,412,413],{},"setup.cache_key"," and compares that hash to the one recorded for this\nworkspace. Unchanged means skipped:",[168,416,419],{"className":417,"code":418,"language":173},[171],"→ setup up to date (cache hit)\n",[163,420,418],{"__ignoreMap":176},[159,422,423],{},"Changed — or never run — means the install command runs and the new hash is\nrecorded on success. A failed install leaves the old hash in place, so the next\nattempt retries rather than silently assuming success.",[425,426,427,429,430,433,434,437,438,441,442,185,444,446,447,449,450,305],"note",{},[163,428,181],{}," does ",[222,431,432],{},"not"," run ",[163,435,436],{},"[setup]"," by default — it is the scriptable\nprimitive and stays fast. Pass ",[163,439,440],{},"--setup"," if you want it. ",[163,443,188],{},[163,445,191],{},", and\n",[163,448,195],{}," always run setup unless you pass ",[163,451,452],{},"--no-setup",[205,454,456],{"id":455},"act","Act",[159,458,459],{},"The act step is the verb you asked for:",[227,461,462,472],{},[230,463,464],{},[233,465,466,469],{},[236,467,468],{},"Verb",[236,470,471],{},"Act step",[243,473,474,483,492,506,516,525,534],{},[233,475,476,480],{},[248,477,478],{},[163,479,181],{},[248,481,482],{},"none — print the worktree path",[233,484,485,489],{},[248,486,487],{},[163,488,163],{},[248,490,491],{},"launch the configured editor",[233,493,494,499],{},[248,495,496],{},[163,497,498],{},"run \u003Cname>",[248,500,501,502,505],{},"execute a ",[163,503,504],{},"[commands.\u003Cname>]"," entry through a shell",[233,507,508,513],{},[248,509,510],{},[163,511,512],{},"exec -- \u003Cargv…>",[248,514,515],{},"spawn an argv directly, no shell",[233,517,518,522],{},[248,519,520],{},[163,521,195],{},[248,523,524],{},"start an interactive shell",[233,526,527,531],{},[248,528,529],{},[163,530,198],{},[248,532,533],{},"re-fetch and hard-reset the worktree to its ref",[233,535,536,540],{},[248,537,538],{},[163,539,202],{},[248,541,542,543,546,547],{},"render ",[163,544,545],{},"gh pr diff",", or ",[163,548,549],{},"git diff \u003Cmerge-base>...HEAD",[159,551,552,553,192,556,185,559,562,563,566,567,305],{},"Every child process gets the full uxd environment exported —  ",[163,554,555],{},"UXD_PATH",[163,557,558],{},"UXD_PORT",[163,560,561],{},"UXD_BRANCH",", and the rest — plus whatever you declared in ",[163,564,565],{},"[env]",".\nSee ",[215,568,569],{"href":146},"Environment and templates",[205,571,573],{"id":572},"where-uxd-keeps-things","Where uxd keeps things",[227,575,576,589],{},[230,577,578],{},[233,579,580,583,586],{},[236,581,582],{},"Location",[236,584,585],{},"Contents",[236,587,588],{},"Default",[243,590,591,604,618,633,649],{},[233,592,593,596,599],{},[248,594,595],{},"Config dir",[248,597,598],{},"Project TOML files and seed trees",[248,600,601],{},[163,602,603],{},"~\u002F.uxd",[233,605,606,610,613],{},[248,607,608],{},[163,609,324],{},[248,611,612],{},"The bare, partial clone",[248,614,615],{},[163,616,617],{},"{root}\u002F{project}\u002Frepo",[233,619,620,625,628],{},[248,621,622],{},[163,623,624],{},"worktrees_path",[248,626,627],{},"One directory per workspace",[248,629,630],{},[163,631,632],{},"{root}\u002F{project}\u002Ftrees",[233,634,635,638,644],{},[248,636,637],{},"Data dir",[248,639,640,641,271],{},"Per-workspace scratch space (",[163,642,643],{},"$UXD_DATA_DIR",[248,645,646],{},[163,647,648],{},"{worktrees_path}\u002F.data\u002F\u003Cslug>",[233,650,651,654,657],{},[248,652,653],{},"State dir",[248,655,656],{},"Per-project JSON: workspaces, ports, PR cache, last ref",[248,658,659],{},[163,660,661],{},"${XDG_STATE_HOME:-~\u002F.local\u002Fstate}\u002Fuxd",[159,663,664,665,668,669,672,673,676],{},"State is the bookkeeping — it records which slugs exist, which ports they hold,\nand which ref you used last (that is what ",[163,666,667],{},"-"," resolves to). It is derived data:\nif it drifts from reality, ",[163,670,671],{},"uxd doctor"," flags it and\n",[163,674,675],{},"uxd \u003Cproject> clean --prune-state"," reconciles it.",[205,678,680],{"id":679},"next","Next",[682,683,684,691],"ul",{},[685,686,687,690],"li",{},[215,688,689],{"href":38},"Workspaces and worktrees"," — the\nconsequences of the worktree model, and the sharp edges worth knowing.",[685,692,693,695],{},[215,694,32],{"href":33}," — every ref form, in resolution order.",{"title":176,"searchDepth":697,"depth":697,"links":698},2,[699,700,708,709,710],{"id":207,"depth":697,"text":208},{"id":297,"depth":697,"text":298,"children":701},[702,704,705,706,707],{"id":313,"depth":703,"text":314},3,{"id":334,"depth":703,"text":335},{"id":353,"depth":703,"text":354},{"id":372,"depth":703,"text":373},{"id":399,"depth":703,"text":400},{"id":455,"depth":697,"text":456},{"id":572,"depth":697,"text":573},{"id":679,"depth":697,"text":680},"The resolve → materialize → act pipeline that every uxd workspace command runs, and what each step actually does.","md",null,{},{"icon":30},{"title":27,"description":717},"Understand uxd's pipeline — ref resolution, worktree materialization, setup caching, port allocation, and where uxd keeps its state.","x0A3Z86TBSQrd4DNZmMMoYC_LPVq4R__pr7irYnkVg8",[720,722],{"title":22,"path":23,"stem":24,"description":721,"icon":25,"children":-1},"Go from a fresh install to a running workspace — configure a project, materialize a branch, run its dev server, and clean up.",{"title":32,"path":33,"stem":34,"description":723,"icon":35,"children":-1},"Every ref form uxd accepts, the order it resolves them in, and how to force an interpretation.",1784975261264]