Use Git
The desktop app’s Git tab commits the spec from the editor, with the system git, and tells
you for each changed file whether Git sees an API change or only formatting. It works on a folder
opened in the desktop app; the web editor and VS Code have no Git tab, and in VS Code the Source
Control view does the job.
The branch
The top of the tab names the branch in a menu that switches to another one, or (detached). Type a name in New branch and press Create branch to branch from the current commit; Refresh reads the repository again.
The changed files
Each file Git sees as changed has a row with its kind of change (new, modified, deleted, renamed or conflict) and a checkbox that includes it in the next commit. Since 0.13.0, a modified or renamed YAML or JSON file also has a tag that says what the change is, from the same comparison the Changes tab makes:
| Tag | Meaning |
|---|---|
| formatting only | The text differs, the parsed document does not: indentation, quotes, blank lines. |
| key order only | The same keys and values, in another order. |
| no API change | The parsed document differs, but the comparison finds no change to the API. |
| 1 API change, documentation only | Changes to descriptions, summaries or examples. |
| 3 API changes, breaking | API changes, with the worst severity among them. |
| content changed | A YAML or JSON file that is not a spec the editor compares. |
A click on a file’s name shows its diff under the list. Since 0.13.0, Undo formatting and order on a file puts back the committed key order and formatting wherever the content is the same, so that the diff holds your edits only, and Undo on a formatting only or key order only file puts back the committed text. In an open file the undo is an edit you can undo, and the file is saved.
Commit
Git sees the files on disk, so the tab asks you to save the editor’s changes first, and names the unsaved files. Tick the files to include, write the message in Commit message, and press Commit N files. The status bar confirms the commit. Pushing, pulling and merging stay with your Git client or the command line.
Next
Import, export and bundle brings older documents in and the finished spec out.