From e5788f1a2357ada093f7be3e32dcc075ec9de000 Mon Sep 17 00:00:00 2001 From: Daniel Krizan Date: Tue, 17 Feb 2026 19:54:10 +0100 Subject: [PATCH] docs: add CLI branching documentation Document the new branching feature from tolgee-cli PR #195: - Add --branch global option to usage page - Add branch config property to project configuration - Create new branching.mdx page (branch/merge commands) - Add branching page to sidebar navigation --- sidebarTolgeeCli.js | 1 + tolgee-cli/branching.mdx | 81 ++++++++++++++++++++++++++++ tolgee-cli/project-configuration.mdx | 4 ++ tolgee-cli/usage.mdx | 1 + 4 files changed, 87 insertions(+) create mode 100644 tolgee-cli/branching.mdx diff --git a/sidebarTolgeeCli.js b/sidebarTolgeeCli.js index f2844bc08..fd2fca59e 100644 --- a/sidebarTolgeeCli.js +++ b/sidebarTolgeeCli.js @@ -5,6 +5,7 @@ module.exports = { 'usage', 'project-configuration', 'push-pull-strings', + 'branching', { collapsed: false, label: 'Extracting from code', diff --git a/tolgee-cli/branching.mdx b/tolgee-cli/branching.mdx new file mode 100644 index 000000000..e3bf2d75f --- /dev/null +++ b/tolgee-cli/branching.mdx @@ -0,0 +1,81 @@ +--- +id: branching +title: Branching +image: /img/og-images/cli.png +--- + +Tolgee supports project branching, allowing you to work on translations in isolated branches — similar to how Git branches work for code. The CLI lets you scope commands to a specific branch and manage branches directly from the terminal. + +## Specifying a branch + +When branching is enabled for your project, you can scope commands to a specific branch using any of these methods (from highest to lowest priority): + +1. **CLI option**: `--branch ` (short: `-b`) +2. **Environment variable**: `TOLGEE_BRANCH` +3. **Project configuration**: `branch` field in [`.tolgeerc`](./project-configuration.mdx#branch) + +The branch option applies to the following commands: `pull`, `push`, `sync`, `compare`, `tag`. + +``` +tolgee pull --branch my-feature --path ./i18n +TOLGEE_BRANCH=my-feature tolgee push +``` + +## `tolgee branch` + +List, create, or delete project branches. + +``` +tolgee branch [branch] [options] +``` + +When called without arguments or options, lists all branches in the project. + +Options: + +- `[branch]` – Branch name to create (positional argument). +- `--create ` – Create a new branch. Alternative to passing the branch name as a positional argument. +- `-d, --delete ` – Delete an existing branch. +- `-o, --origin ` – Origin branch to fork from. Defaults to the project's default branch. + +Examples: + +```bash +# List branches +tolgee branch + +# Create a branch from the default branch +tolgee branch my-feature + +# Create a branch from a specific origin +tolgee branch my-feature --origin develop + +# Delete a branch +tolgee branch --delete my-feature +``` + +## `tolgee merge` + +Merge a branch into its origin branch. + +``` +tolgee merge [branch] [options] +``` + +The branch to merge can be specified either as a positional argument or via the global `--branch` option. + +The command previews changes before applying the merge. If there are unresolved conflicts, the merge is aborted and a link to the Tolgee web app is provided so you can resolve them there. + +Options: + +- `[branch]` – Branch name to merge (positional argument). + +Examples: + +```bash +# Merge a branch +tolgee merge my-feature + +# Merge using the global --branch option +tolgee merge --branch my-feature +``` diff --git a/tolgee-cli/project-configuration.mdx b/tolgee-cli/project-configuration.mdx index 171fb1bbb..04495f750 100644 --- a/tolgee-cli/project-configuration.mdx +++ b/tolgee-cli/project-configuration.mdx @@ -12,6 +12,7 @@ Example configuration: { "$schema": "https://docs.tolgee.io/cli-schema.json", "projectId": 123, // project id in tolgee platform + "branch": "my-feature", // project branch (when branching is enabled) "format": "JSON_TOLGEE", "patterns": ["./src/**/*.ts?(x)"], // pattern for code extraction "push": { @@ -65,6 +66,9 @@ Use `apiKey` only if you are loading it from an environment or other secured sou In most cases, it's better to use a one-time [login command](./usage.mdx#logging-in) or set it via the `TOLGEE_API_KEY` environment variable. ::: +### `branch` + +String. Project branch name. Use when [branching](./branching.mdx) is enabled for the project. Can also be set via the `TOLGEE_BRANCH` environment variable or `--branch` CLI option. ### `format` diff --git a/tolgee-cli/usage.mdx b/tolgee-cli/usage.mdx index 2bfabcef9..02c92add1 100644 --- a/tolgee-cli/usage.mdx +++ b/tolgee-cli/usage.mdx @@ -16,6 +16,7 @@ in a [per-project configuration](./project-configuration.mdx). May be omitted if you are [logged in](#logging-in). You can also set it via the `TOLGEE_API_KEY` environment variable (recommended for CI server use). - `--project-id ` (short: `-p`) – **Required**. Project ID on the Tolgee server. May be omitted if you explicitly specified a Project API Key via `--api-key` or `TOLGEE_API_KEY`. Can be [configured per-project](./project-configuration.mdx). +- `--branch ` (short: `-b`) – Project branch. Use when [branching](./branching.mdx) is enabled for the project. Can be set via the `TOLGEE_BRANCH` environment variable or [configured per-project](./project-configuration.mdx#branch). - `--format ` - Localization files format. [See all possible formats](./project-configuration.mdx#format) - `--extractor ` (short: `-e`) - A path to a custom extractor to use instead of the default one. - `--patterns ` (short: `-pt`) - File glob patterns to include (hint: make sure to escape it in quotes, or your shell might attempt to unroll some tokens like *)