Understand agent workspaces with a small Git lab

1. Create a disposable three-part project

Open a new terminal and run the complete block. mktemp chooses a fresh directory each time, which makes it safe to repeat the exercise without overwriting an existing project. The lab configures an example author only in this repository and disables commit signing and hooks there, so your normal project settings stay intact.

The three directories represent separate responsibilities. Nothing needs to compile. That is deliberate: if this tiny example fails, you can diagnose directory state before adding model behavior, package installation or an application server.

set -eu
lab_dir=$(mktemp -d "${TMPDIR:-/tmp}/current-source-lab.XXXXXX")
git init -q -b main "$lab_dir/repo"
git -C "$lab_dir/repo" config user.name "Current example"
git -C "$lab_dir/repo" config user.email "example@example.invalid"
git -C "$lab_dir/repo" config commit.gpgsign false
git -C "$lab_dir/repo" config core.hooksPath /dev/null
mkdir -p "$lab_dir/repo/apps/web" "$lab_dir/repo/services/api" "$lab_dir/repo/docs"
printf 'button=Save\n' > "$lab_dir/repo/apps/web/ui.txt"
printf 'status=ready\n' > "$lab_dir/repo/services/api/status.txt"
printf 'Owner: example team\n' > "$lab_dir/repo/docs/ownership.txt"
git -C "$lab_dir/repo" add .
git -C "$lab_dir/repo" commit -qm 'Create three-part example'

The first commit should succeed without asking for a remote or credentials. If git cannot be found, install Git through its official distribution for your operating system and reopen the terminal. If your Git version rejects the initial-branch option, update it before continuing. Save the printed workspace path at the end of the lab if you want to inspect it later.

2. Give the edit a separate workspace

A worktree gives the task its own checked-out files and branch while sharing the repository’s object storage. The sparse-checkout command selects the interface directory for this task. In cone mode, files at parent directory levels may also be included; this fixture places its content inside separate directories so the expected scope is simple.

Make the change and commit it in the interface worktree. Notice that every command states its repository with -C. This keeps an accidental terminal-directory change from sending a command to your real project.

git -C "$lab_dir/repo" worktree add -q -b ui-copy "$lab_dir/ui"
git -C "$lab_dir/ui" sparse-checkout set --cone apps/web
printf 'button=Save draft\n' > "$lab_dir/ui/apps/web/ui.txt"
git -C "$lab_dir/ui" add apps/web/ui.txt
git -C "$lab_dir/ui" commit -qm 'Clarify the save action'

At this point, the original repository still contains button=Save. The separate worktree contains button=Save draft. The branch ui-copy has its own commit. No merge has happened, and no server has received the change.

3. Check the output before accepting it

Run all of these assertions. Each test returns a nonzero exit status if its condition fails; set -e stops the shell block at the first failure. The checks cover isolation, visible file scope, the exact changed path and a clean committed state. A clean status alone would miss an edit made to the wrong file.

test "$(cat "$lab_dir/repo/apps/web/ui.txt")" = 'button=Save'
test "$(cat "$lab_dir/ui/apps/web/ui.txt")" = 'button=Save draft'
test ! -d "$lab_dir/ui/services"
test ! -d "$lab_dir/ui/docs"
test "$(git -C "$lab_dir/ui" diff --name-only main...HEAD)" = 'apps/web/ui.txt'
test -z "$(git -C "$lab_dir/ui" status --porcelain)"
printf 'PASS: separate edit, scoped files, one-file diff, clean worktree\n'
printf 'Example retained in: %s\n' "$lab_dir"

The final success message must be exactly PASS: separate edit, scoped files, one-file diff, clean worktree. If it is absent, stop and inspect the failing condition. The next line gives the temporary path. Keep that output with your review notes.

To confirm the checker can detect a mistake, run the negative check below. It deliberately asks whether the change touched the API file. The expected result is PASS: wrong-file expectation rejected. If it prints FAIL, the fixture has changed and needs inspection.

if test "$(git -C "$lab_dir/ui" diff --name-only main...HEAD)" = 'services/api/status.txt'; then
  printf 'FAIL: unexpected API change
'
  exit 1
else
  printf 'PASS: wrong-file expectation rejected
'
fi

4. Review and integrate the change

Read the diff before merging. It should show one removed line, button=Save, and one added line, button=Save draft, under apps/web/ui.txt. Any additional path means the result does not match this assignment. The fast-forward-only merge below stops rather than resolving an unexpected branch divergence on your behalf.

git -C "$lab_dir/repo" diff main...ui-copy -- apps/web/ui.txt
git -C "$lab_dir/repo" merge --ff-only ui-copy
test "$(cat "$lab_dir/repo/apps/web/ui.txt")" = 'button=Save draft'
test "$(cat "$lab_dir/repo/services/api/status.txt")" = 'status=ready'
test "$(cat "$lab_dir/repo/docs/ownership.txt")" = 'Owner: example team'
printf 'PASS: merged label; API and ownership unchanged
'

Keep a short handoff: assignment, starting branch, changed path, verification result and the final commit from git log -1 --oneline. This gives the next person enough information to compare the result with the request. In a real application, add the relevant unit and end-to-end checks before integrating. This text fixture says nothing about whether a real Save button works.

5. Recover from an unexpected result

The temporary folder is intentionally retained so you can inspect the evidence. You can remove that specific lab folder through your file manager after you have finished reviewing it. There is no cleanup command here that could accidentally target your project.

6. Apply the lesson to a real agent task

For a real task, replace the text fixture with one narrowly scoped change, such as a button label and its interface test. Assign a separate worktree, record the base revision and identify the permitted files. Capture the diff and the checks in the handoff. When two tasks need the same file, make that dependency explicit before running them concurrently.

Use actual process isolation for different trust boundaries. Worktrees share Git objects, and a process running as your user has your filesystem permissions. Sparse checkout reduces visible tracked files; it does not restrict what a sufficiently privileged tool can access.

Measure a representative baseline before optimizing. Record checkout time, dependency time, test time, total elapsed time and any missing-file failures. Compare several runs with the same task and environment. Report the individual timings and explain any excluded run. This gives you evidence for the next change without treating the speed of this tiny lab as a production benchmark.

Guide history

Revisions preserve the original instructions. A source recheck alone does not create a new revision.

Revision 1 · New local Git exercise with exact inputs, assertions, a negative check, integration and troubleshooting.

Continue learning