Git

DialCatz does Git in two ways, and this page covers both:

1. Folder workspaces — a workspace saved as plain files in a folder, usually inside a Git repository. Your collections and environments then travel with the code: review them in a pull request, branch them with a feature, and pull your teammates’ changes like any other file. A small Git panel commits, pulls and pushes just those files.
2. The Git section (Git in the rail) — a full Git client for whole repositories: changes, history, branches, tags, stashes, worktrees, pull requests, hosting accounts and SSH keys.

Git is the no-server way to share a workspace. For live sync with roles and presence, there is DialCatz Den; a workspace is one or the other.

DialCatz runs the git installed on your computer, with your own config, credential helper and SSH agent. If Git is missing, DialCatz says so; on a Mac, xcode-select --install installs it.on Windows, install Git for Windows.

Share a workspace through a Git repository

Make a folder workspace

There are several ways in — pick the one that matches where you start.

A new workspace in a folder

1. Workspace picker → New workspace… → In a folder.
2. Give it a Name, pick the parent folder under Inside, and a Folder name.
3. Optionally tick Connect it to a Git repository now to set up the remote in the same step.
4. Create.

A workspace from a Git repository

1. Workspace picker → New workspace… → From a Git repository.
2. Pick a repository (from a connected account, or by URL), where to Clone into, and the Folder name.
3. Clone & open. DialCatz opens the DialCatz workspace already in the repository, or starts a new one in its dialcatz/ folder.

An existing folder — workspace picker → Open a folder as a workspace…. A folder that already holds a workspace opens it; an empty folder starts a new one.

An existing local workspace — workspace picker → Move to a folder…. The workspace is written out as files and keeps working as before. It refuses a folder that already holds a workspace, or one another workspace already uses.

From the Git section — open a repository that holds a workspace and press Open it, or after a clone choose Open its workspace or Start a workspace in it.

From DevCatz — when importing a DevCatz site, tick Save in the site’s repository (see DevCatz site workspaces).

Where the workspace sits in a repository

A workspace lives either at the repository root, or in a dialcatz/ folder inside it — the usual choice for a project repository, so the API requests sit next to the code without crowding the root. A new workspace in a repository is named after the repository (or the DevCatz site), not “dialcatz”.

my-shop/                       ← your project's repository
├── app/  src/  …              ← your code, untouched
└── dialcatz/                  ← the DialCatz workspace
    ├── dialcatz.yml
    ├── collections/
    │   └── shop-api/
    │       ├── collection.yml
    │       ├── list-products.request.yml
    │       ├── create-product.request.yml
    │       └── orders/
    │           ├── folder.yml
    │           └── get-an-order.request.yml
    └── environments/
        ├── local.env.yml
        └── staging.env.yml

The files on disk

Everything is YAML, one small file per item, so a change to one request is a change to one file — easy to read in a diff and easy to merge.

Names on disk are slugs of the item’s name: lower-case, with dashes, at most 60 characters (“Get an order” → get-an-order.request.yml). Two items with the same slug get -2, -3 and so on.

Each file keeps the item’s id. That is what links a request to its collection’s environment, and what lets a rename — of the item in DialCatz, or of the file by hand — keep everything connected. A file you write by hand without an id gets a stable id made from its path. A copied file whose id is already taken gets a new one of its own.

Empty fields are left out so files stay short. A request file looks like this (the id is an example):

id: r_8f2k1q
name: List products
sort: 1
request:
  method: GET
  url: "{{baseUrl}}/products"
  params:
    - key: page
      value: "1"
      enabled: true
  auth:
    mode: bearer
    token: "{{token}}"
  tests: |
    dc.test('ok', () => dc.expect(dc.response.status).toBe(200));

And an environment file holds only names and flags:

id: e_3m9xd0
name: Staging
variables:
  - key: baseUrl
    enabled: true
  - key: token
    enabled: true
    secret: true

What is committed and what stays on this computer

The local-only parts are kept in DialCatz’s own workspace file on this computer, next to the folder link.

Each teammate who opens the workspace fills in their own values — their own token, their own local baseUrl. There are no secret files in the folder, so there is nothing to add to .gitignore: commit the whole workspace folder (dialcatz.yml, collections/ and environments/).

