Workspaces and Collections

Storing a workspace in a folder

Keep a workspace as files in a folder you choose and share it with Git.

Overview

Every workspace is a folder of JSON files: one for the workspace itself, one for each environment, and a directory for each collection with a file for each request and a directory for each folder. Relay keeps this folder for you, inside its own storage, unless you choose a folder yourself.

When you keep a workspace in a folder of your own, such as one inside your project's Git repository, you can commit it, review changes in pull requests and share it with your team. Teammates open the same folder in their copy of Relay, and Relay picks up changes to the files as soon as they appear.

Some things stay on your Mac and are never written to the folder: secret variable values, auth credentials, client certificates, cookies, drafts, history and which environment is active.

Create a workspace in a folder

  1. In the sidebar, click the workspace menu and choose New Workspace….
  2. Enter a name and select In a Folder.
  3. Click Choose…, then enter a name for a new folder and click Choose. You can also choose an empty folder that already exists.
  4. Click Create.

Move a workspace to a folder

To move a workspace that Relay stores into a folder you choose:

  1. In the sidebar, click the workspace menu and choose Edit Workspaces….
  2. Select the workspace and click the Settings tab (gear).
  3. In the Storage section, click Move to Folder….
  4. Enter a name for a new folder, choose where to create it and click Move.

Relay writes the workspace into the new folder and then removes its own copy. You can also choose an empty folder that already exists, but not one with files in it.

Relay refuses a folder inside its own storage, inside another workspace's folder, or containing another workspace's folder, because a file can belong to only one workspace.

To move the workspace back, click Move Back into Relay in the same section. Relay copies the workspace into its own storage and leaves your folder and its files in place. Either move can be undone with Edit > Undo in the Workspaces window.

To see a workspace's files, click Reveal in Finder in the Storage section. This works for a workspace Relay stores too.

Open a workspace from a folder

To add a workspace someone else created, such as one in a repository you cloned, choose File > Open Workspace… or press Command-O, then choose the workspace's folder. You can also drag the folder onto a Relay window. The workspace opens in the current window.

A workspace folder is one with a relay-workspace.json file at its top level. Relay won't open a folder if:

  • It has no relay-workspace.json, or the file can't be read.
  • It was saved by a newer version of Relay.
  • It's inside Relay's own storage, or inside or around another workspace's folder.

If the workspace is already open, Relay tells you so and switches the window to it.

To stop showing a workspace you opened, remove it from Relay. For more information, see Creating and managing workspaces.

Opening a workspace keeps it in its folder, so your edits are saved there. To make a separate copy in Relay instead, or to copy one collection into your own workspace, use File > Import. For more information, see Importing Relay collections and workspaces.

Keep secrets out of the folder

Secret variables keep their values on your Mac, and so do authentication credentials such as tokens and passwords. The folder holds only their names, so you can commit it without exposing them. Each teammate enters their own values.

An auth field that contains nothing but variable references, such as {{token}} or {{user}}:{{password}}, is written to the folder, because a reference isn't a secret. For more information, see Keeping secrets on your Mac.

Share a workspace with Git

Commit the workspace's folder like any other files. Relay writes the same bytes for the same content and changes only the files you edit, so diffs show only real changes.

When files change on disk, because you pulled, switched branches or edited a file by hand, Relay reloads the workspace and shows a message such as "Reloaded Payments API after changes on disk." at the bottom of the window. What's on disk wins: if you edit the workspace in Relay at the same moment its files change, Relay keeps the files on disk. Reloading clears the undo history of every window.

Important

Scripts that arrive in changed files don't run until you allow them. After a pull, check each changed script and click Allow. For more information, see Allowing scripts to run.

If a pull leaves a file Relay can't read, such as one with merge conflict markers, the workspace becomes read-only until you fix it. For more information, see Resolving workspace file issues.

Understand file names

Relay names each file and directory after the item's name in lowercase, with hyphens between words: a request named List Users is saved as list-users.json. When two items in the same place would get the same name, Relay adds -2, -3 and so on.

An item keeps its file name until you rename it in Relay. If you rename a file yourself, Relay keeps using the new file name. The name shown in Relay always comes from inside the file.

Relay ignores hidden files and files that don't end in .json, so you can keep a README.md or .gitignore in the folder. For details about each file, see Workspace file format.

See Also