Branching FAQs

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.

How do I 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 you 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.

    The source component is displayed in bold only in List View.

  • 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: branch copies of all components (source and reference) that you select are 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.

  • Any components you select to branch—by default the branched 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. If you do, all branched copies are saved in that one folder.

For example:

Change the default

If you want to create a branched copy of the source and image components, but you want the branched 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.

    After you select the Keep folder structure option, the Target Folder option is greyed out and becomes unavailable.

    If you want to select a different Target Folder, do it before you select Keep folder structure or clear the Keep folder structure option and choose a different Target Folder.

  • You select the source component and the two 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.

If you selected a different Target Folder and the Keep folder structure option, Inspire creates the branched copies in the same folder structure as they had, but under the Target Folder you just selected. If the folders do not exist, Inspire creates them.

For example:

In this example, the branched copies are found in different folders according to where the original was stored, but under the Target Folder Version 2.0.

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.

The Name can also be known as the Label.

  • This is because the snapshot Name doesn't replace the component name, but allows you to identify why the history record was created.
    • When you create a snapshot on demand, the Name becomes the label but is always shown as Name.
    • When you branch a component, you add a title in the Label field. In the History record (of snapshots), the Label is always shown as Name.
    • Long unique numbers are also attached to custom labels, so be sure to keep your label short. For MyLabel__93746df4-558f-4414-9423-52835fa5d2cd.
  • Later, if you update a snapshot, you can edit the Name (Label) as long as the history record isn't for a Branch action.
  • You cannot update the Name (Label) for a snapshot where the Action is Branch.

    If you open the Component Details, select the History tab, and choose a record where Action is Branch you cannot select the Update option.

  • You can update the Name (Label) for all other types of snapshots.

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.

    When you hover your cursor over the black branch icon, you see a tooltip telling you it has a branch and also how many branches have been created from it. For example, Has 2 branches.

  • Green was branched because a source component referenced it.

    When you hover your cursor over the green branch icon, you see a tooltip telling you it is part of a branch. For example, Is a branch.

  • Orange is both the source of one branch and included in another branch because a different source component referenced it.

    When you hover your cursor over the orange branch icon, you see a tooltip telling you it is part of a branch and also how many branches have been created from it. For example, Is a branch and has 1 branch.

Can I see all the branch relationships in a report?

Yes.

To see a report on the relationships a component has with other components, if it's the source of a branch, is part of a branch, or is both, and find the location of all components in the branch, you can generate and view a branch report.

In the Components browser, you can select a branched component, right-click or use the Options menu to select Reports, and then select Branch Report.

You must select a component with the following properties in order to see the Branch Report option:

  • Is the source of a branch
  • When hovering over the branch icon, identified as Is a Branch
  • Has the icon for Is a Branch

You can also go to the Selected Components pane, select the Reports menu, and then select Branch Report.

You cannot create a branch or a branch report from inside a project.

You see a separate notification for each component you select. You also get a separate report for each component you select.

On the Notifications tab, you can see the report details.

In the example report above:

  • The component that you selected to run the report on (DSLQR_Map_1200) is the source of a branch (DSLQR_Map_1200_Rev2). The branch has the same component name with a Label of Rev2.
  • The source component references topics that have been branched from another component (GetStarted_Intro_Rev1, from DSLQR_Map_1100_Rev1).
  • There is a section header for each branch that contains the same topics referenced by the component that the report was run on (DSLQR_Map_1200).

You can use this report to do the following:

  • See indirect references. You can find components (shown in red) that have references in common with the selected component (DSLQR_Map_1200). The components shown in red contain one or more of the same topics in the source component. They contain a reference as a branch of another branch but not a direct reference from the source component.

    In this case, the map DSLQR_Map_1100_Rev1 (shown in red) references CameraBodyParts_Rev1. The source component (DSLQR_Map_1200) also references CameraBodyParts_Rev1.

    This is helpful because it shows you that there are branched maps you might want to review and consider connecting the source component to.

  • Go to all. If you want to open the folder that contains all the components listed in a section of the report, click the Select All link.

    • If you click this link from an email, a browser tab opens, and Inspire opens to the Components browser.
    • If you click this link from a notification inside of Inspire, the Components browser opens.
    • In the browser, you see all of the components highlighted from that section of the report.
    • If the components are in different folders, you see the items from the first folder listed in the Folders pane.
    • The components are also listed in the Selected Components pane
  • Open one. If the component's content needs to be updated, you can click on the component Name, which is a link that opens the component in the Oxygen editor.

    • The Name is listed first.
    • The Name does not contain the file extension. For example, "Chapter1_Charge your battery_IconCheck".
    • If the component is locked or a binary, you see the component in a read-only viewer
  • Go to one. If you need to update a component using a system function, such as Rename, you can click on the File Name which is a link that opens the folder where it's stored.

    • The File Name is listed second, after the shorter Name and in parenthesis ().
    • The File Name contains the file extension. For example, "Chapter1_Charge_your_battery_IconCheck_070e9999-fe40-4747-b57d-ba1096b925ed.xml.