Auth values typed into a request go into the files

This is the one thing to watch. A literal value typed straight into a request’s or collection’s Auth — a Bearer token, a Basic password, an API key — is part of the request, so it is written into the YAML as it is, and it reaches the repository with your next commit.

Keep secrets in environment variables instead:

1. Add a variable such as token to your environment and tick Secret.
2. In the Auth pane, write {{token}} instead of the token itself.

Now only the name {{token}} is in the files; the value stays on this computer. The same goes for a key typed into a header or a body — use a variable.

If a real token did get committed, change the request, commit again, and revoke the token with its service: it is still in the repository’s history.

Live with the folder

• DialCatz writes only the files whose text changed, and deletes the files of items you removed.
• It watches the folder. Edits from outside — a git pull in the terminal, a branch switch, a teammate’s change, your editor — show up in DialCatz within about 0.4 seconds. Its own writes are ignored for about 1.2 seconds, so they do not come back as changes.

When the folder or a file has a problem

• The folder is gone (an unplugged drive, a moved repository): The folder … is not there any more. Changes stay on this computer until it is back. Nothing is lost; DialCatz writes everything once the folder returns.
• A file cannot be read — merge conflict markers, or a typo in hand-written YAML: Some files could not be read: … Fix them (or Abort merge in Git) — until then changes here are not written to the folder. DialCatz stops writing on purpose, so it never deletes or overwrites a file it could not understand. Fix the file (or abort the merge) and it carries on.

The status strip

Under the workspace picker, a folder workspace shows a status strip:

• the branch · N changes, committed or conflicts · ↑ commits to push · ↓ commits to pull;
• or, when the folder is not in a repository, Saved as files in <path>.

Two buttons sit beside it: Git (Commit, pull and push this workspace’s files) opens the Git panel, and the folder icon (Show the folder) reveals it in FinderFile Explorer. The strip refreshes when the window gets focus and when you switch workspace.

The workspace Git panel

The Git button opens a panel made for this one workspace.

The header shows the branch, and → upstream, not pushed yet or no remote. Its buttons:

• ↻ — Check the remote again (a git fetch).
• Pull — Get your team’s commits, with a badge counting them.
• Push — Send your commits, with a badge counting them.

Not in Git yet? The panel says This folder is not in a Git repository yet… and offers Start Git here (runs git init) and Connect to a repository….

Connect to a repository

Choose where the remote comes from:

• Your repositories — the repositories of a connected account, with a search box. The SSH toggle uses git@… addresses instead of HTTPS.
• New repository — a name, Private, then Create on GitHub (or GitLab and the others): the repository is made on the host for you.
• URL — paste any Git address.

Then Connect. What happens:

1. If the folder is not a repository yet, DialCatz runs git init -b main.
2. It adds origin (or points the existing one at the new URL) and fetches it.
3. Then, depending on the remote:
   • An empty remote waits for your first Push.
   • A remote with commits becomes the upstream — its default branch, else main or master.
     • With no local commits yet, your workspace is placed on top of the remote’s history: your files show as changes to commit.
     • With local commits, the remote is merged in (unrelated histories are allowed).
   • Any conflicts are left for you to settle — see Conflicts.

The panel’s footer always shows origin: <url>, with Change… to point it elsewhere.

Changes and commit

Changes in this workspace (N) lists the changed items by what they are, not by file name — Request: Get users, Environment: Staging, Collection: Shop API, Folder: Orders, Workspace: Shop — each with a letter:

Click an item to see its diff.

Write a message in the commit box (What changed? e.g. Add the order endpoints) and press Commit N or mod+enter. The panel commits this workspace’s files only — the rest of the repository is left as it is. It stages and commits just the workspace folder, so your half-finished code changes are not swept into the commit. (During a merge, the merge commit takes everything, as Git requires.)

After a commit the toast says Committed — Push to share it.

Pull and push

• Pull fast-forwards when it can, else makes a merge — it never rebases. You see Up to date with the remote, Pulled and merged, or Pulled, with conflicts to settle.
• Push is a plain push; the first push of a branch also sets its upstream (git push -u origin HEAD). The toast says Pushed.

