feat: branching

[dkrizan]

Summary by CodeRabbit

• New Features
  • Project branching: create, list, delete branches and view branches UI.
  • Branch merging: dry-run previews, conflict detection, resolve and apply merges.
  • Branch-scoped workflows: filter/select branches for keys, translations, exports, and content delivery.
  • UI additions: branch list, branch selector, branch creation modal, branch-related chips and controls.

[coderabbitai[bot]]

[!IMPORTANT]

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Walkthrough

Adds project branch support across backend, database, and frontend: new Branch entities and migrations, branch-aware key/translation queries and services, branch merge/dry-run/conflict workflows with APIs and UI for branch management and selection.

Changes

Cohort / File(s)	Summary
Branch domain & schema backend/data/src/main/kotlin/io/tolgee/model/branching/Branch.kt, backend/data/src/main/kotlin/io/tolgee/model/branching/BranchMerge.kt, backend/data/src/main/kotlin/io/tolgee/model/branching/BranchMergeChange.kt, backend/data/src/main/resources/db/changelog/schema.xml	New Branch entity, merge entities, related DB tables/columns, indexes and FKs; archived/default semantics and revision column.
Branch-versioning contracts backend/data/src/main/kotlin/io/tolgee/model/branching/BranchVersionedEntity.kt	New interface for branch-versioned entities (resolveKeyId/isModified/diff/merge).
Key / Translation model updates backend/data/src/main/kotlin/io/tolgee/model/key/Key.kt, backend/data/src/main/kotlin/io/tolgee/model/key/KeyMeta.kt, backend/data/src/main/kotlin/io/tolgee/model/translation/Translation.kt	Key gained nullable Branch relation and cascadeUpdatedAt; KeyMeta and Translation implement branch-versioning methods.
Repositories & queries (branch-aware) backend/data/src/main/kotlin/io/tolgee/repository/KeyRepository.kt, backend/data/src/main/kotlin/io/tolgee/repository/TranslationRepository.kt, backend/data/src/main/kotlin/io/tolgee/repository/KeyMetaRepository.kt, ee/backend/app/src/main/kotlin/io/tolgee/ee/repository/branching/BranchRepository.kt, ee/backend/app/src/main/kotlin/io/tolgee/ee/repository/branching/BranchMergeRepository.kt, ee/backend/app/src/main/kotlin/io/tolgee/ee/repository/branching/BranchMergeChangeRepository.kt	Added branch-aware queries and projections, prefetched lookups, branch-specific counts and pagination; new branch repositories for EE.
Services: branch lifecycle, copy, merge, meta backend/data/src/main/kotlin/io/tolgee/service/branching/BranchService.kt, backend/data/src/main/kotlin/io/tolgee/service/branching/BranchServiceOssStub.kt, ee/backend/app/src/main/kotlin/io/tolgee/ee/service/branching/BranchServiceImpl.kt, ee/backend/app/src/main/kotlin/io/tolgee/ee/service/branching/BranchCopyServiceSql.kt, ee/backend/app/src/main/kotlin/io/tolgee/ee/service/branching/BranchMergeService.kt, ee/backend/app/src/main/kotlin/io/tolgee/ee/service/branching/BranchCleanupService.kt, ee/backend/app/src/main/kotlin/io/tolgee/ee/service/branching/BranchCopyServiceSql.kt, ee/backend/app/src/main/kotlin/io/tolgee/ee/service/branching/DefaultBranchCreator.kt, ee/backend/app/src/main/kotlin/io/tolgee/ee/service/branching/BranchMetaUpdater.kt	New branch management interface/impls, OSS stub, copy-by-SQL implementation, merge dry-run and conflict logic, branch cleanup and meta updater for revisions.
Key/Translation service threading backend/data/src/main/kotlin/io/tolgee/service/key/KeyService.kt, backend/data/src/main/kotlin/io/tolgee/service/translation/TranslationService.kt, backend/api/src/main/kotlin/io/tolgee/api/v2/controllers/translation/CreateOrUpdateTranslationsFacade.kt, backend/api/src/main/kotlin/io/tolgee/api/v2/controllers/translation/TranslationsController.kt, backend/api/src/main/kotlin/io/tolgee/api/v2/controllers/keys/KeyController.kt, backend/api/src/main/kotlin/io/tolgee/component/KeyComplexEditHelper.kt	Threaded optional branch parameter through key/translation creation, find, edit, and paged listing endpoints and service calls.
Export & content delivery params backend/data/src/main/kotlin/io/tolgee/dtos/request/export/ExportParams.kt, backend/data/src/main/kotlin/io/tolgee/dtos/ExportParamsDocs.kt, backend/data/src/main/kotlin/io/tolgee/hateoas/contentDelivery/ContentDeliveryConfigModel.kt, backend/data/src/main/kotlin/io/tolgee/dtos/request/ContentDeliveryConfigRequest.kt, backend/data/src/main/kotlin/io/tolgee/model/contentDelivery/ContentDeliveryConfig.kt, backend/api/src/main/kotlin/io/tolgee/controllers/ExportController.kt, backend/data/src/main/kotlin/io/tolgee/dtos/IExportParams.kt	Added filterBranch parameter across export DTOs and content delivery config; export query filtering support.
Big meta / utilities / query builders backend/data/src/main/kotlin/io/tolgee/service/bigMeta/BigMetaService.kt, backend/data/src/main/kotlin/io/tolgee/service/bigMeta/KeysDistanceUtil.kt, backend/data/src/main/kotlin/io/tolgee/service/queryBuilders/LanguageStatsProvider.kt, backend/data/src/main/kotlin/io/tolgee/service/queryBuilders/ProjectStatsProvider.kt, backend/data/src/main/kotlin/io/tolgee/service/queryBuilders/translationViewBuilder/QueryGlobalFiltering.kt, backend/data/src/main/kotlin/io/tolgee/service/export/dataProvider/ExportDataProvider.kt	Propagated branch joins and filters into big-meta queries, distance util, stats providers and global translation filtering.
DTOs and API schema updates backend/data/src/main/kotlin/io/tolgee/dtos/request/key/CreateKeyDto.kt, backend/data/src/main/kotlin/io/tolgee/dtos/request/key/EditKeyDto.kt, backend/data/src/main/kotlin/io/tolgee/dtos/request/key/ComplexEditKeyDto.kt, backend/data/src/main/kotlin/io/tolgee/dtos/request/translation/SetTranslationsWithKeyDto.kt, backend/data/src/main/kotlin/io/tolgee/dtos/request/translation/TranslationFilters.kt, backend/data/src/main/kotlin/io/tolgee/dtos/queryResults/KeyView.kt, backend/data/src/main/kotlin/io/tolgee/dtos/queryResults/KeyIdFindResult.kt, backend/data/src/main/kotlin/io/tolgee/dtos/queryResults/branching/*, webapp/src/service/apiSchema.generated.ts	Added optional branch fields to many DTOs and query result types; new branching request/response DTOs; TypeScript API schema updated.
Controllers & HATEOAS models/assemblers ee/backend/app/src/main/kotlin/io/tolgee/ee/api/v2/controllers/branching/BranchController.kt, ee/backend/app/src/main/kotlin/io/tolgee/ee/api/v2/hateoas/model/branching/*, ee/backend/app/src/main/kotlin/io/tolgee/ee/api/v2/hateoas/assemblers/branching/*, backend/api/src/main/kotlin/io/tolgee/hateoas/key/*	New BranchController EE endpoints (list/create/delete/merge/conflicts/resolve/apply) and corresponding HATEOAS models/assemblers; KeyModel/KeyWithDataModel extended with branch.
Test data builders & tests backend/data/src/main/kotlin/io/tolgee/development/testDataBuilder/*, backend/app/src/test/kotlin/... , ee/backend/tests/src/test/kotlin/...	New branch-related test data builders, many updated/added tests covering branch visibility, translations, creation, merges, revisions, and cleanup.
Frontend UI: branch management & selection webapp/src/component/branching/*, webapp/src/ee/branching/*, webapp/src/views/projects/translations/context/*, webapp/src/views/projects/ProjectRouter.tsx, webapp/src/eeSetup/eeModule.ee.tsx, webapp/src/constants/links.tsx, webapp/src/constants/GlobalValidationSchema.tsx, webapp/src/component/searchSelect/InfiniteSearchSelect.tsx	New BranchSelect, BranchSelector, BranchesList, Branch form/modals, BranchLabel and chips, integration with translations context and routing; validation and link constants updated; infinite select enhancements.
Misc & messages backend/data/src/main/kotlin/io/tolgee/constants/Message.kt, backend/data/src/main/kotlin/io/tolgee/development/testDataBuilder/data/ImportTestData.kt	New message codes for branch errors and added test metadata authors.

Sequence Diagram(s)

sequenceDiagram
    participant User
    participant UI as Frontend
    participant API as BranchController / TranslationsController / KeyController
    participant Service as BranchService / KeyService / TranslationService
    participant Repo as Repository Layer
    participant DB as Database

    User->>UI: open translations or branches view
    UI->>API: GET /v2/projects/{id}/branches or GET keys/translations?branch={name}
    API->>Service: fetch branches or branch-scoped keys/translations (branch param)
    Service->>Repo: execute branch-aware query (LEFT JOIN branch, filter archived/default)
    Repo->>DB: SELECT ... FROM key LEFT JOIN branch ... WHERE (branch IS NULL OR branch.name = :branch ...)
    DB-->>Repo: rows
    Repo-->>Service: mapped DTOs (KeyView/Translation)
    Service-->>API: return models
    API-->>UI: render branch-aware list

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~75 minutes

Areas requiring extra attention:

• Branch merge algorithm and conflict resolution (BranchMergeService, BranchMergeChange, decision logic).
• Query correctness and NULL/default branch semantics in repository queries and query builders (KeyRepository, TranslationRepository, QueryGlobalFiltering).
• Database migration safety and index/constraint changes in schema.xml (concurrent index creation and unique constraints with COALESCE).
• Branch revision snapshotting and async updates (BranchMetaUpdater, BranchContentEventListener).
• End-to-end propagation of branch parameter through controllers, services, and DTOs (KeyService, TranslationService, controllers, frontend hooks).
• Tests that depend on branching behavior and new test data builders.

Suggested labels

enhancement

Suggested reviewers

• JanCizmar

Poem

"I am a rabbit in the code-filled glade,
I plant small branches in each project-made,
Keys hop between main and feature lane,
Merges nibble conflicts, then hop again.
A tiny drumbeat — revisions softly play!" 🐇

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 2.68% which is insufficient. The required threshold is 80.00%.	You can run @coderabbitai generate docstrings to improve docstring coverage.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title Check	✅ Passed	The PR title "feat: branching" is directly related to the primary change in this extensive changeset, which introduces comprehensive branching functionality throughout the application including new Branch entity, merge capabilities, branch-scoped filtering for keys and translations, branch management endpoints, UI components, database schema changes, and supporting services. The title is concise and specific enough that a developer scanning commit history would immediately understand that a branching feature is being added, without requiring unnecessary detail. The title follows conventional commit format and clearly conveys the main objective without being vague or generic.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}