Branching is used in software version control. Copies of project files called branches allow teams to work on parallel versions of the project at the same time while retaining an unedited copy. This eliminates the risk of accidentally overwriting others’ changes to project files.
The main project is copied when a new branch is created with changes being made only to that branch. When changes are complete, the branch is merged back into the main project. Multiple branches can be worked on at the same time and after merging, branches can be deleted. Tags from an existing branch are copied to the new branch.
Limitations
-
All roles except Translator and Guest have access to the view.
-
Merges cannot be reverted and branches cannot be undeleted.
-
Jobs created in a specific branch are not visible in the main project and vice versa. When a branch is merged into the main project, any open jobs in it are lost.
-
Reports in the
view reflect only the status of the active branch. Merging a branch into the main project updates the main project reports. -
The
view contains only activities in the active branch. Activities in branches are not visible in the main project and vice versa. Activities in a branch are lost when merging it into the main project. -
GitHub Sync can only be used on the main project and not on branches.
-
Comments made in a branch are not visible in the main project and vice versa.
-
created in a branch are not visible in the main project and vice versa. When a branch is merged into the main project, any open orders in it are lost.
-
Translators cannot be restricted to specific branches but are given permission to work on specific locales. Translators should be instructed on how to work with branches.
Branching is enabled in the
tab of with the option to protect the main branch from changes.When enabled, a branch menu is presented on the project screen where working branches can be selected. To specify a branch in CLI, use the
--branch
parameter:
--branch <branch_name>
Branches are listed on the
view where creation and merging information is presented. Branches can also be deleted or merged and jobs created for that branch from the view.To list all branches for project via API or CLI, run:
$ phrase branches list <project_id>
To delete a branch via API or CLI, run:
$ phrase branch delete <project_id> <branch_name>
Admin, Project Manager and Developer roles can create new branches in the translation editor, via API or in the CLI.
To create a branch in the translation editor, follow these steps:
-
From a
page, select the tab. -
Click Create branch.
The
window opens. -
Provide a name for the branch.
-
Click Create branch.
The new branch is added to the list.
To create a branch via API or CPI, run:
$ phrase branches create --project_id <project_id> --data <data>
To create a branch when pushing translations, run:
$ phrase push --branch <branch_name>
After changes are made to a branch, it can be merged back into the main translation in order to incorporate any new translations.
Only changes to the following resources are applied to the main branch during merges:
-
Locales
-
Keys
-
Translations
Changes to other resources, such as Activities, Jobs, and Orders, are not applied.
Conflicts
A conflict occurs when a resource (translation, key, or locale) has changed in the main project between the time a branch is created and when it is merged back to the main project. For example, translations and key settings such as plural forms) may have changed in the main project after a branch is created making the values in the branch different from those in the main project.
To merge a branch, follow these steps:
-
From the Compare and Merge.
view of a project, select a branch for merging and clickThe
page opens. Information about translations to be modified during the merge can be accessed by clicking in the cells. -
If there are conflicts, select a merge strategy:
-
Select
to reject the conflicting changes and preserve existing translations. -
Select
to replace existing translations with changes from the branch.
-
-
Click Merge Branch.
The branch is merged to the main project.
To merge a branch via API or CPI, run:
$ phrase branches merge \
--project_id <project_id> \
--name <name> \
--data '{"strategy":"use_master"}' \
--access_token <token>
-
use_branch
resolves conflicts by applying changes from the branch and if not specified is the default. -
use_master
resolves conflicts by rejecting changes from the branch.
When using CLI, specify a branch to push or pull from with the --branch
parameter.
$ phrase push --branch <branch_name> $ phrase pull --branch <branch_name>
If the specified branch does not exist in a project, the client creates it.
Use --use-local-branch-name
to push and pull using the branch name of an active git branch:
$ phrase push --use-local-branch-name $ phrase pull --use-local-branch-name
All API endpoints that take a project argument also support the --branch
parameter to perform an action on a specific branch of a project:
$ phrase upload create <project_id> \ --branch <branch_name> --file /path/to/my/file.json \ --file-format json \ --locale-id abcd1234cdef1234abcd1234cdef1234 \ --tags awesome-feature,needs-proofreading \ --locale-mapping "{"en": "2"}" \ --format-options "{"foo": "bar"}"