The Branching feature is a versioning tool that enables you to create a parallel set of content so you can edit the branched content without affecting the original content and push changes from one branch to another.
The Branching feature enables you to maintain and edit multiple versions of your content. When a map is branched, full copies of each component are created in the new branch, along with its link dependencies. This allows you to edit the branched map without affecting the ‘original’ map. Then when you’re ready, you can merge or replace changes from one branch into another.
To branch your content, use the Branching Tab in the Resource Viewer. You can use this interface to branch a map, or to merge or replace content from one branch to another. Just select a Source Branch to merge or replace content in the Target Branch with.
Each time you merge or replace branches, a historical event is added to the map’s history. You can view a map’s history in the History Tab.
Your default branch is named “master”. You can switch to another branch using the
. You can also search in the branch list.
When should I branch my content?
Branching is useful when you need to maintain and edit multiple versions of your documentation. For example, you have an upcoming software release. For this release, you need to maintain two versions of the content: the current content because it’s still being used by users and an new version that’s being edited for the upcoming release.
You can use the Branching feature to branch the original content into a new branch. This new branch contains copies of all the content from the original branch. You can make changes to this branched map without affecting the original map. Then when the new software version is released, you can either merge the content from the branched map to the ‘original’ branch or continue maintaining two separate branches for each version of the content.
If your goal is to track milestone versions, we recommend using our Releases feature instead. For more information, see Releases Overview
Branching a map
When you branch a map, full copies of each component are created in the new branch, along with its link dependencies. In the example below, when you branch Map ABC, that map and all of its dependencies (topics, images, and reused content) are copied into a new branch.
If any of the topics in Map ABC are linked to topics that aren’t directly referenced in the map (for example, Reference1), those topics would also be included, even though they are not direct dependencies of the map.
Branching a map
Merging between branches
As you continue to modify a branch, you may realize you need to merge changes from one branch to another. When merging between branches, you’ll be asked to Approve or Reject any differences in the topics you’re merging. For example:
You can also push completely new topics to the branch.
Branching into an existing branch
easyDITA’s branching feature uses a selective branching system. So when you branch into another branch, if a component is already present in the target branch, it will not be overwritten. The component will be unchanged and any other components linking to it will be relinked to the pre-existing component. Let’s look at an example.
Below we have two branches: BranchA and BranchZ. You can make three observations about these branches:
BranchA contains two topics: Concept1 and Task2.
In BranchA, there is a link between Concept1 and Task2.
BranchA and BranchZ both contain the Task2 topic
This is what happens when you branch BranchA into BranchB:
Branching BranchA to BranchZ
When you branch BranchA (Source Branch) into BranchZ (Target Branch), the following occurs:
A copy of Concept1 is created in BranchZ.
The existing Task2 in BranchZ is not overwritten with the Task2 topic from BranchA.
The link in Concept1 to Task2 is relinked to the existing Task2 in BranchZ.