Git has no concept called a workspace. The word gets used for three different things - the working tree, a git worktree, and a multi-repository directory - and the commands that apply to one do nothing for the others.
Search for this phrase and you get a mix of answers that appear to contradict each other. They do not; they are answering three different questions. Working out which one you are asking takes about thirty seconds and saves a lot of confusion.
Table of contents
- Meaning one: the working tree
- Meaning two: git worktree
- Meaning three: a multi-repository directory
- Working out which one you need
- Worktrees in practice
- How this fits the rest of the stack
- FAQ
Meaning one: the working tree
The most common intent. Git’s own term is working tree, and it is the directory of actual files you edit, as opposed to the object database in the hidden git directory.
Git’s mental model has three areas, and understanding the boundaries between them explains most of the commands people find confusing:
- Working tree - the files on disk that your editor opens.
- Index, also called the staging area - what will go into the next commit.
- Repository - the committed history, stored as objects.
# What is different in each area
git status
# Working tree vs index - unstaged changes
git diff
# Index vs last commit - staged changes
git diff --staged
# Working tree vs last commit - everything uncommitted
git diff HEADMoving between the areas is what the everyday commands do. git add copies from working tree to index. git commit moves the index into the repository. git restore pulls a file back from the index or a commit into the working tree.
# Discard working tree changes to one file - destructive
git restore path/to/file
# Unstage without losing the edit
git restore --staged path/to/file
# Set the whole working tree back to the last commit - destructive
git reset --hardBoth destructive commands above throw away uncommitted work with no recovery path, because Git never stored it. If you want the changes back later, git stash is the safe version.
Meaning two: git worktree
This is a real Git feature with a real command, and it is genuinely underused. git worktree lets one repository have several working trees checked out simultaneously, each on a different branch, in different directories.
# From inside your repo, check out a branch in a sibling directory
git worktree add ../myproject-hotfix hotfix/session-bug
# Create a new branch and a worktree for it at once
git worktree add -b feature/search ../myproject-search
# See them all
git worktree list
# /home/me/myproject ab29059 [main]
# /home/me/myproject-hotfix cc7d01a [hotfix/session-bug]
# Clean up when done
git worktree remove ../myproject-hotfixThe value is that switching branches no longer disturbs your working directory. The classic case: you are deep in a feature with a half-finished refactor, and an urgent fix comes in. Without worktrees you stash, switch, fix, switch back, and pop - and hope the stash applies cleanly.
With a worktree, the fix happens in a separate directory with its own checkout, its own build artifacts, and its own running dev server. Your feature branch is untouched the entire time.
They share one object database, so a fetch in any worktree makes the new objects available to all of them, and disk usage is far lower than a second clone. Two constraints: the same branch cannot be checked out in two worktrees at once, and deleting the directory without running git worktree remove leaves a stale administrative entry that git worktree prune cleans up.
Meaning three: a multi-repository directory
The third usage comes from editors and from tools that manage many repositories at once. VS Code has a workspace concept - a saved set of folders and settings - which is an editor feature with no Git meaning whatsoever.
There are also third-party tools that sync a directory of repositories against an organisation on a hosting provider, keeping local clones in step with what exists remotely. Those are useful if you work across dozens of repositories, and they are not part of Git.
Git’s own answers in this space are submodules and subtrees, and both come with real costs.
# Submodule - a pointer to a specific commit in another repo
git submodule add https://github.com/org/shared-lib vendor/shared-lib
git submodule update --init --recursive
# Subtree - the other repo's files merged into yours
git subtree add --prefix=vendor/shared-lib \
https://github.com/org/shared-lib main --squashSubmodules keep the histories separate and pin an exact commit, but every clone needs the extra init step and forgetting it produces an empty directory and a confusing build failure. Subtrees put the files directly in your repository, so a plain clone just works, at the cost of a larger repository and a fiddlier update path.
If you are reaching for either to solve a shared-code problem, it is worth asking whether a published package would be simpler. Both features exist because sometimes it would not be, but they are heavier than they look.
Working out which one you need
A short decision list. Match your actual symptom to the meaning.
- “How do I undo my uncommitted changes?” - working tree. Use
git restoreorgit stash. - “How do I work on two branches at once without stashing?” -
git worktree add. - “How do I keep several related repositories in step?” - submodules, subtrees, a package registry, or an external multi-repo tool.
- “How do I open several projects in one editor window?” - editor feature, nothing to do with Git.
The reason this matters beyond terminology is that searching the wrong term wastes time. Someone with a stash-and-switch problem searching for workspace finds submodule documentation, concludes Git is baroque, and keeps stashing. The command they wanted was one line.
Worktrees in practice
A few habits make worktrees pleasant rather than another thing to manage.
Keep them as siblings of the main checkout, not nested inside it. A worktree inside the repository directory will confuse tooling, get picked up by file watchers, and occasionally end up in a build.
# Good - siblings
~/code/myproject/
~/code/myproject-hotfix/
# Bad - nested
~/code/myproject/hotfix/Remember that each worktree needs its own dependency install. They share Git objects, not node_modules or a Python virtual environment. That is usually what you want - a hotfix built against the dependency versions on that branch is the whole point - but it is a surprise the first time.
Worktrees also pair well with long-running builds and with agents or scripts that check out code. Giving an automated process its own worktree means it cannot change the branch out from under you, which is a failure mode that produces genuinely baffling bug reports.
# Prune stale entries after deleting directories by hand
git worktree prune
# Lock a worktree on removable storage so prune leaves it alone
git worktree lock ../myproject-usbHow this fits the rest of the stack
Multiple checkouts are a local convenience; the thing they usually lead to is wanting more than one version of the app running at once. Push a branch to RunxBuild and you get a build log, a live route, and rollback to the previous deploy, so comparing two versions does not mean rebuilding one from memory. The RunxBuild hosting calculator shows what a second service and its database cost as separate line items, which is the question a second checkout eventually raises.
Useful related references:
- Replit vs Cursor: A Browser Workspace Against an AI Editor
- How to Rename a File in Linux: mv, rename, and git mv
- Git vs GitHub vs GitLab: One Is a Program, Two Are Companies
- Services on RunxBuild
FAQ
What is a workspace in Git?
Git has no feature by that name. People use it for three different things: the working tree, which is the files on disk you edit; a git worktree, which is a second checkout of the same repository on another branch; and an editor or tool concept for a directory holding several repositories.
What is the difference between the working tree and the repository?
The working tree is the directory of files you edit. The repository is the object database of committed history, stored in the hidden git directory. Between them sits the index, or staging area, which holds what will go into the next commit.
What is git worktree used for?
Checking out more than one branch of the same repository at the same time, in separate directories. It removes the stash-switch-fix-switch-pop dance when an urgent fix arrives during a feature. All worktrees share one object database, so disk usage is far lower than a second clone.
Can I check out the same branch in two worktrees?
No. Git refuses, because two working trees advancing the same branch independently would produce conflicting states. Create a new branch for the second worktree, or use a detached checkout if you only need to read the code.
Should I use submodules or subtrees for shared code?
Submodules keep histories separate and pin an exact commit, but every clone needs an extra init step that people forget. Subtrees put the files in your repository so a plain clone works, at the cost of size and a fiddlier update path. Before either, consider whether a published package is simpler.