Friendly errors tell you the next step, for example:

Conflicts

When you and a teammate changed the same lines, the panel shows a banner: N files changed on both sides. Open the folder, keep the right lines in each file (between <<<<<<< and >>>>>>>), then Commit.

1. Show folder and open each conflicted file in your editor.
2. Keep the right lines and delete the markers. Because each item is its own small file, a conflict is usually a line or two in one request.
3. Back in the panel: The merge is ready: Commit to finish it. Press Commit.

Or press Abort merge to go back to how things were before the pull. While a file still has markers in it, DialCatz does not write to the folder (see above), so nothing gets overwritten mid-merge.

Sign-in for pull and push

DialCatz never asks for a password in a terminal — Git runs with prompts switched off (GIT_TERMINAL_PROMPT=0, and SSH in batch mode). It signs in with:

• your own setup — your credential helper and SSH agent, exactly as in the terminal;
• or, for an HTTPS remote whose host matches a connected account, that account’s token. It is handed to Git through a small GIT_ASKPASS helper and lives only in the process’s environment, never on disk — the helper file (git/askpass.sh in DialCatz’s data folder) holds no secret. The user name sent is x-access-token for GitHub, oauth2 for GitLab, and the account’s user name for other hosts.

Limits of folder workspaces

• Personal workspaces only. A team workspace syncs with its DialCatz Den and cannot use a folder: A team workspace syncs with its DialCatz Den; make a personal workspace for a folder. To share the same collections both ways, copy them with Copy to workspace….
• The panel commits only the workspace folder. For the rest of the repository — your code — use the Git section or your usual tools.
• Auth values typed into a request are written to the files — use {{variables}}.
• Values, globals, history and your sidebar arrangement stay local — each person fills in their own.
• DialCatz pauses writing while a file is unreadable, until it is fixed or the merge is aborted.
• It needs the system git.

Stop using the folder, or delete the workspace

• Stop using the folder… — DialCatz stops writing there; the files stay where they are. The workspace becomes an ordinary local one.
• Delete… on a folder workspace removes it from DialCatz only. The folder and its files stay, ready to open again.

DevCatz site workspaces

A site in DevCatz keeps its DialCatz workspace in <site>/dialcatz, inside the site’s own repository. So the site’s Git (in DevCatz) and the DialCatz workspace are the same repository: a commit can carry the new endpoint and the request that calls it.

To make one, import the site with Import → From DevCatz and tick Save in the site’s repository (see Import a DevCatz site). If the site’s repository already holds a workspace, the import says <site> keeps a DialCatz workspace in its repository… and offers Open its workspace.

The Git section

Git in the rail opens a full Git client for whole repositories. It is the same Git section as in DevCatz, so it works the same way in both apps.

The sidebar

• Repositories — every repository DialCatz knows: the repositories of your folder workspaces (added automatically), folders you added and repositories you cloned. Two buttons sit in the heading: Clone a repository… (the download icon) and + (Add a folder…). Each row shows:
  • the branch, or detached;
  • ● the number of changed files;
  • ↑ ahead and ↓ behind;
  • an operation in progress (a merge or rebase), or not in Git yet;
  • an icon when a DialCatz workspace is inside.
• Accounts — your connected hosting accounts (avatar, user name, host) — the same ones DevCatz uses, see Git and DevCatz — and Connect an account.
• This computer → SSH keys — the keys in ~/.ssh%USERPROFILE%\.ssh.
• The footer: git <version> · your own config and credentials. Accounts are shared with the Catzoid apps. — or git is missing: ….

Summaries refresh every 20 seconds while the Git section is open, and after every operation.

A repository’s page

The header has the repository’s name and path, Show folder, and — for folders you added — Remove… (Take <name> off the list?; the files stay). A folder that is not a repository yet offers Initialize repository (git init -b main).

The toolbar:

Every sync asks first — Fetch from every remote?, Pull into this branch?, Pull with rebase?, Push to the remote?, Force push? (which explains that --force-with-lease refuses if someone pushed since your last fetch). Long operations stream into Output and can be stopped with Cancel.

