# History, blame and restoring ## What you'll do You find out what changed in a mapping, who changed it and when, compare an old version with the current one, and bring an older version back if a change was a mistake. You also name your changes with a checkpoint before they are pushed. ```{figure} ../images/ship/history-dock.png :class: screenshot :alt: The Workspace with the History tab of the dock open under the three panes — the recorded changes of the blood pressure model and the diff of the newest one The **History** tab of the Workspace dock, opened from the versioning badge. ``` ## Before you start - Versioning must be available: see {ref}`versioning-availability`. The history is recorded even before a Git repository is connected; restoring from a release or commit needs one. - Restoring changes the engine, so it needs write access to the mappings as well as `versioning.w`. ## Steps ### See the history of what you are editing 1. Open a model in the Workspace. 2. Click the versioning badge in the top bar [1]{.callout} (it reads, for example, **2 unpushed**), or the **History** tab of the dock [2]{.callout} when the dock is open. 3. The left side lists the recorded changes of the open model, newest first [3]{.callout}. With no model open, it lists all changes (*All changes*). Each row shows: - a dot: grey when the change is pushed, orange when it isn't, blue while it is in an open review (hover the dot for the commit or review); - the checkpoint message, or what happened (*Updated model …*, *Created context …*); - who, when (hover for the exact time) and where the change came from: *Workspace*, *State* (the Engine state page), *Import* (an upload), and others; - a chip *in review*, *approved*, *changes requested* or *review closed* when the change is part of a review (see {doc}`reviews`). 4. Click a change. The right side shows the diff. - **This change** (default): the version before this change on the left, this change on the right. The first recorded version of a file is compared with *Before (did not exist)*. - **Compared with now** [4]{.callout}: this change on the left, the engine's current text (*Now (engine)*) on the right. Unchanged stretches are folded (*101 unchanged lines*); added lines are green, removed ones red. **Load older** at the bottom of the list fetches the next 50 changes; the round arrow reloads. The same history is on the **History** tab of the Versioning page (all changes of the tenant), and on the Engine state page: select a template and click **History** for the changes of its OPT, its context and each of its models, one tab each. ```{figure} ../images/ship/history-page.png :class: screenshot :alt: The History tab of the Versioning page with numbered callouts The **History** tab of the Versioning page. ``` | | | |---|---| | [1]{.callout} | The versioning badge; here it opens the **Remote** tab. | | [2]{.callout} | **Git remote settings**. | | [3]{.callout} | The **History** tab. | | [4]{.callout} | A change not pushed yet (orange dot) with its checkpoint message. | | [5]{.callout} | A pushed change (grey dot). | | [6]{.callout} | **Checkpoint…**: name the unpushed changes. With the review workflow, **Submit for review…** sits next to it. | | [7]{.callout} | **This change** / **Compared with now**. | | [8]{.callout} | **Restore this version…** (not offered on a change that deleted the file). | ```{figure} ../images/ship/history-compared-with-now.png :class: screenshot :alt: The diff of the change "Map the measurement position" compared with the engine now — the later location and performer mappings appear as added **Compared with now**: everything changed since sam.lee mapped the measurement position. ``` ```{figure} ../images/ship/template-history.png :class: screenshot :alt: The dialog "History · Blood Pressure" with tabs Template (OPT), Context and one tab per model **History** of a template on the Engine state page. ``` ### See who changed a mapping 1. In the Workspace, select a mapping. Under its name the inspector shows who changed it last [1]{.callout}: - *Last changed by alex.morgan · 17 hours ago · Map the cuff location*: the person, when, and the checkpoint message if there was one. Hover it for the exact time, where the change came from, how many changes by whom, and when the mapping was first recorded. - *Unsaved changes · before that …*: you edited the mapping and the edit isn't recorded yet. - *New — not recorded yet*: the mapping didn't exist in the recorded version. 2. Click the line. The **History** footer tab [2]{.callout} opens with the number of changes, their authors and when the mapping was first recorded, and one row per change behind the mapping's lines [3]{.callout}. 3. Click a row to open that change in the **History** tab of the dock, scrolled to the mapping. On the Engine state page, where there is no dock, the row opens the Versioning page instead. ```{figure} ../images/ship/blame-line.png :class: screenshot :alt: The inspector of the mapping "location" with the line "Last changed by alex.morgan · 17 hours ago · Map the cuff location" and the History footer tab open The blame line and the **History** footer tab of a mapping. ``` To see it for every mapping at once, click the clock button in the outline toolbar [1]{.callout} (*Show who changed each mapping last*). Each row then shows who changed it and when [2]{.callout}. Without the column, hovering a row shows the same in its tooltip. ```{figure} ../images/ship/blame-column.png :class: screenshot :alt: The mapping outline with a column of authors and times — alex.morgan for most rows, sam.lee for position and confoundingFactors The outline with the blame column on. ``` ### Restore an older version of one file 1. In a history (the dock, the Versioning page or a template's **History**), click the change you want to go back to. 2. Click **Restore this version…**. 3. Atlas works out what restoring would do and shows the plan [1]{.callout}: one row per file with its action (*create*, *update*, *delete*). Click **Diff** [2]{.callout} on a row to compare *Now (engine)* with *This version*. 4. Click **Restore** [3]{.callout}. The dialog says *Restored.* with what changed. ```{figure} ../images/ship/restore-dialog.png :class: screenshot :alt: The dialog "Restore this version" with a plan of one update and the diff of the model Restoring the blood pressure model to sam.lee's version: the later mappings go away. ``` Restoring is itself a recorded change (its source is *restore*), so you can undo it the same way. ### Restore a template from a release, commit or branch 1. On the Engine state page, select the template, open **⋯** and choose **Restore from revision…**. On the Versioning page, **Restore engine to this…** on a release opens the same dialog for that release (limited to its template for a template release), and **Restore…** on a commit of the **Remote** tab opens it for that commit, for all templates. 2. Pick where to restore from [1]{.callout}: **Release**, **Commit** or **Branch or ref**, then the release, commit or ref [2]{.callout}. 3. Choose how [3]{.callout}: - **Merge — update and add, keep what's only in the engine**; - **Mirror — also delete what the ref doesn't have**. From the template's menu the dialog adds *Only template … is restored.* 4. The plan appears by itself. **Show N unchanged** [4]{.callout} lists the files that stay as they are. Click **Restore**. ```{figure} ../images/ship/restore-from-release.png :class: screenshot :alt: The dialog "Restore from the remote" with the Release tab, the release blood_pressure/v1.0.0 picked, Merge selected and a plan of 1 to update and 3 unchanged Restoring the Blood Pressure template as it was in release `blood_pressure/v1.0.0`. ``` ### Name your changes with a checkpoint Every save is recorded without a message. A checkpoint gives the changes since the last checkpoint a name, which becomes the message of their commit. 1. Click **Checkpoint…** in a history or on the **Remote** tab. 2. Type the message. 3. With the direct workflow, tick **Push to main now** to push right away. With the review workflow the commit reaches the branch in the review you submit it in. 4. Click **Checkpoint** (or **Checkpoint and push**). ```{figure} ../images/ship/checkpoint-dialog.png :class: screenshot :alt: The Checkpoint dialog with a message and "Push to main now" ticked A checkpoint that also pushes. ``` ## Check it worked - After a restore, the history has a new change on top, and the Workspace shows the restored text. - After a checkpoint with **Push to main now**, the **Remote** tab lists a new commit named by your message. ## Tips :::{tip} The badge and the History tab only appear when the engine versions mappings. Without them, look at {ref}`versioning-availability`. ::: :::{tip} The blame column is remembered in this browser. See {doc}`/reference/remembers`. ::: :::{tip} **Compared with now** answers "what has happened since?" faster than stepping through every change. ::: ## Watch out :::{warning} Restoring reloads the open model from the engine. If it has unsaved edits, the dialog warns: *The open model has unsaved edits. Restoring reloads it from the engine and discards them.* Save first if you want to keep them. ::: :::{warning} **Mirror** deletes from the engine whatever the release, commit or branch doesn't have, within the scope of the restore. Use **Merge** unless you want exactly the old state. ::: :::{warning} The plan is applied only as you saw it. If someone changes the mappings in between, Atlas shows *The engine changed since the preview. This is the new plan — review it before restoring.* Read it and click **Restore** again. ::: ## If something goes wrong | Message | What to do | |---|---| | *No recorded changes yet.* | Nothing was saved since versioning was turned on. | | *Could not load the history* / *Could not load the diff* | Reload with the round arrow; if it persists, see {doc}`/reference/messages`. | | *Nothing to restore: the engine already matches this version.* | The engine already holds that text; **Restore** stays disabled. | | *There are no changes since the last checkpoint.* | Everything is already named. Tick **Push to main now** to push anyway. | | *Another versioning operation is running. Try again in a moment.* | Someone else is pushing, pulling or restoring. Wait and try again. | When the engine explains an error itself, Atlas shows its explanation instead of these words. ## Related - {doc}`push-pull`: getting the changes onto the remote. - {doc}`compare`: comparing whole versions of a template. - {doc}`/map/edit-in-workspace`: saving, auto-save and the dock. - {doc}`/reference/screens/versioning`: the Versioning page, control by control.