treramey · September 25, 2024 15:08 · Oct 24, 2019 · Aug 23, 2019 · Aug 23, 2019
diff --git a/Git Worktree Overview.md b/Git Worktree Overview.md
@@ -1,4 +1,6 @@
-# What is it?
+# `git worktree`
+
+## What is it?
 
 [Git worktree](https://git-scm.com/docs/git-worktree) it a git feature which allows you to checkout a single repository into multiple locations on your filesystem.
 It has a few rough edges, but if you follow a few simple rules it can be make context switching much easier than git's other mechanisms, such as stashing or switching branches.
@@ -10,7 +12,7 @@ My folder structure will usually look something like this:
 `       hotfix_branch_1/` ← A quick hotfix I need to make
 
 
-# Creating Worktrees
+## Creating Worktrees
 1. Create the top-level folder: `mkdir MyRepo`
 1. Checkout the repository's master branch as a normal checkout: `cd MyRepo; git clone <repo url> master`
 1. Add a branch: `cd master; git worktree add -b <branch_name> ../<folder_name> HEAD`
@@ -19,7 +21,7 @@ My folder structure will usually look something like this:
 1. When you need to create a new branch, make sure to create it from the branch you want to base it on (often, this is `master`)
 
 # Removing Worktrees
-1. `git worktree rm <path_to_worktree>` from a directory containing your worktree
+1. `git worktree remove <path_to_worktree>` from a directory containing your worktree
 1. (Optional) Delete the local branch with `git branch -D branch_name`
 1. (Optional) Delete the remote branch with `git push <remote> :<branch_name>`
 

diff --git a/Git Worktree Overview.md b/Git Worktree Overview.md
@@ -1,6 +1,6 @@
 # What is it?
 
-[Git worktree]() it a git feature which allows you to checkout a single repository into multiple locations on your filesystem.
+[Git worktree](https://git-scm.com/docs/git-worktree) it a git feature which allows you to checkout a single repository into multiple locations on your filesystem.
 It has a few rough edges, but if you follow a few simple rules it can be make context switching much easier than git's other mechanisms, such as stashing or switching branches.
 My folder structure will usually look something like this:
 

diff --git a/Git Worktree Overview.md b/Git Worktree Overview.md
@@ -0,0 +1,29 @@
+# What is it?
+
+[Git worktree]() it a git feature which allows you to checkout a single repository into multiple locations on your filesystem.
+It has a few rough edges, but if you follow a few simple rules it can be make context switching much easier than git's other mechanisms, such as stashing or switching branches.
+My folder structure will usually look something like this:
+
+`MyRepo/`
+`       master/` ← The original checkout, using something like `git clone <repo url> master`
+`       feature_branch_1/` ← A feature branch
+`       hotfix_branch_1/` ← A quick hotfix I need to make
+
+
+# Creating Worktrees
+1. Create the top-level folder: `mkdir MyRepo`
+1. Checkout the repository's master branch as a normal checkout: `cd MyRepo; git clone <repo url> master`
+1. Add a branch: `cd master; git worktree add -b <branch_name> ../<folder_name> HEAD`
+  - `branch_name` and `folder_name` should likely be the same to avoid confusion (in larger projects, I would prepend `branch_name` with my username)
+1. Switch to that branch: `cd ../my_branch`
+1. When you need to create a new branch, make sure to create it from the branch you want to base it on (often, this is `master`)
+
+# Removing Worktrees
+1. `git worktree rm <path_to_worktree>` from a directory containing your worktree
+1. (Optional) Delete the local branch with `git branch -D branch_name`
+1. (Optional) Delete the remote branch with `git push <remote> :<branch_name>`
+
+# Gotchas
+- In a worktree, the `.git` folder is just a file, so scripts modifying repo settings like git hooks may fail. The git hooks in the original repository apply to its worktrees.
+- You can actually checkout a worktree _inside_ of the repository by leaving out the `../` before folder name. This is not recommended.
+- You can not have the same branch checked out in multiple worktrees