Branches

Branches enable you to create an editable copy of a map with all dependencies in a separate space.

Branches are useful if you want to maintain multiple editable versions of content.
Note: Depending on your easyDITA configuration, some operations may be restricted to Administrators and users with specific permissions.

Branching Tab

Figure 1. Branching Tab

The Branching tab enables you to do the following:

  • Create a branch from a map
  • Merge content from one branch with content in another branch
  • Replace content from one branch with content from another branch

Branch Menu

The Branch drop-down menu enables you to switch the branch that you are working on.
Tip: We recommend using the default master branch to develop the current version of your documentation.
Figure 2. Branch Menu

Topic Merge/Replace Icon

The topic editor enables you to quickly merge/replace a topic from one branch to a topic in another branch.
Note: By default, merging/replacing topics is disabled and the Topic Merge/Replace icon is hidden. To enable this feature, contact a Customer Success Manager.
Figure 3. Topic Merge/Replace icon

History Tab

Merging or replacing branches creates a history entry that enables you to view and restore a file to the former version by using the History tab.

Figure 4. History Tab

Guidelines

Keep the following guidelines in mind when working with branches:

  • Before creating a branch, check the content for errors. You can do that by publishing your content and verifying how the output looks.
  • Establish a branches naming convention. Once you create a branch, you cannot change its name.
  • Designate a person, for example a team leader, who will be responsible for merging and replacing branches.
  • The resources in branches count against your content object limits.

Example

Figure 5. Branches.

In the following example, each branch corresponds with a particular product guide version. The branches can be edited at any point.

Create a Branch

You can only create branches from maps.

Switch to the branch that you want to branch content from. For more information, see Switch Branches.
  1. In the content library, right-click a map and select Branching .
  2. Click Create Branch.
  3. Fill in the New branch name field.
  4. Optional: If you do not want to switch to the new branch when it is created, clear the Navigate to new branch check box.
  5. Click Create.

Switch Branches

You can see the contents of different branches in the content library by switching between the branches.

In the content library, in the right-top corner, from the Branches drop-down menu, select a branch.
Figure 6. Branches Menu.

The branches menu is hidden if you have a single branch.

Merge Branches

easyDITA enables you to merge changes between branches and resolve conflicts.

Switch to the branch that you want to merge content from. For more information, see Switch Branches.
  1. If you want to merge a map to another branch, do the following:
    1. In the content library, right-click a map and select Branching .
    2. Click Push Changes > Merge.
  2. If you want to merge a topic to another branch, do the following:
    Note: By default, merging/replacing topics is disabled and the Topic Merge/Replace icon is hidden. To enable this feature, contact a Customer Success Manager.
    1. In the content library, hover over a topic or a map that contains the topic, and click Open.
    2. In the Topic Toolbar, click the Topic Merge/Replace icon and select Merge.
      Figure 7. Topic Merge/Replace Icon
  3. In the Merge dialog, from the Into drop-down menu, select the branch that you want to merge to.
    Figure 8. Into Menu
  4. In the Filter files to be merged section, do any of the following:
    • To only merge the files with given file statuses, complete the File Status field.
    • To only merge the files owned by a given user, complete the Owner field.
  5. Click Continue.
  6. If the Conflict Manager window appears, do the following:
    Figure 9. Conflict Manager.

    The Conflict Manager may contain entries in the following sections: Changed Files, Added Files, and Moved and Renamed Files.

    1. For each resource or section, select an appropriate option.
    2. If prompted, accept or reject changes and select an appropriate option.
    When every conflict is resolved, a dialog appears.
  7. In the dialog, click Finish.

Overwrite Branches

easyDITA enables you to overwrite branches by replacing files in one branch with files from another branch.

Switch to the branch with content that you want to use to overwrite another branch. For more information, see Switch Branches.
  1. If you want to overwrite a map in another branch, do the following:
    1. In the content library, right-click a map and select Branching .
    2. Click Push Changes > Replace.
  2. If you want to overwrite a topic in another branch, do the following:
    Note: By default, merging/replacing topics is disabled and the Topic Merge/Replace icon is hidden. To enable this feature, contact a Customer Success Manager.
    1. In the content library, hover over a topic or a map that contains the topic, and click Open.
    2. In the Topic Toolbar, click the Topic Merge/Replace icon and select Replace.
      Figure 10. Topic Merge/Replace Icon
  3. In the Replace dialog, from the Into drop-down menu, select the branch with content that you want to replace.
    Figure 11. Into Menu
  4. In the Filter files to be merged section, do any of the following:
    • To only overwrite the files with given file statuses, complete the File Status field.
    • To only overwrite files owned by a given user, complete the Owner field.
  5. Click Replace.
    The Branching Tab displays the progress of the replace operation.

Revert Branching Operations

You can revert the branch merge and branch overwrite operations by using the History tab.

Note: easyDITA stores the history of DITA and non-DITA resources. This means that you can revert maps, topics, and media files to their previous versions at any time.
Important: Reverting a resource to its previous version does not revert the resource dependencies to their previous versions. For example, if you revert a map to its previous version, the topics in a map will not be reverted to their previous versions.
  1. In the content library, right-click a resource that was impacted by a branching operation and select History.
  2. In the History tab, do the following:
    1. In the left pane, locate the branching operation Revision that you want to revert.
      Branching operations are labeled with either “Branched” or “Merged”.
    2. Select a Revision occurred before the branching operation.
    3. In the right pane, click Restore.
  3. In the dialog, click OK.
  4. In the Edit the commit details window, click Save.

Remove a Branch

Only easyDITA Administrators can remove branches.

Warning: Removed branches cannot be restored!
  1. In the Dashboard, click Branching.
  2. In the list, identify the branch that you want to delete and click the corresponding Remove button.
  3. Warning: The following operation cannot be reversed!
    In the dialog, type in DELETE and click DELETE.