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