Branches - archimatetool/archi-modelrepository-plugin2 GitHub Wiki

Branches

Background

Branching in coArchi is a powerful feature that allows multiple lines of development to coexist within the same repository. It enables users to work on different versions of models simultaneously without interfering with the main branch.

A branch is a lightweight, movable pointer to a commit in the repository’s history. The default branch is called "main" but you can create other branch names. When you create a new branch, you’re essentially creating a new pointer that allows you to make changes independently of other branches.

Why Use Branching?

  • Parallel Development: work on multiple versions of the model at the same time
  • Isolation: keep experimental or incomplete changes separate from the stable version
  • Collaboration: allow team members to work on different features of the model without conflicts
  • Safety: Protect the main branch from untested changes

Local and Remote Branches

It's important to understand that a branch exists both locally and on the remote server. When you first create a branch it is a local branch only, it is not present on the remote server. Switching to the branch ("checking out the branch" in Git terms) and publishing it to the remote server means that it will be present locally and remotely.

A branch can be present remotely but not locally if a collaborator has created the branch and published it. Other collaborators will see the new branch when they "Refresh" the repository.

Branches Panel

The Branches panel can be shown or hidden from the main "Collaboration" menu item "Toggle Branches" or from the main toolbar.

The Branches panel consists of a table that shows information for each branch.

Columns

Each column in the table is as follows:

Branch - the name of the branch. The current branch shows as "(current)"

Branch Status - the status of the branch. This can be:

  • Orphaned - the remote branch has been deleted but the local branch exists. This can happen if a collaborator deletes the branch on the remote server.
  • Available - both local and remote branches exist
  • Unpublished - the branch exists locally but has not yet been published. This can be achieved by switching to the branch and publishing it

Latest Commit Author - the name of the author who has contributed the latest commit to this branch

Latest Commit Date - the date and time of the latest commit to this branch

Commit Status - the status of the commit history. This can be:

  • Up to date - local and remote commits are synchronised
  • There are unpublished commits - there are local commits that have not yet been published to the remote server. Switch to the branch and "Publish" it.
  • There are new commits on the remote - there are new commits on the remote that have not yet been retrieved. Switching to this branch will change the status.
  • There are unpublished and new commits on the remote - there are local commits that have not yet been published to the remote server and there are new commits on the remote that have not yet been retrieved. Switch to the branch and "Refresh" followed by "Publish".

Merge Status - the status of the branch in relation to other branches. This can be:

  • OK - the branch has been merged into at least one other branch
  • Not merged - the branch has not been merged into another branch

Getting and Publishing Branches

In order to retrieve branches from the remote repository you need to perform a Refresh Model action.

To publish a local branch to the remote server you need to switch to the branch and then perform a Publish Changes action.

Actions

The following actions are available from the Branches table right-click context menu and from the toolbar.

Add New Branch to this Branch

This action allows you to add a new branch to the selected branch.

A dialog box allows you to enter a unique name for the new branch. Options are to just create the new branch or to create the new branch and immediately switch to it (this option is only available if the new branch is added to the "current" branch or the model has been saved and there are no pending commits).

[!Note] A branch can't be renamed. To work around this, switch to the branch and add a new branch with the desired name. Publish the new branch and delete the old branch.

Switch to this Branch

This action will switch to the selected branch and re-load the model. Double-clicking on the branch in the table also triggers this action. A dialog will appear if the model needs saving or a commit is necessary before switching to the new branch.

Merge Branch into Current Branch

This action will merge the selected branch into the current branch. A new commit will be made as necessary with the merged changes. If successful the branch will need to be published to the remote server.

[!Important] Merging and conflict handling is a work in progress. A merge may not be successful in which case you will have to choose between "Mine" and "Theirs".

Delete Branch

This action deletes the selected local and online branch. Be sure that the branch is merged or no longer needed before deleting it. This action is not enabled on the current branch.