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