Git and collaboration

Getman keeps the whole project in a getman/ folder inside your Git repository. The folder is plain YAML, so requests, environments, the API contract and change packages go through the same review as the code. Getman never runs Git in the background on your behalf. Fetching, pulling, committing and pushing happen only when you choose them, or when you run Git yourself.

What is in the folder

getman/
  getman.yaml                   project: auth, headers, settings (no secrets)
  environments/*.yaml           variables; secret values are always blank
  collections/**.yaml           one file per request
  contracts/openapi.yaml        the current API contract
  changes/GT-<KEY>-<NNN>.yaml   change packages, with evidence and integration status

Secret values are never written. A secret variable keeps its name and a blank value, so teammates fill in their own values, and the keychain on each machine stores them. Literal credentials in auth settings are blank too.

Sync with the folder

Set the folder once under Project settings → Team sync with Choose folder. Then use:

• Write to folder to save the project’s current state into the folder.
• Load from folder to read the folder into the project.

When the folder and the app disagree, Getman asks which version to keep. Keep mine writes the app’s version to the folder. Take theirs replaces the project’s version with the folder’s.

The Git bar

The Git bar sits in the Changes view. It shows how far your branch is ahead of and behind the remote, and when you last fetched.

Button	What it does	When it runs
Fetch	Runs git fetch and updates what the remote has	Only when you click it
Pull	Runs git pull --ff-only. It never creates a merge commit	Only when you click it
Commit…	Commits only the Getman files you tick	Only when you click it
Push	Pushes the branch	Only when you click it

Getman uses your installed Git, with your SSH keys and credentials. Push stays disabled until the branch has an upstream. Run git push -u origin <branch> once to set it.

Getman refuses a pull when you have local changes or the branch has diverged. Commit or discard the local changes first. A diverged branch needs a merge or rebase in Git. Merges and conflicts are always resolved in Git.

What Getman does on its own

Getman reads the folder and the fetched remote branch, so the Inbox stays current without any network call. It also:

• flags incoming change packages and incoming request or contract edits after a Fetch
• detects conflict markers and invalid files, and refuses to load them
• asks before a pull replaces requests you have changed

Getman refuses to load a file that still has conflict markers or is invalid YAML. Fix the file in Git first.

The Changes view

Open the Changes view from the rail, or with ⌘⇧G. It has four modes:

Mode	Shows
Inbox	Changes that need action from you: conflicts, breaking changes, failed runs, incoming packages and pending work
Completed	Changes you have reported or verified for your consumer name
All changes	Every change package, highest ID first
Timeline	Every change package, newest first, with its author and verification label

Set I integrate as to your consumer name, such as web. The Inbox then shows the changes that name must act on. An incoming change package that you have not pulled is marked Not pulled yet.

Commit and review

A good commit for a backend change includes the code and the getman/ files together, so the reviewer sees the contract, the examples and the code in one place.

1. Open Commit… and tick the Getman files that belong to the change.
2. Write a message that names the change package, such as GT-SHOP-001: order totals in cents.
3. Commit, then push.

Only the ticked files are committed. Getman leaves the rest of the folder untouched, so unrelated edits do not slip into the commit.

Git tips

• Review the YAML diff in your normal Git tool. Each request is one file, so a change to one call is one small diff.
• Keep the getman/ folder in the same repository as the code it describes, so both move together.
• If two people create the same change ID, one of them renames the file and the id: line to the next free number, then commits. Troubleshooting covers this case.

Next steps

• Team workflow follows one backend change from Alice to Bob, step by step.
• Contracts explains the file that the change packages are checked against.