Git integration

Writerside has built-in integration with Git – 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.

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 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

When you clone an existing Git repository with a Writerside project or create a Git repository 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.

Manually set path to Git executable

Press Ctrl+Alt+S to open the Writerside settings and select Version Control | Git.
If it was not auto-detected, set the Path to Git executable and click Test to make sure it works.

Clone Git repository

From the main menu, select Git | Clone.
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.
Click Clone.

Initialize Git repository

From the main menu, select VCS | Enable Version Control Integration.
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

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

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.

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.

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

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.

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, the remote is already set up. If you initialized a repository in your documentation project, 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, 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.

Push changes to a remote repository

From the main menu, select Git | Push or press ⌘ ⇧ K to open the Push Commits dialog.
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.
Click Push.

Define a remote

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

Create an empty repository on a Git hosting service, such as GitHub, GitLab, or Bitbucket. Copy the URL of the remote repository.
Open the Push Commits dialog. See Push changes to a remote repository.
Click the Define remote link.
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.

Pull changes from a remote repository

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

From the main menu, select Git | Update Project or press ⌘ T.
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.

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.

Create new branch

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.
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:

If you want others to work on your branch, or if you want to build from this branch externally, you will need to 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.

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

Merge branch into main

Checkout the main branch. Select it in the Branches popup and click Checkout.
From the main menu, select Git | Merge.
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.

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.

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.

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.

Cherry-pick commits

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

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

Last modified: 05 June 2024