# Push, pull and conflicts ## What you'll do You push the recorded changes to the Git repository, bring in changes teammates made on the repository directly, and decide which side wins when both changed the same file. ```{figure} ../images/ship/remote-tab.png :class: screenshot :alt: The Remote tab — the repository URL, "2 changes not pushed yet. main has 1 commit the engine hasn't pulled yet.", the buttons Pull, Checkpoint and Push, and the commits on main The **Remote** tab: two changes to push, one commit to pull. ``` ## Before you start - A Git repository is connected: see {doc}`git-remote`. - Pushing and pulling need the `versioning.w` scope; a pull that changes mappings also needs write access to them. - With the review workflow there is no **Push**: changes reach the branch through {doc}`reviews`. Pulling works in both workflows. ## Steps ### Read the Remote tab Open **Versioning** and click the **Remote** tab. | | | |---|---| | [1]{.callout} | The repository, the branch, the workflow (*direct push* or *review workflow*) and when the engine last pushed, with the commit. *Checking the remote…* shows while the engine asks the repository. | | [2]{.callout} | *N changes not pushed yet.* or *Everything is pushed.* | | [3]{.callout} | Why the remote differs, if it does: *main has 1 commit the engine hasn't pulled yet.*, *main no longer contains the engine's last push: its history was rewritten (e.g. force-pushed).*, or *The engine hasn't pushed to or pulled from main yet, so it can't tell whether they match.* | | [4]{.callout} | **Pull…**, outlined in orange when there is something to pull. | | [5]{.callout} | **Checkpoint…**: name the changes before pushing (see {doc}`history`). | | [6]{.callout} | **Push**, disabled while everything is pushed. With the review workflow, **Submit for review…** takes its place. | | [7]{.callout} | **Restore…** on a commit: bring the whole engine back to that commit (see {doc}`history`). | Below, **Commits on main** lists the commits of the branch, newest first, with a chip for the kind of commit (*checkpoint*, *snapshot*, *restore*, *release*; ordinary pushes have none), the author and when. ### Push 1. Click **Push**. 2. The engine turns the unpushed changes into commits: changes of the same person close together in time become one commit (see *Group edits within* in {doc}`git-remote`), and a checkpoint closes a commit with its message. 3. *Pushed N commits (sha).* confirms it, and the commits appear in the list. A push never changes the mappings in the engine; only a pull does. So **Push** asks you to pull first when the branch has changes the engine hasn't taken: - someone changed mapping files on the branch that you didn't change (*main has commits the engine hasn't pulled yet.*). Other files, such as a README, don't count; - the engine has never pushed to or pulled from the branch, or the branch's history was rewritten. The Remote tab says why, adds *Pull first, then push.*, and offers **Pull…**, which opens the pull dialog. Pull, then push again. Files changed on both sides are conflicts instead (see [conflicts](#push-pull-conflicts)). On a branch the engine never synced with (never connected, or the repository or branch setting changed), the Remote tab offers **Git remote settings** before **Pull…**: connecting is usually right there, because a pull plans to delete every engine artefact the repository lacks. When the branch has no commits at all (it was never connected, or it was deleted), **Push** asks you to connect instead: *main has no commits (never connected, or deleted).* with a link to the **Git remote settings**, where **Connect** writes the engine's state to the branch (see {doc}`git-remote`). Then push again. Automatic pushes stop in both cases until someone pulls or connects; the Remote tab shows the engine's reason in red meanwhile. ### Pull 1. Click **Pull…**. Atlas asks the remote what pulling would change; nothing changes yet. 2. The dialog says which commit it pulls and what the engine's last push or pull was, lists the incoming commits (up to ten) [1]{.callout}, and shows the plan [2]{.callout}: one row per file with its action. Click **Diff** on a row to compare *Now (engine)* with the branch. 3. Click **Pull** [3]{.callout}. *Pulled \.* confirms it with what changed. ```{figure} ../images/ship/pull-dialog.png :class: screenshot :alt: The dialog "Pull from the remote" with one incoming commit "Round body weight to one decimal", a plan updating the body weight model and its diff Pulling a teammate's commit to the body weight model. ``` If nothing came in, the dialog says *Already up to date: main has nothing the engine hasn't pushed or pulled.* (push-pull-conflicts)= ### When both sides changed the same file **While pushing**, the Remote tab lists the files and offers two buttons: ```{figure} ../images/ship/push-conflict.png :class: screenshot :alt: The message "The remote changed 1 file the engine also changed — models/OBSERVATION.blood_pressure.v2.yml" with the buttons "Keep the engine's version (overwrite the remote)" and "Take the remote's version (update the engine)" A push that conflicts with the remote. ``` - **Keep the engine's version (overwrite the remote)** [1]{.callout}: push anyway; the engine's text replaces the remote's for these files. - **Take the remote's version (update the engine)** [2]{.callout}: after you confirm (*Replace the engine's version of the conflicting files with the remote's?*), the remote's text replaces the engine's, and your unpushed edits to these files are gone. **While pulling**, the dialog lists the files the remote changed that the engine also changed (not pushed yet, or in an open review) and asks which to keep: ```{figure} ../images/ship/pull-conflicts.png :class: screenshot :alt: The pull dialog with a conflict on the blood pressure model and the choices "Keep the engine's version (the next push overwrites the remote)" and "Take the remote's version (discards the engine's changes)" A pull touching unpushed changes. Keeping the engine's version is selected by default. ``` - **Keep the engine's version (the next push overwrites the remote)** [1]{.callout}, selected by default because nothing is lost; - **Take the remote's version (discards the engine's changes)** [2]{.callout}. The plan updates when you switch. With *Keep* and nothing else to import, the footer explains [3]{.callout}: *Nothing to import: the engine keeps its versions. Pulling records the remote as pulled.* Pulling then still counts: the next push builds on the remote's commits. ## Check it worked - After a push, the badge reads **Up to date** (unless the remote has commits to pull) and the Remote tab says *Everything is pushed.* Changes the push took from the remote are in the Workspace. - After a pull, the orange remark next to the unpushed count is gone, and the pulled changes are in the Workspace. ## Tips :::{tip} Push often, or turn on automatic pushing in {doc}`git-remote`. The fewer unpushed changes, the fewer conflicts. ::: :::{tip} Pull before a bigger piece of work when the badge or the Remote tab says the remote has commits. ::: ## Watch out :::{warning} Pulling reloads the open model from the engine. When the model open in the Workspace has unsaved edits and the pull changes something, the dialog warns: *The open model has unsaved edits. Pulling reloads it from the engine and discards them.* Save first. ::: :::{warning} **Take the remote's version** throws your unpushed edits to those files away. It can't be undone from the remote, but the engine's history still has your version: restore it from the **History** tab (see {doc}`history`). ::: :::{warning} A pull applies exactly the plan you saw. If the engine or the remote changed while you read it, Atlas shows *The engine or the remote changed since the preview. This is the new plan — review it before pulling.* Read it and click **Pull** again. ::: ## If something goes wrong | Message | What to do | |---|---| | A red box on the Remote tab, and the badge says **Versioning error** | The last push failed (also an automatic one). The box shows the reason; it clears with the next successful push. | | *… Pull first, then push.* with a **Pull…** button; from a dialog, the engine's *…; pull (POST /versioning/pull) before pushing* | The branch has changes the engine hasn't taken, the engine hasn't synced with it yet, or it was rewritten. Click **Pull…** on the Remote tab, pull, then push. | | *\ has no commits (never connected, or deleted).*; from a dialog, the engine's *The remote branch \ has no commits; connect …* | Open the **Git remote settings** and click **Connect**, then push. | | *\ moved on while pushing (…)*, or *The remote kept moving while pushing. Try again.* | Someone kept pushing to the branch while the engine was pushing. The engine already retried on top of the new commits; click **Push** again. | | *This remote uses the review workflow: submit the changes for review instead of pushing.* | The workflow was switched to *Review*. Use **Submit for review…** (see {doc}`reviews`). | | *Another versioning operation is running. Try again in a moment.* | Someone else is pushing, pulling or restoring right now. | | *The git remote could not be reached.* | The repository or the token doesn't work any more; test it on the {doc}`git-remote` page. | | *Could not push*, *Could not pull*, *Could not read the remote* | See {doc}`/reference/messages`. | When the engine explains an error itself, Atlas shows its explanation instead. ## Related - {doc}`git-remote`: connection, workflow and automatic pushing. - {doc}`history`: checkpoints, and restoring an older version. - {doc}`reviews`: the review workflow. - {doc}`/reference/screens/versioning`: the Versioning page, control by control.