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.
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 IDE settings and select.
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.
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.
Initialize Git repository
From the main menu, select.
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.
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.
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 to view the log of commits for a particular file.
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 Push Commits dialog.or press ⌘ ⇧ K to open the
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.
Define a remote
This is necessary if you created a new documentation project locally, and then initialized a local Git repository in it.
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, selectfrom 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, selector 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.
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
mainbranch. Select it in the Branches popup and click Checkout.
From the main menu, select.
In the Merge into main dialog, select
new_branchand click Merge.
As a result, all commits from
new_branch will be applied to
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
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
If you document something that applies to both versions in the
v2 branch, you can cherry-pick just the commit with these changes into
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.