User Guide
Table of Contents
User Guide
Branching
Branches
Branching a versioning tool enabling you to create a parallel set of content in a "branch" so you can edit the branched content without affecting the original content and push changes from one branch to another.
Visual Compare
Compare differences between your current map and a branched map using Visual Compare .
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.
Merging into an Existing Branch
Merge a branched map into an branch that doesn't contain the map.
Deleting a Branch
If you've already merged the branched content into the master branch, then you can delete the branched content if you no longer need it. Deleting a branch permanently removes it from easyDITA.
Branches

Branching a versioning tool enabling you to create a parallel set of content in a “branch” so you can edit the branched content without affecting the original content and push changes from one branch to another.

section
The branching 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.
Note:You must be an Administrator or have specific user permissions to branch and release content.

Branching is map-based, meaning you can only create branches for maps. To branch your map, 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 file’s history. You can view and even restore a previous version before the merge using the History Tab.
Your default branch is named “master”. You can switch to another branch using the Branch Menu. Search is enabled in this menu so you can quickly find the branch you’re looking for.
section

Creating a Branch

When you branch a map, full copies of each component in the map and its link dependencies are created in a branch. 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 reference topics that aren’t directly in the map (for example, ReferenceA), 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 modifying content in a branched map, you may need to merge changes from your branched map to the master or even to any branch that contains the map. When merging between branches, you’ll be asked to Approve or Reject any differences in the topics you’re merging. For example:
During a merge, you can also push completely new resources like topics or images to the Target Branch.
section

Merging into an existing branch

The branching feature uses a selective branching system, enabling you to merge into a branch that doesn’t contain the map. When you merge into the Target 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 in the Target Branch. Let’s look at an example.
Below we have two branches: BranchA and BranchZ. You can make three observations about these branches:
  • BranchA contains ReferenceA topic and a link between ReferenceA and ConceptB.

  • BranchZ contains TaskC and a link between TaskC and ConceptB.

  • Both BranchA and BranchZ contain the ConceptB topic.

Two branches
This is what happens when you merge BranchA into BranchZ:

Branching BranchA to BranchZ
When you merge BranchA (Source Branch) into BranchZ (Target Branch), the following occurs:
  • A copy of Map ABC is created in BranchZ.

  • The link in ReferenceA to ConceptB is relinked to the existing ConceptB in BranchZ.

Visual Compare

Compare differences between your current map and a branched map using Visual Compare .
section
When you’re merging changes between branches, you can use the Visual Compare button to compare the differences between the current map and a branched map. Visual Compare displays the XML of the map and highlights changes.
The highlighted changes indicate added or removed resources in the map you’re doing a comparison to. Changes highlighted in red indicate that the resource does not exist in the map you’re comparing against. Changes highlighted in green indicate that the resource exists in the map you’re comparing against, but not in the current map.
Creating a Branch

Use the Branching Tab in the Resource Viewer to create a parallel set of content in a new branch.
context
Tip:Before creating a branch, do a test publish to an output like PDF or HTML to ensure that your publication doesn’t contain any broken links.
  1. In the Content Manager , right-click a map and select Branching . Branching Tab
  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 Branching . 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 Branching . 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 Branching . 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.

Merging into an Existing Branch

Merge a branched map into an branch that doesn’t contain the map.
context
  1. In the Content Manager , right-click a map and select Branching . Branching Tab
  2. Click New Branch .

    Expected Result
    The Create New Branch window displays.

  3. Select a branch to merge your map into and click Save .
result

You merged the map into the selected branch.

Deleting a Branch

If you’ve already merged the branched content into the master branch, then you can delete the branched content if you no longer need it. Deleting a branch permanently removes it from easyDITA.
context
You’re in the Dashboard interface and want to permanently delete a branch.
Note:You must be an Administrator to access the Administration interface.
  1. Click Branching .

    Expected Result
    The available branches are listed.
  2. Beside the branch you want to delete, click Remove.

    Expected Result
    A confirmation dialog displays.
  3. In the field, enter DELETE and then click DELETE.
result

The branch is permanently deleted.