[{"data":1,"prerenderedAt":564},["ShallowReactive",2],{"navigation_en":3,"-docs-getting-started-workspaces":153,"-docs-getting-started-workspaces-surround":561},{"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":37,"body":155,"description":553,"extension":554,"links":555,"meta":556,"navigation":557,"path":38,"seo":558,"stem":39,"__hash__":560},"docs_gettingStarted\u002Fdocs\u002Fgetting-started\u002F06.workspaces.md",{"type":156,"value":157,"toc":546},"minimark",[158,167,182,187,190,203,207,238,300,310,318,322,333,354,358,364,376,392,400,407,462,466,526,532,542],[159,160,161,162,166],"p",{},"A ",[163,164,165],"strong",{},"workspace"," is one materialized ref: a git worktree, a port allocation, a\nprivate data directory, and the state entry that ties them together.",[159,168,169,173,174,177,178,181],{},[170,171,172],"code",{},"uxd"," owns one ",[163,175,176],{},"bare, partial clone"," per project and creates one ",[163,179,180],{},"git\nworktree"," per ref. That is the whole model, and most of its behaviour — good\nand awkward — follows from it.",[183,184,186],"h2",{"id":185},"why-worktrees","Why worktrees",[159,188,189],{},"A worktree gives you a real, separate directory that shares object storage with\none clone. So you can:",[191,192,193,197,200],"ul",{},[194,195,196],"li",{},"Hold five branches open at once without five full clones on disk.",[194,198,199],{},"Leave your main checkout alone — no stashing to review someone else's branch.",[194,201,202],{},"Run several dev servers at the same time, each on its own port.",[183,204,206],{"id":205},"port-isolation","Port isolation",[159,208,209,210,213,214,217,218,221,222,225,226,229,230,233,234,237],{},"Each workspace gets a contiguous block of ports, sized by the project's ",[170,211,212],{},"ports","\nkey (1–10, default 1). The first is exported as ",[170,215,216],{},"$UXD_PORT"," and interpolated as\n",[170,219,220],{},"{port}","; the rest are ",[170,223,224],{},"$UXD_PORT_1",", ",[170,227,228],{},"$UXD_PORT_2",", … and ",[170,231,232],{},"{port+1}",",\n",[170,235,236],{},"{port+2}",", ….",[239,240,246],"pre",{"className":241,"code":242,"filename":243,"language":244,"meta":245,"style":245},"language-toml shiki shiki-themes github-light-high-contrast github-light-high-contrast github-dark-high-contrast","ports = 2\n\n[env]\nPORT = \"{port}\"\nAPI_PORT = \"{port+1}\"\n","~\u002F.uxd\u002Fmy-project.toml","toml","",[170,247,248,261,268,281,291],{"__ignoreMap":245},[249,250,253,257],"span",{"class":251,"line":252},"line",1,[249,254,256],{"class":255},"s7iLA","ports = ",[249,258,260],{"class":259},"ssYy9","2\n",[249,262,264],{"class":251,"line":263},2,[249,265,267],{"emptyLinePlaceholder":266},true,"\n",[249,269,271,274,278],{"class":251,"line":270},3,[249,272,273],{"class":255},"[",[249,275,277],{"class":276},"szw1H","env",[249,279,280],{"class":255},"]\n",[249,282,284,287],{"class":251,"line":283},4,[249,285,286],{"class":255},"PORT = ",[249,288,290],{"class":289},"semJd","\"{port}\"\n",[249,292,294,297],{"class":251,"line":293},5,[249,295,296],{"class":255},"API_PORT = ",[249,298,299],{"class":289},"\"{port+1}\"\n",[159,301,302,303,306,307,309],{},"Allocation is deterministic first — the slug is hashed into a window above\n",[170,304,305],{},"base_port",", and ",[170,308,172],{}," only scans upward if that block is taken or occupied. In\npractice a given branch keeps the same port across sessions.",[159,311,312,313,317],{},"See ",[314,315,316],"a",{"href":54},"Run dev servers in parallel"," for\nthe working setup.",[183,319,321],{"id":320},"the-data-directory","The data directory",[159,323,324,325,328,329,332],{},"Every workspace gets ",[170,326,327],{},"$UXD_DATA_DIR"," — a private directory outside the worktree\nat ",[170,330,331],{},"{worktrees_path}\u002F.data\u002F\u003Cslug>",". Use it for things that must not pollute the\ngit tree: SQLite files, upload directories, caches.",[239,334,336],{"className":241,"code":335,"filename":243,"language":244,"meta":245,"style":245},"[env]\nDATABASE_URL = \"file:{data_dir}\u002Fdev.db\"\n",[170,337,338,346],{"__ignoreMap":245},[249,339,340,342,344],{"class":251,"line":252},[249,341,273],{"class":255},[249,343,277],{"class":276},[249,345,280],{"class":255},[249,347,348,351],{"class":251,"line":263},[249,349,350],{"class":255},"DATABASE_URL = ",[249,352,353],{"class":289},"\"file:{data_dir}\u002Fdev.db\"\n",[183,355,357],{"id":356},"known-caveats","Known caveats",[159,359,360,361,363],{},"These are consequences of the worktree model, not bugs ",[170,362,172],{}," can paper over.\nKnowing them saves an afternoon.",[365,366,368,369,372,373,375],"note",{"title":367},"`.git` is a file, not a directory","Inside a worktree, ",[170,370,371],{},".git"," is a file pointing back at the primary repo. Tooling\nthat assumes a ",[170,374,371],{}," directory — some Docker volume setups, older shell\nscripts — can trip on this.",[365,377,379,380,383,384,387,388,391],{"title":378},"`core.hooksPath` and husky","Repositories that configure relative hook paths (husky does) may resolve them\nincorrectly from a worktree, and ",[170,381,382],{},"pnpm install"," can try to install hooks into\nthe bare repo. ",[170,385,386],{},"uxd doctor"," warns when ",[170,389,390],{},"core.hooksPath"," is set. It does not\nmodify your repository.",[365,393,395,396,399],{"title":394},"Partial clones fetch lazily","The first checkout of a worktree, and a ",[170,397,398],{},"diff"," across not-yet-fetched trees,\nneed network access. Offline use is degraded by design — the trade for not\ndownloading history you will never read.",[365,401,403,404,406],{"title":402},"A branch can only be checked out once","Git refuses to check out the same branch in two worktrees. ",[170,405,172],{}," detects this\nand points you at the existing workspace instead of failing obscurely.",[408,409,411,428,436,439],"caution",{"title":410},"Deleting a worktree by hand leaves metadata behind",[159,412,413,416,417,419,420,423,424,427],{},[170,414,415],{},"rm -rf","-ing a workspace directory leaves git's worktree metadata and ",[170,418,172],{},"'s\nstate entry orphaned. ",[170,421,422],{},"list"," then reports the workspace as ",[170,425,426],{},"missing",":",[239,429,434],{"className":430,"code":432,"language":433},[431],"language-text","SLUG        KIND    BRANCH      STATUS   PORT  AGE  LAST USED\nfeat-login  branch  feat\u002Flogin  missing  3053  2m   1m\n","text",[170,435,432],{"__ignoreMap":245},[159,437,438],{},"Reconcile with:",[239,440,444],{"className":441,"code":442,"language":443,"meta":245,"style":245},"language-bash shiki shiki-themes github-light-high-contrast github-light-high-contrast github-dark-high-contrast","uxd my-project clean --prune-state --yes\n","bash",[170,445,446],{"__ignoreMap":245},[249,447,448,450,453,456,459],{"class":251,"line":252},[249,449,172],{"class":276},[249,451,452],{"class":289}," my-project",[249,454,455],{"class":289}," clean",[249,457,458],{"class":259}," --prune-state",[249,460,461],{"class":259}," --yes\n",[183,463,465],{"id":464},"inspecting-workspaces","Inspecting workspaces",[239,467,469],{"className":441,"code":468,"language":443,"meta":245,"style":245},"uxd my-project list                 # all workspaces for a project\nuxd my-project list --du            # add a disk-usage column\nuxd my-project feat\u002Flogin info      # one workspace in detail\nuxd my-project feat\u002Flogin info --du\n",[170,470,471,484,498,513],{"__ignoreMap":245},[249,472,473,475,477,480],{"class":251,"line":252},[249,474,172],{"class":276},[249,476,452],{"class":289},[249,478,479],{"class":289}," list",[249,481,483],{"class":482},"sq92B","                 # all workspaces for a project\n",[249,485,486,488,490,492,495],{"class":251,"line":263},[249,487,172],{"class":276},[249,489,452],{"class":289},[249,491,479],{"class":289},[249,493,494],{"class":259}," --du",[249,496,497],{"class":482},"            # add a disk-usage column\n",[249,499,500,502,504,507,510],{"class":251,"line":270},[249,501,172],{"class":276},[249,503,452],{"class":289},[249,505,506],{"class":289}," feat\u002Flogin",[249,508,509],{"class":289}," info",[249,511,512],{"class":482},"      # one workspace in detail\n",[249,514,515,517,519,521,523],{"class":251,"line":283},[249,516,172],{"class":276},[249,518,452],{"class":289},[249,520,506],{"class":289},[249,522,509],{"class":289},[249,524,525],{"class":259}," --du\n",[239,527,530],{"className":528,"code":529,"language":433},[431],"slug: feat-login\nkind: branch\nref: feat\u002Flogin\nbranch: feat\u002Flogin\npath: ~\u002Fdev\u002Fuxd\u002Fmy-project\u002Ftrees\u002Ffeat-login\nports: 3053\nstatus: clean\ncreated: 2026-07-25T05:51:38.363Z\nlast used: 2026-07-25T05:51:38.827Z\n",[170,531,529],{"__ignoreMap":245},[159,533,534,535,538,539,541],{},"Both accept ",[170,536,537],{},"--json"," for scripting. See\n",[314,540,73],{"href":74},".",[543,544,545],"style",{},"html pre.shiki code .s7iLA, html code.shiki .s7iLA{--shiki-light:#0E1116;--shiki-default:#0E1116;--shiki-dark:#F0F3F6}html pre.shiki code .ssYy9, html code.shiki .ssYy9{--shiki-light:#023B95;--shiki-default:#023B95;--shiki-dark:#91CBFF}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 .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);}html pre.shiki code .sq92B, html code.shiki .sq92B{--shiki-light:#66707B;--shiki-default:#66707B;--shiki-dark:#BDC4CC}",{"title":245,"searchDepth":263,"depth":263,"links":547},[548,549,550,551,552],{"id":185,"depth":263,"text":186},{"id":205,"depth":263,"text":206},{"id":320,"depth":263,"text":321},{"id":356,"depth":263,"text":357},{"id":464,"depth":263,"text":465},"What a uxd workspace is, how ports keep them isolated, and the git worktree sharp edges worth knowing before you hit them.","md",null,{},{"icon":40},{"title":37,"description":559},"The uxd workspace model — one bare partial clone per project, one git worktree per ref — plus port isolation and the known caveats of worktrees.","fpPE3y2lhqV1baYuD3eyJkbZTDssD4F9zo6DtguISoU",[562,555],{"title":32,"path":33,"stem":34,"description":563,"icon":35,"children":-1},"Every ref form uxd accepts, the order it resolves them in, and how to force an interpretation.",1784975261264]