The info line shows the remotes (with links to their web pages, and (connect <Host> for pull requests) when no account matches), Last: the latest commit’s short id, subject and author, the number of stashes, and as <name> <email> with change.

The workspace strip appears when the repository holds a DialCatz workspace: open each one (<name> ↗), or — when it is not open in DialCatz yet — This repository holds a DialCatz workspace. Open it.

Identity, remote and operations in progress

• Identity — when Git does not know you yet: Who are you? Git needs a name and email for commits. Fill in the name and email, tick for every repository (–global) to set them for all repositories, and Save. The same box (Commit identity) opens from change in the info line.
• No remote — give a name (origin) and a URL, then Add remote.
• An operation in progress — a merge, rebase, cherry-pick, revert, or conflicts from applying a stash. The page lists the conflicted files, each with Open in editor and Mark resolved (stages it). Then Continue, Skip this commit (not for a merge) or Abort <operation>.

The page has five tabs: Changes, History, Branches & tags, Worktrees and Pull requests.

Changes

• Staged · N — what goes into the next commit. Unstage all, or − on a file.
• Changes · N — what is changed but not staged. Stage all and Discard all; per file ↗ (open in your editor), ↺ (discard) and + (stage). Discarding asks first: Edits are lost and new (untracked) files are deleted.
• The diff viewer shows the selected file, staged or working tree. A change with no text in it says No textual changes (mode change or binary file).
• The commit box — Commit message (first line = summary), Amend last commit, then Commit N or Commit & Push. mod+enter commits.
• The .gitignore box — Suggest lines proposes lines for the project’s detected stack; tick the ones you want and press Add N line(s). Edit… opens the editor.

The .gitignore editor

When the repository has no .gitignore, the editor says No .gitignore yet and offers:

