Branch components

If you want to make a copy of a component and maintain a relationship between the original component and the new copy, you can use the Save as a branch option. This is helpful if there are different versions of a component that you want to track and update separately but still want to have a common starting point for the information.

A content owner or administrator can set permissions to deny access to components or folders. If your permissions to content has been blocked and you are not an administrator, you cannot use the Save as branch option in a project's Content pane.

For example, you want to create a prototype of a book with a new style that you want to distribute in a test market.

  • You can take the original components of the standard-style book and create a branch.
  • Then you can edit the content in the branch to create the prototype.
  • While creating the prototype you may need to refer back to the standard style.
  • You'll be able to see where the original content came from because Inspire tracks the branched relationship.

When you select the Save as a branch... option, you can choose to either save all references or select only the ones you want to include in the new branch.

  • To keep all the same references in the branch copy that exist in the source, click Create.
  • To see the references or select a customized list of references in the List or Hierarchy view, select Show referenced components.

By default, the Show referenced components option is not selected.

When branching a component, you must decide if you also want to branch the components that it references. You can choose from:
  • No referenced components
  • All referenced components
  • Referenced components except xref/conref
  • Referenced components except xref/conref/images

You may not see all referenced components on the Save as a branch screen.

  • Components that are referenced in the source component are only listed if:
    • You select the Show referenced components option
    • In the Branch referenced components dropdown menu you select anything other than No referenced components
    • It doesn't have a tag applied to it called ExcludeFromBranch. For more details, read Prevent branching.

Whenever you save a component by branching, Inspire ensures content that is read from Right-to-Left displays correctly in Oxygen.

For the topic's language, Inspire sets the Reading property in these cases:
  • If it doesn't exist yet
  • Only if the language Reading property is rtl (Right-to-Left)
  • For example: <concept id="concept_guid" xml:lang="ar-Ar" dir="rtl">
  • Inspire makes no changes if the language Reading property is ltr (Left-to-Right)

Quickly branch a component with many references

To quickly branch a component with a long list of references, leave the Show referenced components option unselected and click Create.
  • Clearing this option means you don't have to wait for Inspire to list all the references in the List or Hierarchy views.
  • This action branches the source component along with the references you select in the Branch referenced components dropdown menu.
For example, if you:
  1. Go to the Branch referenced components dropdown menu and select Referenced components except xref/conref/images.
  2. Clear the Show referenced components option.
  3. Click Create.
Inspire branches the source components and all the topics it references. No cross references, content references, or images are branched.

Can I choose which references are branched?

If you want to customize which references are branched, you can choose All referenced components, make sure the Show referenced components option is selected, and then in the Hierarchy or List view, select the checkbox for only the components you want to branch.

You can't clear the checkbox for the source component. If don't want to branch the source component, click Cancel, find the source component you want to use, and then select Save as a branch again.

You may not see all referenced components on the Save as a branch screen.

  • Components that are referenced in the source component are only listed if:
    • You select the Show referenced components option
    • In the Branch referenced components dropdown menu you select anything other than No referenced components
    • It doesn't have a tag applied to it called ExcludeFromBranch. For more details, read Prevent branching.

To decide what to branch, use the following options:
  • On the Save as a branch dialog, the component you selected to branch is displayed in bold. This is considered the source component.
  • In the Branch referenced components field, if you select anything other than No referenced components, you see a hierarchical list of other components that are referenced by the source component. In the following figure above, this includes:

    • The root parent topic (Introduction)
    • Three child components
      • One binary image (EOSR5)
      • Two conceptual DITA topics (What is CMOS?, and What is DIGIC?)
    • Two child components with children of their own
      • What is CMOS (CMOS1, and CMOS2)
      • What is DIGIC? (DIGIC4)
  • By default, references are shown in a hierarchical view. You can expand and collapse parent topics in the hierarchical list to find the components you want to select.
    • To expand all parent topics, click Expand all

    • To collapse all parent topics, click Collapse all

    • To expand one parent topic, click Expand children

    • To collapse one parent topic, click Collapse children

  • If you want to see references as a list, select List View.

Can I choose where the branched copies are saved?

By default

Copies of all components (source and reference) that you select are branched and saved in the Target Folder.

For example:

  • A source component called Chapter2_Attach the strap is stored in a Target Folder called Tasks.
  • Two image files are referenced by the source component and are stored in an Images folder.

If you don't select the Keep folder structure option. (The Target Folder option remains available.)

  • Any components you select to branch—by default the copies are created in the Target Folder (Tasks).
  • This happens even if the referenced components are currently stored in a different folder.
  • You can select a different Target Folder however all branched copies are saved there.

Change the default

If you want to create a copy of the source and image components, but you want the copies to be saved in their current folders, you can select the Keep folder structure option.

In this example:

  • You select the Keep folder structure option. (The Target Folder option is greyed out and becomes unavailable.)
  • You select the source component and the three image files.
  • After you click Create, the branched copy of the source component is saved in Tasks.
  • The branched copies of the images are saved in the Images folder.

How can I track a branch?

When you're creating a branch, you can now add a Label. This allows you to add more information about why the branch was created or a version number.

  • The Label is attached to the component name.
    • For example, if you right-click a component named GetStarted, and select Save as branch... when you go to the Label field and enter "New version updates", after you click Create:
      • Component name = GetStarted_New version updates
    • The Filename uses the Component name with the Label, and then adds a GUID to make it unique. For example:
      • File name = GetStarted_New_version_updates_0b2426a1-1831-4114-8611-5b8db7edd7ab.xml
  • You can also see the Label on the Component Details screen, on the Branches tab. Select the component, and from the right-click menu select Details. Select the Branches tab.

After you create a branch, in the Components browser, the branched components have an icon corresponding to their place in the branch.

  • Black is the source component for a branch
  • Green was branched because a source component referenced it
  • Orange is both the source of one branch and included in another branch because a different source component referenced it