# Refresh a Workspace

> Bring a workspace up to date with its branch or pull request, and choose what happens to the changes you made in it.

By the end of this guide, a workspace you opened earlier shows the latest commits of its branch or pull request. When the author pushes a fix, you want to see it without opening a new workspace or losing the notes you left in the old one, and `sync` does that.

## Before you start

You'll need a workspace you've already opened, like the pull request from [Review a pull request](https://testlane.dev/docs/guides/review-a-pull-request). We'll use `42` in a project called `my-project`.

## Bring a workspace up to date

::steps{level="3"}

### See whether it has changes

```bash
testlane my-project list
```

```
SLUG        KIND    BRANCH      STATUS  PORT  AGE  LAST USED
feat-login  branch  feat/login  dirty   4153  2h   1h
pr-42       pr      pr/42       clean   4164  4h   3h
```

A `clean` workspace syncs straight away. A `dirty` one has uncommitted changes, and a plain `sync` refuses to touch it, so pick a flag from [Keep or drop your changes](#keep-or-drop-your-changes) first.

### Preview what sync will do

```bash
testlane my-project 42 sync --dry-run
```

```
git -C /home/you/dev/testlane/my-project/trees/pr-42 fetch origin refs/pull/42/head --no-tags
git -C /home/you/dev/testlane/my-project/trees/pr-42 reset --hard FETCH_HEAD
```

`--dry-run` prints the git commands and changes nothing.

### Sync it

```bash
testlane my-project 42 sync
```

```
→ fetching pull/42
→ 05cc56ae → 6e1c1243, 3 file(s) changed
```

`sync` fetches the ref again and hard-resets the workspace to it. The last line shows the old and new commits and how many files changed, so you can tell at a glance whether anything did.

### Run it again

```bash
testlane my-project 42 run dev
```

```
→ worktree ready (reused)
→ setup up to date (cache hit)
```

`sync` moves the code but doesn't install anything. The next `run`, `exec`, `shell` or `start` runs your `[setup]` again when the files in `setup.cache_key` have changed, like a lockfile the new commits touched, and skips it otherwise.

::

## Keep or drop your changes

When a workspace has uncommitted changes, a plain `sync` stops with `E_GIT` (exit `5`) rather than throw them away:

```
→ fetching origin/feat/login
error(E_GIT): worktree has uncommitted changes
hint: re-run with --stash or --discard, or commit them
```

Pick one of two flags to say what happens to them:

| Flag        | What it does                                                         |
| ----------- | -------------------------------------------------------------------- |
| `--stash`   | Stashes your changes with `git stash`, then resets                    |
| `--discard` | Throws your changes away, untracked files included, then resets       |

```bash
testlane my-project feat/login sync --stash
```

```
→ fetching origin/feat/login
→ c3bcd0c1 → 0bcaf7c8, 2 file(s) changed, stashed stash@{0}
```

We recommend `--stash` when the changes are worth keeping, like debug logging you'll want back, since `git stash list` in the workspace still has them. `--discard` is for changes you've finished with, like a `console.log` you've already read.

::warning
`--discard` deletes your uncommitted changes and untracked files for good. Run `sync --discard --dry-run` first to see the `git reset` and `git clean` it will run.
::

The flags can't be combined, so passing two is a usage error, `E_USAGE` (exit `2`).

## Start a workspace over

`--fresh` removes the workspace and creates it again from the ref, which is what you want when the workspace itself is in a bad state, like a half-finished install or a `node_modules` you no longer trust:

```bash
testlane my-project feat/login sync --fresh
```

```
→ fetching origin/feat/login
→ worktree ready: /home/you/dev/testlane/my-project/trees/feat-login
→ recreated feat-login
```

The new workspace has no install yet, so the next `run` runs your `[setup]` in full. Keep in mind that `--fresh` refuses a workspace with uncommitted changes, with `E_GIT` (exit `5`), so commit or stash them first. To throw them away and start over, use `testlane my-project feat/login rm --force`, then open the ref again.

## Fetch without resetting

`sync` is for a workspace that already exists. To fetch the ref as part of the command you were going to run anyway, add `--fetch` to it:

```bash
testlane my-project 42 checkout --fetch
testlane my-project 42 run dev --fetch
```

For a pull request, `--fetch` fetches it again and fast-forwards the workspace when it can. When the pull request was force-pushed, it warns and leaves the workspace as it is, so run `sync` then. For a branch, `--fetch` updates `origin/<branch>` and leaves the workspace where it is, so `sync` is what moves it.

## Where to go next

Here's where to go from here:

- [Workspace verbs](https://testlane.dev/docs/cli/workspace-verbs) lists every flag of `sync` and `checkout`.
- [Clean up workspaces](https://testlane.dev/docs/guides/clean-up-workspaces) shows how to remove the workspaces you've finished with.
- [Seed local files](https://testlane.dev/docs/guides/seed-local-files) shows how to copy a seeded file again with `--reseed`.