• Add .gitignore — starts from suggested lines: .env, .env.*, !.env.example, node_modules/, dist/, build/, .venv/, __pycache__/, vendor/, *.log, .DS_Store, .idea/ and .vscode/*;
• Start empty.

mod+S saves and Esc closes.

History

• A branch select (<branch> (current) or any other branch) and a search box (Message, author or commit id).
• Commits with their branch and tag labels, short id, author and date. Older commits loads 100 more.
• A selected commit shows its patch, with a button to copy its full id, and these actions:

Branch tools work against a Base you pick:

• Rebase onto it… — replays your branch on top of the base (with autostash). It warns that commits you already pushed will need a force push with lease.
• Squash since it… — turns every commit since the base into one, with your message. It needs at least two commits and a clean working tree.

Branches & tags

• Local branches — a table of Branch, Upstream (with ↑/↓, or local only) and Last commit. Per branch: Switch, Merge (into the current branch; a merge commit is made unless it fast-forwards) and Delete. Delete is refused for a branch that is not merged; Delete anyway then runs git branch -D.
• New branch — a name (feature/new-thing) and from <branch>, then Create & switch.
• Remote branches · N — show or hide them; Check out makes a local branch that tracks one.
• Stashes — an optional message and Stash changes (new files included); then Apply, Pop or Drop per stash.
• Tags — a name (v1.0.0) and an optional message (which makes an annotated tag), then Tag <sha>. Per tag: Push and Delete. Delete removes the local tag only; a tag already pushed stays on the remote.

Worktrees

A worktree is a second working folder of the same repository, on another branch — handy for checking a teammate’s branch without stashing your own work.

• A table of Folder and Branch, with badges main, locked, folder gone and ↑unpushed.
• Remove… deletes a worktree (with a force option when it has changes); Prune cleans up worktrees whose folder is gone.
• New worktree — New branch (a name, and from which branch) or Existing branch, then Choose folder & create…. The suggested folder is <repo>-<branch> next to the repository.

Pull requests

The tab is called Merge requests for GitLab. It needs the repository’s remote to be on a connected account; otherwise it says Connect <Host> to see pull requests with Connect an account.

The list shows the open pull requests: number, title, a draft badge, head → base, author, last update, and:

• checks — ● success, pending or failure (GitHub check runs, GitLab pipelines);
• review state on GitHub — approved (N), changes requested or review required.

Refresh reloads the list, On <Host> opens it on the web, and Check out fetches a pull request into a local branch pr/<n> (or its head branch) and switches to it.

New pull request from <branch> opens a form: Title, into the base branch, a body in Markdown, Draft, then Open pull request. The branch must be pushed with no unpushed commits. If it already has one open, you see <branch> already has #N open… Push new commits to update it.

Clone a repository

Clone a repository… (the download icon in the sidebar):

• Repository URL — https://… or git@….
• Into — the parent folder. It defaults to the folder most of your repositories are in, else ~/Projects%USERPROFILE%\Projects, else your home folder.
• Folder name, Branch (blank for the default branch), and Latest commit only for a shallow clone.

Progress shows live; Cancel stops the clone and deletes what was downloaded. When it is done, Cloned into … offers Open its workspace (when the repository holds one) or Start a workspace in it.

From an account’s page you can also browse its repositories — with private and fork badges, the last update, a search box and the SSH toggle — and press Clone…, or Open for one already on this computer.

Connect an account

A connected account lets DialCatz list your repositories, create new ones, sign in for HTTPS pull and push, show pull requests and upload SSH keys.

1. Connect an account, pick the host.
2. Change the Server URL for a self-hosted instance (for example https://git.company.com).
3. Create one ↗ opens the host’s token page with the scopes filled in. Create the token and paste it into Personal access token (plus Username for Bitbucket).
4. Connect. The token is checked against the host before it is saved.

An account’s page shows its name, @username · host, Open <Host> and Remove…. Removing says: It is removed from every Catzoid app on this computer, and its token from the KeychainWindows’ protected storage (DPAPI). Repositories stay; revoke the token on the host too…. Connecting the same account again keeps its id, so nothing that refers to it breaks.

SSH keys

This computer → SSH keys lists the public keys in ~/.ssh%USERPROFILE%\.ssh (*.pub), each with its type, comment, path and fingerprint, and:

• Copy public key;
• Add to account — uploads it to GitHub, GitLab, Gitea or Bitbucket, titled DialCatz <date>.

New key → Generate makes an ed25519 key without a passphrase (an email can go in as its comment). It is saved as ~/.ssh/id_ed25519%USERPROFILE%\.ssh\id_ed25519 when that name is free — ssh uses it without any setup — else as id_ed25519_dialcatz in the same folder; for that one, add an IdentityFile line for it to ~/.ssh/config (IdentityFile ~/.ssh/id_ed25519_dialcatz)%USERPROFILE%\.ssh\config.

In the Git section, SSH accepts a host’s key the first time it sees it (StrictHostKeyChecking=accept-new) and never stops to ask.

Git and DevCatz

One set of Git accounts for DevCatz and DialCatz

DevCatz and DialCatz use the same Git hosting accounts. Connect GitHub (or GitLab, Gitea, Bitbucket) once, in either app, and the other has it too. Remove it in one, and it is gone from both — along with its token.

Where they are kept:

• The account list — id, kind, server, user name, display name, avatar and when it was added, but no token — is in ~/Library/Application Support/Catzoid/shared.json%APPDATA%\Catzoid\shared.json, under git.accounts.
• Each token is in the macOS Keychain as a generic password: service Catzoid Git, account = the account’s id.Each token is encrypted with Windows’ protected storage (DPAPI) for your Windows account, one file per account in %APPDATA%\Catzoid\git\ (<account id>.dpapi).

Both apps watch this store live, so a change in one shows up in the other straight away, without a restart. That is also why removing an account warns that it is removed from every Catzoid app on this computer. More on what the apps share is in Shared by the Catzoid apps.

The same Git section in both apps

DialCatz’s Git section is a port of DevCatz’s, kept in step by hand: the same views, the same confirmations, the same behaviour. And because a DevCatz site’s workspace lives in <site>/dialcatz, the repository DevCatz shows for a site and the one DialCatz commits to are one and the same.

What DialCatz Git does not do

• It does not write commit messages for you — there is no AI in the Git views.
• Folder workspaces are for personal workspaces; team workspaces sync through a DialCatz Den instead.
• It relies on the git installed on your computer; it does not bring its own.

Last updated 2026-11-03