Table of Contents
User Guide
Branching
Branching Overview
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.
Creating a Branch
Use the Branching Tab in the Resource Viewer to create a parallel set of content in a new branch.
Overwriting a Branch
Use the Branching Tab in the Resource Viewer to replace all content in a branch with newer content from another branch.
Merging Some Changes Between Map Branches
Use the Branching Tab in the Resource Viewer to merge map branches and select which changes are pushed from the source branch into the target branch.
Merging All Changes Between Map Branches
Use the Branching Tab in the Resource Viewer to merge all changes from one branch into another.
Branching Overview

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.

section
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 Branch Menu. You can also search in the branch list.
section

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.
Note:If your goal is to track milestone versions, we recommend using our Releases feature instead. For more information, see Releases Overview.
section

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
section

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

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

Two branches
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.
Creating a Branch

Use the Branching Tab in the Resource Viewer to create a parallel set of content in a new branch.
  1. In the Content Manager, right-click a map and select Branch .
  2. Click New Branch .

    Expected Result
    The Create New Branch window displays.
  3. Enter a name for the new branch.Enter a New Branch Name field
  4. Click Save.

    Expected Result
    The Branch created dialog displays.
  5. Do one of the following:

    • To switch to the new branch, click OK.

      You are switched to the new branch. The new branch is selected in the Branch drop-down menu.
    • To stay in the current branch, click Cancel.

      You remain in the current branch. The current branch displays in the Branch drop-down menu.

result

A new branch is created.

Overwriting a Branch

Use the Branching Tab in the Resource Viewer to replace all content in a branch with newer content from another branch.
  1. In the Content Manager, right-click a map and select Branch .Branching Tab
  2. In the Source Branch drop-down menu, select the branch that will be used to update the target branch.

    Step Information

  3. In the Target Branch drop-down menu, select the branch that will be updated to match the source branch.

    Step Information

  4. Do one of the following:

    • To replace all modified files, click Replace -> Replace All.

      The Resources Affected By Replace Operation window displays.

    • To only replace files that have been approved, click Replace -> Replace Approved.

      The Resources Affected By Replace Operation window displays.

  5. Click Submit.
result

The target branch is updated with content in the source branch.

Merging Some Changes Between Map Branches

Use the Branching Tab in the Resource Viewer to merge map branches and select which changes are pushed from the source branch into the target branch.
  1. In the Content Manager, right-click a map and select Branch .Branching Tab
  2. In the Source Branch drop-down menu, select the branch that will be used to update the target branch.

    Step Information

  3. In the Target Branch drop-down menu, select the branch that will be updated to match the source branch.

    Step Information

  4. Click Merge .

    Expected Result
    The Merge Branches window displays.
  5. To merge changes from a branch, click Merge .

    Step Information
    The Merge File window displays.
    1. To accept the highlighted change, click Accept .
    2. To reject the highlighted change, click Reject .
    3. Click Save.
  6. To ignore changes that should not be applied to the target branch, click Ignore .
result

The changes in the source branch are pushed into the target branch.

Merging All Changes Between Map Branches

Use the Branching Tab in the Resource Viewer to merge all changes from one branch into another.
  1. In the Content Manager, right-click a map and select Branch .Branching Tab
  2. In the Source Branch drop-down menu, select the branch that will be used to update the target branch.

    Step Information

  3. In the Target Branch drop-down menu, select the branch that will be updated to match the source branch.

    Step Information

  4. Click Merge .

    Expected Result
    The Merge Branches window displays.
  5. Click Add all to target branch.
result

You pushed all the changes from the source branch to the target branch.