How Git sync works Agency plan

Agency · Git sync is part of the Agency plan (and its free trial). Plans

The files #

Each snippet is two files in the repository, inside the Folder in the repository (default snipfire/), in a directory for its Snipfire folder:

snipfire/
  disable-xml-rpc.php
  disable-xml-rpc.json
  WooCommerce/
    Checkout/
      vat-number-field.php
      vat-number-field.json
  Design/
    brand-colours.scss
    brand-colours.json
    promo-bar.html
    promo-bar.json

• The code file holds exactly the code, nothing else. Its extension follows the type: .php, .html, .css, .scss, .less or .js. The name comes from the snippet's title.
• The settings file (.json) holds the snippet's settings and its permanent ID (uid).

What's in the files #

{
    "snipfire": 1,
    "uid": "0b6c3f0e-5a1d-4c7e-9f7a-2d1e8c4b33e2",
    "title": "Disable XML-RPC",
    "description": "",
    "type": "php",
    "lang": "",
    "status": "active",
    "mode": "live",
    "run": "auto",
    "hook": "root",
    "priority": 10,
    "shortcode": "",
    "conditions": [],
    "load_as": "inline",
    "js_strategy": "",
    "consent": "",
    "tags": []
}

So the code, title, description, type, location, priority, how it runs, shortcode, conditions, loading options, testing mode, cookie consent, tags and on/off all sync. Nothing site-specific does: no numeric IDs, authors or dates. For the meaning of each field, see Storage, export format and constants.

Working in the repository #

• Edit code files freely, in any editor.
• Rename or move files, together with their settings file (same name, .json). The uid ties them to the snippet, so Snipfire follows. Moving to another directory moves the snippet to that folder on the site.
• Create a new snippet in Git by adding both files. The settings file needs "snipfire": 1 and a uid of your own: 8 to 64 letters, digits and dashes, unique (a UUID is ideal). Missing fields get their defaults.
• Other files in the repository (a README, a CI config) are ignored.

What a sync does #

Snipfire compares each side with how it looked after the last sync, using Git's own file fingerprints, so unchanged files are never downloaded. A sync with nothing to do costs one request.

All the changes of one sync go into one commit, with a message like Snipfire: 3 changes from example.com and a list of what changed. If someone pushes to the branch while a sync is running, Snipfire starts again from their commit instead of overwriting it (three attempts in all).

Conflicts #

A snippet in conflict is listed under Choose which version to keep, with what happened:

Choosing settles that snippet and syncs straight away. The version you don't keep isn't lost: it stays in the snippet's history on the site, or in Git's history.

Conflicts are never settled automatically, not even by scheduled syncs or webhooks: they wait for you. Other snippets keep syncing in the meantime.

From the command line: wp snipfire git status lists conflicts with their uids, and wp snipfire git resolve <uid> --keep=site (or --keep=git, or all instead of a uid) settles them.

Code from Git that fails on the site #

Code pulled from Git goes through the same checks as a save in the editor (syntax, "Cannot redeclare", conditions), and a snippet that's on is test-loaded. If it fails:

• the snippet is saved on the site but kept switched off there, so the site keeps running,
• the sync report says so: "…" came from Git but is switched off here: …,
• it isn't pushed back to Git as "off": Git keeps saying "on", so once you fix the code in Git, the next sync switches it on.

Syncing one folder, and several sites in one repository #

What to sync can limit syncing to one Snipfire folder, for example Shared. Its subfolders come along, and become directories inside the repository folder.

• Share snippets between sites: point several sites at the same repository, branch and folder, each syncing its Shared folder. A change on one site reaches the others at their next sync.
• Keep each site's snippets apart in one repository: give each site a different Folder in the repository, such as client-a/ and client-b/.

A snippet you move out of the synced folder on the site leaves Git (it's deleted there) but stays on the site.

Starting over #

Forget the last sync (on the Tools page, or wp snipfire git reset) makes the next sync compare the site and Git from scratch. Matching snippets are recognised; snippets that differ show up as conflicts. Nothing is deleted.