# Git integration

Writerside has built-in integration with [Git](https://git-scm.com/) – a distributed version control system that tracks changes in your documentation sources.

This article explains some basic concepts about Git and how they can be used in Writerside for documentation authoring. For a full description of how Git integrates in JetBrains IDEs, see [Git for IntelliJ IDEA](https://www.jetbrains.com/help/idea/using-git-integration.html).

Why you should consider using Git for your documentation sources:

* Robust change tracking ensures that you have a complete history of changes. If you provide informative commit messages, then you will also be able to understand why a certain change has been made.

* Collaboration is important if you have several authors working on the same documentation sources. With Git, everyone works in their own copies (clones) of the repository, and submits changes (commit and push) only when the changes are ready. And if two people happen to change the same piece of content, the latest changes will not simply overwrite earlier changes: you will be able to resolve conflicts and ensure that all changes are taken into account.

* Versioning your documentation ensures that users of every version get the most relevant information. While you can set up separate [instances](instances.html) for each version, it is generally more convenient to branch off the versions from a common root. Every branch in Git is a copy of your project that contains only the differences specific to one particular version.

* Combined with a Git hosting service, such as GitHub or GitLab, you can automate the builds, testing, and deployment of your documentation similar to common and robust practices in software development.

## Configure Git

> **TL;DR**
> `Settings | Version Control | Git`

When you [clone an existing Git repository](#clone_repo) with a Writerside project or [create a Git repository](#init_repo) in your current documentation project, Writerside detects whether Git is installed on your computer. If Writerside does not locate the Git executable, it suggests downloading and installing Git.

Procedure: Manually set path to Git executable

1. Press `Ctrl+Alt+S` (Windows), `⌘ Comma` (macOS), `⌘ Comma` (IntelliJ IDEA Classic (macOS)), `⌘ Comma` (macOS System Shortcuts), `Ctrl+Alt+S` (XWin), `Ctrl+Alt+S` (GNOME), `Ctrl+Alt+S` (KDE), `Ctrl+Alt+S` (Emacs), `Ctrl+Alt+S` (Sublime Text), `⌘ Comma` (Sublime Text (macOS)), `Ctrl+Alt+S` (NetBeans), `Ctrl+Alt+S` (Visual Studio), `⌘ Comma` (Visual Studio (macOS)), `Ctrl+Alt+S` (Eclipse), `⌘ Comma` (Eclipse (macOS)) to open the IDE settings and select `Version Control | Git`.

2. If it was not auto-detected, set the Path to Git executable and click Test to make sure it works.

Procedure: Clone Git repository

1. From the main menu, select `Git | Clone`.

2. In the Get from Version Control dialog, specify the URL of the Git repository you want to clone or select one of the VCS hosting services on the left.

If you are already logged in to the selected hosting service, completion will suggest the list of available repositories that you can clone.

3. Click Clone.

Procedure: Initialize Git repository

1. From the main menu, select `VCS | Enable Version Control Integration`.

2. Choose Git as the version control system and click OK.

The project will be associated with a single Git repository, so there is no need to add each file to Git individually.

## Track changes

> **TL;DR**
> Press `Alt+0` (Windows), `⌘ 0` (macOS), `⌘ 0` (IntelliJ IDEA Classic (macOS)), `⌘ 0` (macOS System Shortcuts), `Alt+0` (XWin), `Alt+0` (GNOME), `Alt+0` (KDE), `Alt+0` (Emacs), `Alt+0` (Sublime Text), `⌘ 0` (Sublime Text (macOS)), `Alt+0` (NetBeans), `Alt+0` (Visual Studio), `Alt+0` (Visual Studio (macOS)), `Alt+0` (Eclipse), `⌘ 0` (Eclipse (macOS)) to open the  Commit tool window
>
>
>
> Press `Alt+9` (Windows), `⌘ 9` (macOS), `⌘ 9` (IntelliJ IDEA Classic (macOS)), `⌘ 9` (macOS System Shortcuts), `Alt+9` (XWin), `Alt+9` (GNOME), `Alt+9` (KDE), `Alt+9` (Emacs), `Alt+9` (Sublime Text), `⌘ 9` (Sublime Text (macOS)), `Alt+9` (NetBeans), `Alt+9` (Visual Studio), `⌘ 9` (Visual Studio (macOS)), `Alt+9` (Eclipse), `⌘ 9` (Eclipse (macOS)) to open the  Git tool window

When you make changes, they are reflected in the  Commit tool window.

![The Commit tool window](https://resources.jetbrains.com/help/img/writerside/commit_tool_window.png)

In the previous example, the following changes happened compared to the current version of the Git repository:

* Three files received some changes: `lib.topic`, `lib.tree`, and `wrs.tree`.

* One file was removed: `icon_remove.png`.

* Two new files are tracked by Git: `Git-integration.topic` and `New-Topic.topic`.

* Three new files are not tracked: `commit_tool_window.png`, `commit_tool_window_dark.png`, and `Untracked-new-topic.topic`.

> **Note:**
> When you add a file, for example, [create a new topic](add-a-topic.html), Writerside will usually detect this and suggest adding it to Git. If you refuse or add the file without using Writerside, it will be listed under Unversioned Files. Drag and drop them to the relevant changelist or right-click and select Add to VCS from the context menu.

Procedure: Commit changes

The changes you see in the  Commit tool window are not saved in Git history yet. They reflect the state of your current local files compared to the last known state. This state in Git is known as the latest commit.

When you are happy with the changes and want to record them in the history, commit them to Git.

* Select the changes in the  Commit tool window, write a commit message and click Commit.

![Commit changes from the Commit tool window](https://resources.jetbrains.com/help/img/writerside/commit_tool_window_commit.png)

The Git repository history is made up of such commits, which reflect the state of the repository at a particular point.

```MERMAID
%%{init: { 'gitGraph': {'showBranches': false} } }%%
gitGraph
    commit id: "Add Introduction topic"
    commit id: "Document settings"
    commit id: "Create reference of dialogs"
    commit id: "Add Git integration topic"
```

You can use the Git tool window to view the history of commits under the Log tab. This view shows the commit message, date of commit, and a diff of changes. You can also right-click anywhere in any topic file and select `Git | Show History` to view the log of commits for a particular file.

![Git tool window: Log tab](https://resources.jetbrains.com/help/img/writerside/git_tool_window_log.png)

## Collaborate

Working with a Git repository locally can be enough if you are the only author and do not need to set up any automation. However, in most cases, you want to host your Git repository externally to provide access to the documentation sources for others and for automation scripts. This is called a remote repository, most commonly referred to as the origin, because it is the actual source of truth and everyone else works with its copies.

If you [cloned an existing repository](#clone_repo), the remote is already set up. If you [initialized a repository in your documentation project](#init_repo), you will need to define a remote. In any case, you work with a local copy of the remote Git repository, and it is important that you properly sync your local clone with the origin.

For example, if you cloned a remote Git repository and then [committed some changes](#commit-changes), this commit will exist only in the local clone of the Git repository. If you want these changes on the remote, push your local commits to the remote.

Procedure: Push changes to a remote repository

1. From the main menu, select `Git | Push` or press `⌘ ⇧ K` (Windows), `⌘ ⇧ K` (macOS), `⌘ ⇧ K` (IntelliJ IDEA Classic (macOS)), `⌘ ⇧ K` (macOS System Shortcuts), `Ctrl+Shift+K` (XWin), `Ctrl+Shift+K` (GNOME), `Ctrl+Shift+K` (KDE), `Ctrl+Shift+K` (Emacs), `⌘ ⇧ K` (Sublime Text), `⌘ ⇧ K` (Sublime Text (macOS)), `Ctrl+Shift+K` (NetBeans), `Ctrl+Shift+K` (Visual Studio), `⌘ ⇧ K` (Visual Studio (macOS)), `Ctrl+Shift+K` (Eclipse), `⌘ ⇧ K` (Eclipse (macOS)) to open the Push Commits dialog.

![Push Commits dialog](https://resources.jetbrains.com/help/img/writerside/push_commits_dialog.png)

This dialog shows the local branch from which you are pushing, the branch on the remote to which you are pushing, and lists the commits that will be pushed.

2. Click Push.

> **Note:**
> If there are no remotes defined, see [Define a remote](#define_a_remote).

Procedure: Define a remote

This is necessary if you created a new documentation project locally, and then initialized a local Git repository in it.

1. Create an empty repository on a Git hosting service, such as [GitHub](https://github.com/), [GitLab](https://gitlab.com/), or [Bitbucket](https://bitbucket.org/). Copy the URL of the remote repository.

2. Open the Push Commits dialog. See [Push changes to a remote repository](#push).

3. Click the Define remote link.

4. Specify a name for the remote (such as `origin`) and the URL where it is hosted.

Now your changes will be pushed to the defined remote. To see which remotes are defined for the current Git repository, select `Git | Manage Remotes` from the main menu.

After you push, the commits will be available on the remote. Anyone who clones the repository or pulls the latest changes will have these commits in their local clone.

Procedure: Pull changes from a remote repository

To make sure you are working with the latest state of the Git repository, update the project.

1. From the main menu, select `Git | Update Project` or press `⌘ T` (Windows), `⌘ T` (macOS), `⌘ T` (IntelliJ IDEA Classic (macOS)), `⌘ T` (macOS System Shortcuts), `Ctrl+T` (XWin), `Ctrl+T` (GNOME), `Ctrl+T` (KDE), `Ctrl+T` (Emacs), `⌘ T` (Sublime Text), `⌘ T` (Sublime Text (macOS)), `Ctrl+T` (NetBeans), `Ctrl+Alt+W` (Visual Studio), `⌘ ⌥ W` (Visual Studio (macOS)), `⌘ T` (Eclipse), `⌘ T` (Eclipse (macOS)).

2. Select the update strategy:

* Merge preserves the history of your repository by creating a merge commit.

* Rebase creates a linear history without any additional commits.

There are advantages and disadvantages for each strategy, but the result is the same: your local clone of the Git repository will be in sync with the remote. For more information, see [Sync with remote](https://www.jetbrains.com/help/idea/sync-with-a-remote-repository.html).

## Branches

In Git, branches are a way to diverge the content in your repository. For example, you can temporarily work on some new content in isolation and then merge it back into the main branch once it is ready. Or you can use branches to maintain several versions of your documentation. You can also combine both approaches.

In Writerside, you can work with branches in the Branches popup, the VCS widget in the main toolbar, or the Log tab of the Git tool window.

Procedure: Create new branch

1. From the main menu, select Git | New Branch. This will create a new branch from the currently selected branch. That is, the new branch will have exactly the same history at the point of creation.

2. Specify the name of the new branch and select Checkout branch to switch to it immediately.

For example, you were working in the default `main` branch, created a new branch `new_branch`, and committed some changes with new content. The history in your local repository will now look like this:

```MERMAID
gitGraph
commit id: "Add Introduction topic"
commit id: "Document settings"
commit id: "Create reference of dialogs"
commit id: "Add Git integration topic"
branch new_branch
commit id: "Add some new content"
```

If you want others to work on your branch, or if you want to build from this branch externally, you will need to [push](#push) the new branch to the remote. Otherwise, you can continue working on it locally.

In the meantime, others (or maybe you) can safely push new commits to the main branch, and this will not affect your branch with new content.

```MERMAID
gitGraph
commit id: "Add Introduction topic"
commit id: "Document settings"
commit id: "Create reference of dialogs"
commit id: "Add Git integration topic"
branch new_branch
commit id: "Add some new content"
checkout main
commit id: "Fix typo"
```

When the changes in your new branch are ready, merge it back into main.

Procedure: Merge branch into main

1. Checkout the `main` branch. Select it in the Branches popup and click Checkout.

2. From the main menu, select `Git | Merge`.

3. In the Merge into main dialog, select `new_branch` and click Merge.

As a result, all commits from `new_branch` will be applied to `main`.

```MERMAID
gitGraph
commit id: "Add Introduction topic"
commit id: "Document settings"
commit id: "Create reference of dialogs"
commit id: "Add Git integration topic"
branch new_branch
commit id: "Add some new content"
checkout main
commit id: "Fix typo"
merge new_branch
```

### Version branches

You can also use branches to maintain content for several versions of your application. For example, the `main` branch can be used for v1, and you can create a separate branch for v2.

```MERMAID
gitGraph
commit id: "Add Introduction topic"
commit id: "Document settings"
commit id: "Create reference of dialogs"
commit id: "Add Git integration topic"
branch v2
commit id: "New in v2"
```

You never merge `v2` into `main`, because features introduced in v2 are not available for v1. However, if you are sure that new features you document for v1 are also applicable to v2, you can regularly merge `main` into `v2`.

```MERMAID
gitGraph
commit id: "Add Introduction topic"
commit id: "Document settings"
commit id: "Create reference of dialogs"
commit id: "Add Git integration topic"
branch v2
commit id: "New in v2"
checkout main
commit id: "New feature"
checkout v2
merge main
```

If you document something that applies to both versions in the `v2` branch, you can cherry-pick just the commit with these changes into `main`.

Procedure: Cherry-pick commits

1. Checkout `main`.

2. Find the commit in the Log tab of the Git tool window. Right-click the commit and select Cherry-Pick.

```MERMAID
gitGraph
commit id: "Add Introduction topic"
commit id: "Document settings"
commit id: "Create reference of dialogs"
commit id: "Add Git integration topic"
branch v2
commit id: "New in v2"
checkout main
commit id: "New feature"
checkout v2
merge main
commit id: "Something for v2 and v1"
checkout main
cherry-pick id: "Something for v2 and v1"
```

Whatever you do in branches, changes are initially staged in your local repository clone. Remember to [push regularly](#push) if you want the changes to be available on the remote. And remember to [update the project](#pull) so that your local clone stays in sync with the remote. This will ensure smooth collaboration.