> ## Documentation Index > Fetch the complete documentation index at: https://docs.hiveku.com/llms.txt > Use this file to discover all available pages before exploring further. # Branches, environments and pull requests > Work on a branch in the editor, point Development or Staging at it, review the change as a pull request, and merge it into main Every Hiveku project has built-in version control. You do not need GitHub to use branches: create one, work on it in the editor with a live preview and the AI chat, let Development or Staging serve it, open a pull request, and merge it into `main` when it is ready. This page covers projects using Hiveku's built-in version control. If your project is connected to GitHub, day-to-day branching usually happens there instead. See [Git Panel](/editor/github). ## The working branch selector The branch selector sits at the top left of the editor, next to the project menu. It shows the branch you are working on and switches everything in the editor to that branch: * The file tree and every open file * The live preview (each branch gets its own preview, see [Branch previews](#branch-previews)) * The AI chat, so edits from a chat turn land on the branch you are looking at * The Database panel, which shows the shared project database with a note explaining that data is not branched Open the selector to search your branches (when you have many), create a new branch, commit your changes, open a pull request, or jump to the Branches tab. `main` is always listed first and carries a lock icon; branches that already serve Development or Staging show a small environment dot; a branch with uncommitted changes shows an amber dot. The selector is available to members who can deploy the project. While the AI is still replying, the selector is disabled so the reply finishes on the branch it started on. ## Uncommitted and committed changes A branch has two states that the editor keeps separate: | State | What it means | | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Uncommitted** | Every save you make lands on the branch immediately. The preview and the AI see the change right away, but it has not been recorded as a named point in the branch's history. The selector shows an amber dot. | | **Committed** | You have given the current state a name. Commits are what pull requests compare, what environments deploy, and what you can return to later. | **Commit changes** in the selector records the whole branch as one commit. You write a message; there is no need to pick files. Uncommitted work is never lost between sessions, and Hiveku commits it for you whenever something needs a fixed point: * **Deploying** a branch to Development or Staging commits your unsaved branch changes first (the commit is named after the deploy, for example `Deploy to Development`). * **Merging** a pull request commits the source branch first, so the merge includes everything you saved. * **Creating a branch** from a branch with uncommitted changes commits those changes first. * **Deleting a branch** with uncommitted changes takes a snapshot first, so nothing disappears silently. * **An AI chat turn** on a branch starts from a commit of your editor changes and ends with a single commit of what the AI wrote, so **Undo this turn** returns the branch to exactly where it was. Commit on your own when you reach a state you would want to come back to. The automatic commits keep you safe; deliberate commits give you a readable history. ## Environments: which branch each tier serves | Tier | What it serves | | --------------- | ------------------------------------------------------------------------------------------------------------------------------------- | | **Production** | Always `main`. This cannot be changed. The only way to ship a branch to production is to merge it into `main` through a pull request. | | **Development** | `main` by default, or any branch you assign. | | **Staging** | `main` by default, or any branch you assign. Staging is enabled per project on the **Hosting** page. | Assign a branch from the **Environments** strip at the top of the **Branches** tab: pick a branch for Development or Staging and click **Deploy**. The strip shows what each tier is serving and since when. If a tier is assigned to a branch that has since been deleted, the strip flags it and offers a one-click **Move back to main**. The **Deploy** button in the top right understands the branch you are on: * On `main` with no assignments, every tier deploys `main` as it always has. * On a branch, Development and Staging offer **Deploy *branch* to Development**, or **Bind Development to *branch* and deploy** if the tier still serves `main` (**Move Development from *other* to *branch* and deploy** if it serves another branch). Hiveku confirms before moving a tier off `main`. * Production offers **Open pull request *branch* into main** (or **Review PR #n** if one is already open). It never deploys a branch directly. Each deploy of a bound tier ships the branch's latest commit, and commits your unsaved branch changes first so what you see is what ships. The change count for that tier counts commits on the branch since its last deploy, plus any unsaved changes. A tier that serves a branch stops following `main`. If a pull request merges and you delete the branch from the post-merge prompt, Hiveku moves the tier back to `main` as part of the delete. Until then, move the tier back to `main` on the **Branches** tab and deploy if you want it to pick up changes from `main`. ## One database per project Files are versioned; data is not. Every branch and every tier reads and writes the same project database, and uploaded assets in the Media library are shared across branches too. On a branch, the Database panel shows the development connection with a banner that reads: "One database for this project. Files on *branch* are versioned; the data you see here is the same on every branch and every tier." This means a migration you run while working on a branch changes the database that production reads. Test schema changes against a copy of your data, or keep them additive until the branch is merged. ## Content and visual editing stay on main The CMS and visual editing work on `main` only. * On a branch, the CMS panel is read-only and shows "Content lives on main. You are working on *branch*. Switch to main to edit content." with a **Switch** button. * Visual edit mode is unavailable on a branch ("Visual editing changes main. Switch to main to use it."). * Per-file **Version History** and checkpoint restore are `main` features. On a branch, use the branch's commit history in the **Branches** tab and **Undo this turn** in the chat. If the project has a CMS, the Environments strip warns you when you assign a branch to a tier: content edits always write to `main`, so they do not appear on that tier until the branch is merged, and a scheduled publish will report success without reaching it. ## Pull requests A pull request proposes merging a branch into `main` (or into another branch). Open one from the selector, from the **Deploy** menu's Production entry while you are on a branch, or from the **Branches** tab. The pull request drawer shows: * Title, source and target, status, and who opened it * A note when `main` has changed since the branch was created, and a note when the branch has uncommitted changes that will be included * The list of changed files; click one for a side-by-side diff ### Strict merge Merging is all or nothing. Hiveku performs a three-way merge against the point where the branch left `main`; if any file conflicts, nothing is merged and the drawer lists the conflicting files: "*n* conflicting files. Nothing was merged. Resolve them on *branch* and try again." To resolve, switch to the branch, open each listed file, bring in the change from `main` by hand, commit, and merge again. A merge into `main` never edits `main` partially, so a half-applied merge cannot reach production. ### After the merge Once merged, Hiveku offers three follow-ups: **Deploy production** (ship the new `main`), **Delete *branch*** (any tier assigned to the branch moves back to `main` first), or **Keep branch**. If you were working on the merged branch, the prompt also offers **Switch to main**. Pull requests can be closed without merging and reopened later. The PR list in the **Branches** tab filters by Open, Merged, and Closed. ## Branch previews Each branch gets its own live preview, separate from the `main` preview. * Switching to a branch starts its preview automatically. A boot card shows progress; most previews are ready in one to two minutes, and the editor waits up to five before offering a **Start preview** retry. * The preview is marked ready only after the branch's files have landed in it, so what you see is the branch, not a starter scaffold. * Saves on the branch sync to its preview the same way saves on `main` sync to the main preview. * A preview that has been idle for an hour is stopped. Switching back to the branch starts it again. You can also stop it yourself with **Stop preview** in the branch menu. * A project can run up to five branch previews at a time. ## From Claude Code and VS Code Agents and editors work on a branch by naming it; nothing "checks out" or switches on the server. ### Claude Code and other MCP agents * The file tools take a `branch` parameter: `project_files_bulk_get`, `project_files_bulk_save`, `project_file_get`, `project_file_save`, `project_file_delete`, `project_test_build`, `preview_http_get`, and `preview_screenshot`. Omit it (or pass `main`) to work on `main`. The two preview tools need a running branch preview; start one with `project_vcs_branch_preview`. `project_files_status` accepts `target: "branch:"` to compare local files against a branch. * `project_vcs_checkout` reads a branch's files; it does not switch anything. Pass `branch` to the file tools to work there. * `project_vcs_branches` lists each branch with `uncommitted` and `working_tree_etag`. Record the etag when you pull and compare before you push to catch edits made elsewhere. * `project_vcs_commit` with a `files` list commits those files. Called with **no files**, it promotes the branch's uncommitted changes into a commit (the response reports `promoted: true`). If there is nothing to commit, it says so instead of creating an empty commit. * `project_vcs_diff_file` returns one file's before-and-after between two branches (`from`, `to`, `path`). For a pull request, `from` is the target and `to` is the source. * Call `project_vcs_env_bindings` before `deploy_site`. The bindings decide what ships: a bound tier deploys its branch (unsaved changes are committed first), production always deploys `main`. `deploy_site` refuses any branch other than `main` for production and refuses a branch that does not match the tier's assignment. * With the [Claude Code plugin](/integrations/claude-code-plugin), `/hiveku:branch` lists, creates, assigns and deletes branches, `/hiveku:pr` opens, reviews and merges pull requests, and `/hiveku:code` and `/hiveku:deploy` follow the same rules. ### VS Code extension * **Hiveku: Switch Branch** changes the branch your local folder tracks. Push and pull then operate on that branch; the status bar shows the current branch. * **Hiveku: Pull Requests** lists open pull requests, opens a per-file diff for review, and merges, closes or reopens them. * **Hiveku: Environments → Branch** assigns a branch to Development or Staging, and the deploy picker labels each tier with its branch ("development - serves branch feat/x", "production - always main"). * **Hiveku: Preview Branch on Fly** starts a branch preview from VS Code, and a companion command in the palette stops it. ## Common questions No. Switching changes what you see in the editor. Production serves main until you merge a pull request and deploy. Development and Staging change only when you assign a branch to them and deploy. Not yet. Content lives on main. Switch to main to edit content; branch-aware content is planned. No. One database per project, shared by every branch and tier. Per-branch databases are planned. They are committed first, under a message naming the deploy, and that commit is what ships. Nothing you saved is left behind. The selector appears for members who can deploy the project. Ask an account admin for the deploy permission. Not directly. Move Development back to main (or to another branch) first. The post-merge prompt does this for you when you choose Delete.