[{"data":1,"prerenderedAt":650},["ShallowReactive",2],{"navigation_en":3,"-docs-getting-started-refs":153,"-docs-getting-started-refs-surround":645},{"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":32,"body":155,"description":637,"extension":638,"links":639,"meta":640,"navigation":641,"path":33,"seo":642,"stem":34,"__hash__":644},"docs_gettingStarted\u002Fdocs\u002Fgetting-started\u002F05.refs.md",{"type":156,"value":157,"toc":629},"minimark",[158,167,178,183,189,318,326,330,333,402,409,413,427,436,475,478,482,492,509,523,527,532,562,581,585,595,612,618,625],[159,160,161,162,166],"p",{},"A ",[163,164,165],"strong",{},"ref"," is what you want to materialize. It is the second positional argument\nof a workspace command:",[168,169,174],"pre",{"className":170,"code":172,"language":173},[171],"language-text","uxd \u003Cproject> \u003Cref> [verb]\n","text",[175,176,172],"code",{"__ignoreMap":177},"",[179,180,182],"h2",{"id":181},"resolution-order","Resolution order",[159,184,185,188],{},[175,186,187],{},"uxd"," tries these forms in order. First match wins.",[190,191,192,208],"table",{},[193,194,195],"thead",{},[196,197,198,202,205],"tr",{},[199,200,201],"th",{},"Input",[199,203,204],{},"Meaning",[199,206,207],{},"Example",[209,210,211,235,250,277,290,305],"tbody",{},[196,212,213,223,226],{},[214,215,216,219,220],"td",{},[175,217,218],{},"\u003Cn>"," or ",[175,221,222],{},"#\u003Cn>",[214,224,225],{},"Pull request",[214,227,228,231,232],{},[175,229,230],{},"uxd my-project 42"," · ",[175,233,234],{},"uxd my-project '#42'",[196,236,237,242,245],{},[214,238,239],{},[175,240,241],{},"pr\u002F\u003Cn>",[214,243,244],{},"Pull request (case-insensitive)",[214,246,247],{},[175,248,249],{},"uxd my-project pr\u002F42",[196,251,252,269,272],{},[214,253,254,255,258,259,258,262,265,266],{},"Starts with ",[175,256,257],{},"\u002F",", ",[175,260,261],{},".\u002F",[175,263,264],{},"..\u002F",", or ",[175,267,268],{},"~",[214,270,271],{},"Adopt an existing working tree",[214,273,274],{},[175,275,276],{},"uxd my-project ~\u002Fcode\u002Fcheckout shell",[196,278,279,282,285],{},[214,280,281],{},"40-char hex",[214,283,284],{},"Commit SHA — detached worktree",[214,286,287],{},[175,288,289],{},"uxd my-project 1a2b3c…",[196,291,292,297,300],{},[214,293,294],{},[175,295,296],{},"-",[214,298,299],{},"The last-used ref for this project",[214,301,302],{},[175,303,304],{},"uxd my-project - shell",[196,306,307,310,313],{},[214,308,309],{},"Anything else valid as a branch",[214,311,312],{},"Branch name",[214,314,315],{},[175,316,317],{},"uxd my-project feat\u002Flogin code",[319,320,322,323,325],"warning",{"title":321},"Short SHAs are not auto-detected","A 7-character hex string is indistinguishable from a hex-ish branch name, so\n",[175,324,187],{}," refuses to guess. Pass the full 40 characters, or force the\ninterpretation with a flag.",[179,327,329],{"id":328},"forcing-an-interpretation","Forcing an interpretation",[159,331,332],{},"Three global flags bypass the table above entirely:",[168,334,338],{"className":335,"code":336,"language":337,"meta":177,"style":177},"language-bash shiki shiki-themes github-light-high-contrast github-light-high-contrast github-dark-high-contrast","uxd my-project --pr 42 code            # treat 42 as a PR\nuxd my-project --branch 42 code        # treat 42 as a branch literally named \"42\"\nuxd my-project --path .\u002Fhere shell     # adopt .\u002Fhere\n","bash",[175,339,340,366,383],{"__ignoreMap":177},[341,342,345,348,352,356,359,362],"span",{"class":343,"line":344},"line",1,[341,346,187],{"class":347},"szw1H",[341,349,351],{"class":350},"semJd"," my-project",[341,353,355],{"class":354},"ssYy9"," --pr",[341,357,358],{"class":354}," 42",[341,360,361],{"class":350}," code",[341,363,365],{"class":364},"sq92B","            # treat 42 as a PR\n",[341,367,369,371,373,376,378,380],{"class":343,"line":368},2,[341,370,187],{"class":347},[341,372,351],{"class":350},[341,374,375],{"class":354}," --branch",[341,377,358],{"class":354},[341,379,361],{"class":350},[341,381,382],{"class":364},"        # treat 42 as a branch literally named \"42\"\n",[341,384,386,388,390,393,396,399],{"class":343,"line":385},3,[341,387,187],{"class":347},[341,389,351],{"class":350},[341,391,392],{"class":354}," --path",[341,394,395],{"class":350}," .\u002Fhere",[341,397,398],{"class":350}," shell",[341,400,401],{"class":364},"     # adopt .\u002Fhere\n",[159,403,404,405,408],{},"Reach for these when a branch name collides with another form — a branch called\n",[175,406,407],{},"42",", or one whose name is 40 hex characters.",[179,410,412],{"id":411},"url-form","URL form",[159,414,415,416,418,419,422,423,426],{},"Pass a clone or web URL in place of the project name. ",[175,417,187],{}," matches it against\nthe project whose ",[175,420,421],{},"repo"," has the same host, owner, and repository — ssh and\nhttps forms are equivalent, and a trailing ",[175,424,425],{},".git"," is optional.",[159,428,161,429,219,432,435],{},[175,430,431],{},"\u002Fpull\u002F\u003Cn>",[175,433,434],{},"\u002Ftree\u002F\u003Cbranch>"," segment in the URL is consumed as the ref:",[168,437,439],{"className":335,"code":438,"language":337,"meta":177,"style":177},"uxd https:\u002F\u002Fgithub.com\u002Fmy-org\u002Fmy-project\u002Fpull\u002F42 code\nuxd https:\u002F\u002Fgithub.com\u002Fmy-org\u002Fmy-project\u002Ftree\u002Ffeat\u002Flogin diff\nuxd git@github.com:my-org\u002Fmy-project.git 42 code      # ref given separately\n",[175,440,441,451,461],{"__ignoreMap":177},[341,442,443,445,448],{"class":343,"line":344},[341,444,187],{"class":347},[341,446,447],{"class":350}," https:\u002F\u002Fgithub.com\u002Fmy-org\u002Fmy-project\u002Fpull\u002F42",[341,449,450],{"class":350}," code\n",[341,452,453,455,458],{"class":343,"line":368},[341,454,187],{"class":347},[341,456,457],{"class":350}," https:\u002F\u002Fgithub.com\u002Fmy-org\u002Fmy-project\u002Ftree\u002Ffeat\u002Flogin",[341,459,460],{"class":350}," diff\n",[341,462,463,465,468,470,472],{"class":343,"line":385},[341,464,187],{"class":347},[341,466,467],{"class":350}," git@github.com:my-org\u002Fmy-project.git",[341,469,358],{"class":354},[341,471,361],{"class":350},[341,473,474],{"class":364},"      # ref given separately\n",[159,476,477],{},"This is the \"paste the link from Slack\" path — no need to remember which\nproject name you gave the repository.",[179,479,481],{"id":480},"adopting-an-existing-checkout","Adopting an existing checkout",[159,483,484,485,487,488,491],{},"A path ref does not create a worktree. ",[175,486,187],{}," ",[163,489,490],{},"adopts"," the working tree that is\nalready there, wrapping it with the same environment, ports, and commands as a\nmanaged workspace:",[168,493,495],{"className":335,"code":494,"language":337,"meta":177,"style":177},"uxd my-project ~\u002Fcode\u002Fmy-project-hotfix shell\n",[175,496,497],{"__ignoreMap":177},[341,498,499,501,503,506],{"class":343,"line":344},[341,500,187],{"class":347},[341,502,351],{"class":350},[341,504,505],{"class":350}," ~\u002Fcode\u002Fmy-project-hotfix",[341,507,508],{"class":350}," shell\n",[159,510,511,512,515,516,519,520,522],{},"Adopted workspaces are excluded from ",[175,513,514],{},"clean"," filters unless you pass\n",[175,517,518],{},"--include-adopted",", because ",[175,521,187],{}," did not create them and should not assume it\nmay delete them.",[179,524,526],{"id":525},"the-last-used-ref","The last-used ref",[159,528,529,531],{},[175,530,296],{}," resolves to the last ref you materialized for that project. It is the\nshortcut for \"the thing I was just looking at\":",[168,533,535],{"className":335,"code":534,"language":337,"meta":177,"style":177},"uxd my-project - shell\nuxd my-project - run dev\n",[175,536,537,548],{"__ignoreMap":177},[341,538,539,541,543,546],{"class":343,"line":344},[341,540,187],{"class":347},[341,542,351],{"class":350},[341,544,545],{"class":350}," -",[341,547,508],{"class":350},[341,549,550,552,554,556,559],{"class":343,"line":368},[341,551,187],{"class":347},[341,553,351],{"class":350},[341,555,545],{"class":350},[341,557,558],{"class":350}," run",[341,560,561],{"class":350}," dev\n",[159,563,564,565,567,568,573,574,576,577,580],{},"The last ref is recorded in ",[175,566,187],{},"'s\n",[569,570,572],"a",{"href":571},"\u002Fdocs\u002Fgetting-started\u002Fhow-it-works#where-uxd-keeps-things","state directory",".\nIf a project has no history, ",[175,575,187],{}," exits with ",[175,578,579],{},"E_RESOLVE",".",[179,582,584],{"id":583},"when-resolution-fails","When resolution fails",[159,586,587,588,591,592,594],{},"Resolution errors exit with code ",[175,589,590],{},"4"," (",[175,593,579],{},") and name the problem:",[168,596,598],{"className":335,"code":597,"language":337,"meta":177,"style":177},"uxd my-project no\u002Fsuch\u002Fbranch checkout\n",[175,599,600],{"__ignoreMap":177},[341,601,602,604,606,609],{"class":343,"line":344},[341,603,187],{"class":347},[341,605,351],{"class":350},[341,607,608],{"class":350}," no\u002Fsuch\u002Fbranch",[341,610,611],{"class":350}," checkout\n",[168,613,616],{"className":614,"code":615,"language":173},[171],"→ fetching origin\u002Fno\u002Fsuch\u002Fbranch\nerror(E_RESOLVE): branch 'no\u002Fsuch\u002Fbranch' does not exist on origin\nhint: check the name, or push the ref first\n",[175,617,615],{"__ignoreMap":177},[159,619,620,621,624],{},"See ",[569,622,623],{"href":120},"Exit codes"," for the full list.",[626,627,628],"style",{},"html pre.shiki code .szw1H, html code.shiki .szw1H{--shiki-light:#702C00;--shiki-default:#702C00;--shiki-dark:#FFB757}html pre.shiki code .semJd, html code.shiki .semJd{--shiki-light:#032563;--shiki-default:#032563;--shiki-dark:#ADDCFF}html pre.shiki code .ssYy9, html code.shiki .ssYy9{--shiki-light:#023B95;--shiki-default:#023B95;--shiki-dark:#91CBFF}html pre.shiki code .sq92B, html code.shiki .sq92B{--shiki-light:#66707B;--shiki-default:#66707B;--shiki-dark:#BDC4CC}html .light .shiki span {color: var(--shiki-light);background: var(--shiki-light-bg);font-style: var(--shiki-light-font-style);font-weight: var(--shiki-light-font-weight);text-decoration: var(--shiki-light-text-decoration);}html.light .shiki span {color: var(--shiki-light);background: var(--shiki-light-bg);font-style: var(--shiki-light-font-style);font-weight: var(--shiki-light-font-weight);text-decoration: var(--shiki-light-text-decoration);}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html.dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}",{"title":177,"searchDepth":368,"depth":368,"links":630},[631,632,633,634,635,636],{"id":181,"depth":368,"text":182},{"id":328,"depth":368,"text":329},{"id":411,"depth":368,"text":412},{"id":480,"depth":368,"text":481},{"id":525,"depth":368,"text":526},{"id":583,"depth":368,"text":584},"Every ref form uxd accepts, the order it resolves them in, and how to force an interpretation.","md",null,{},{"icon":35},{"title":32,"description":643},"How uxd parses the ref positional — pull requests, branches, commit SHAs, adopted paths, the last-used ref, and repository URLs.","wkxwyDj5-BAYbDIHdNCIoRZhhFa08F4Mgtn2MTlO2iY",[646,648],{"title":27,"path":28,"stem":29,"description":647,"icon":30,"children":-1},"The resolve → materialize → act pipeline that every uxd workspace command runs, and what each step actually does.",{"title":37,"path":38,"stem":39,"description":649,"icon":40,"children":-1},"What a uxd workspace is, how ports keep them isolated, and the git worktree sharp edges worth knowing before you hit them.",1784975261264]