A visual Git worktree tutorial for Flame IDE. Create a branch and checkout, choose what to copy, open the worktree, review its changes, and return to your task.
Create the second checkout from Flame's New worktree form. The screenshots in this guide come from the real IDE with sample project data. Select the image to enlarge.
WHY IT HELPS
Keep your feature open. Give the urgent fix its own space.
You are working on cohort insights when a login bug needs attention. Instead of changing the branch under your open files, create a worktree for fix/login-timeout. Flame gives that task a sibling checkout you can open as a project. The original feature keeps its own files and changes. This walkthrough uses Flame's Git panel, New worktree form, and checkout controls from start to finish.
What you will create
A branch named fix/login-timeout and a sibling folder named flame-starter-login-fix, based on your repository's main branch. Use names and a starting ref that fit your project.
What stays where it is
Your current feature checkout keeps its branch and uncommitted work. Leave Bring all uncommitted changes off when this second task should start from the chosen base.
Before you begin
Open a Git project with at least one commit. Know which branch or commit the fix should start from, and choose a new branch and an unused sibling folder name.
HOW TO USE IT
Follow the worktree workflow in Flame.
Open Git, then choose Worktrees
Select the repository in Flame and open Git from the left activity bar. Choose the Worktrees tab. This list shows the main checkout and any linked checkouts, with their branch and folder information. Expand a row to inspect the checkout before deciding where the new task belongs.
Git → Worktrees. Each row represents a working directory, not just a branch name.
Choose New worktree and fill in the task
Click New worktree at the bottom of the Git panel. Keep New branch selected. Enter fix/login-timeout in Branch, main in Create from, and flame-starter-login-fix in Folder name. Create from selects the commit the new branch starts at; Folder name selects the separate checkout directory. Wait for Ready to create before continuing.
The actual New worktree form. The branch, starting ref, and folder are separate choices.
Decide what the new checkout should contain
For this independent fix, leave Bring all uncommitted changes unchecked. Enabling it copies staged, unstaged, and untracked files into the new checkout as unstaged changes, while keeping them in the original checkout too. It is useful when moving an existing change into a new worktree, but it would mix unfinished feature work into this example. Enable Open the worktree as a new project after creating, then choose Create worktree.
Check the active project and prepare its runtime
When Flame opens the worktree, verify the project and branch before editing. If you left the open-after option off, return to Worktrees and use Open on the new row. Flame applies the configured worktree initialization and copy rules; check their outcome and install any remaining dependencies. Use a different port or development database when the first checkout's server is still running.
Implement the fix, then review the right diff
Make the login fix in the worktree and run its relevant tests. Inspect Changes in that checkout, commit only the intended fix, and review it through your team's normal pull-request or integration process. A separate checkout helps keep tasks apart, but both branches can still change the same lines and create a merge conflict later.
Return to the feature and clean up deliberately
Open the original project to return to the feature you left in progress. When the fix is integrated or no longer needed, stop its servers and preserve any useful local changes. In Git → Worktrees, expand the task checkout and use its remove action. Review the confirmation and any dirty-state or lock warning. Removing a checkout and deleting its branch are separate decisions.
REQUIREMENTS & LIMITS
Know what the tool depends on.
Choose your repository's actual base ref. A local main branch can be behind its remote; update or select the intended starting commit before creating the worktree.
Git normally prevents the same branch being checked out in multiple worktrees. For an independent task, use a new branch instead of forcing the same branch into two directories.
Worktrees separate working files. Ports, databases, caches, credentials, and external services can still be shared. A worktree does not provide a security sandbox.
A dirty or locked checkout needs investigation before removal. Preserve work and stop the processes using it rather than forcing past an unexplained warning.
FAQ
Git Worktree Tutorial: common questions
A branch identifies a line of Git history. A worktree is a separate working directory where a branch can be checked out. Flame can open that directory as a project, with files and terminals scoped to that checkout.
Leaving Bring all uncommitted changes off keeps the new checkout based on the selected ref. Turning it on copies staged, unstaged, and untracked files into the new checkout as unstaged changes, while retaining them in the original checkout.
Use the branch or commit the new task should start from, such as your project's main or release branch. Do not assume the current checkout or a local main branch already matches the latest remote state.
Yes. Enable Open the worktree as a new project after creating in the form. You can also open an existing linked checkout through its row in Git → Worktrees.
The checkout may still need dependencies, environment files, or initialization. Review Flame's worktree initialization and copy settings, inspect the resulting terminal output, and check for shared ports or services.
The checkout and branch have separate lifecycles. Preserve useful changes and review the removal confirmation. Decide separately whether the branch is still needed after integration.