Projects and workbenches

Adding, creating, cloning and importing projects

Add projects by creating a folder, cloning a Git URL, opening an existing folder or importing repositories, and link an IDE and choose how files open for a new project.

On this page

A project is a folder on your computer. Orkestra gives four ways to add one: create a new folder, clone a Git repository from a URL, open a folder that already exists, or scan a folder and import many repositories at once. The Project operations panel in the status bar lists these jobs while they run and after they end. To switch, edit, group or remove projects, see Projects.

Where to find it

  • Project switcher in the top bar. It shows the current project name, or No project. Click it to open the project list.
    • The folder-plus button next to the search box (tooltip "Add project") opens the Add project dialog. This dialog lets you choose one of the four ways.
    • Open… in the list footer opens Open existing folder directly.
    • New project in the list footer opens Create project directly.
    • When the list is empty, four buttons open their dialog directly: Create new, Clone from URL, Open existing folder, Scan a folder.
  • The Add project button of the Getting started checklist opens the Add project dialog. The last step of the first-run setup wizard offers the same four ways and opens the matching dialog. See Getting started.
  • Project operations: a button with a clock icon at the right end of the status bar. See Window layout.

What you see

  • All dialogs — a title at the top left and a close button at the top right (tooltip "Close dialog"). Buttons are at the bottom right. Escape or a click outside the dialog also closes it, unless the dialog is busy.
  • Add project dialog (footer: Cancel):
    • Create new — note "Empty git repository or plain folder".
    • Clone from URL — note "git clone into a new project folder".
    • Open existing folder — note "Add a folder or repository already on disk".
    • Scan a folder for repositories — note "Find and import many repositories at once".
  • Create project dialog:
    • Name — the folder name. The hint in the empty field is "my-project".
    • IDE — a native list of detected and chosen editors, plus Rescan editors and Choose editor…. The hint says a JetBrains IDE can create .idea/.
    • File opening — three choices: Orkestra, Default application and Project IDE. They say what a double-click or Enter on a file in the Files panel does in this project; Orkestra (opening in an Orkestra window) is checked at first. The hint says "When no rule matches. Rules live in Edit project." While IDE says None, Project IDE is grey and the line says "No project IDE — choose one above"; choose an IDE and it works at once. If Project IDE was checked and you set IDE back to None, Orkestra is checked again.
    • Kind — two buttons: Git repository and Plain folder.
    • Parent folder — a path field with a folder button (see "Path field" below).
    • A preview line — the full target, for example ~/Orkestra/projects/my-project · git init. · git init shows for Git repository.
    • Remember as my default project location — a check box.
    • Cancel, and Create (it reads Creating… while it works and Retry after a failure). Open existing instead appears only after a conflict.
  • Clone from URL dialog:
    • Source — the repository address. The hint is "https://example.com/team/project.git".
    • Parent folder — a path field with a folder button.
    • A preview line — the target folder and "from URL".
    • Cancel and Clone.
    • While it runs: the line "address → target folder", a progress bar with the Git stage and a percent, the note "Closing hides this — the clone still runs", and the buttons Cancel clone and Hide.
  • Open existing folder dialog:
    • Path — a path field with a folder button.
    • IDE — the same editor list, Rescan editors, Choose editor… and .idea/ hint as Create project.
    • Open as — three buttons: Auto, Git, Folder.
    • Cancel and Add project. The main button can also read Inspecting…, Add as folder, Add main checkout or Switch to it. Clone instead can appear (see States and messages).
  • Scan for repositories dialog:
    • Root folder — a path field with a folder button.
    • Limits — a button that opens three fields: Max depth, Max repositories, Timeout (s). The text beside it always reads "depth 4 · 200 repos · 30 s". These are the start values.
    • Cancel and Scan. While the scan runs: a moving bar, a status line, and Stop.
    • Results view, titled "Scan results — <folder>": warning banners, a line "N repositories found · M selected", a check list (each row shows the path under the root and a depth number with the tooltip "depth"), Back, and Review import (N).
  • Import N repositories dialog (review):
    • Import as — two buttons: Separate projects and One group.
    • Group name — shows only for One group.
    • Selected repositories — a list with each name and path.
    • Back and Import N.
  • Path field (in every dialog above) — a text box and a folder button. The button has the tooltip "Choose folder…" and opens the system folder picker.
  • Project operations panel (opens upward from the status bar). Its header reads "Project operations" and has a close button (tooltip "close Project operations"). Each row shows an icon, a title (Clone, Create, Open existing, Scan or Import plus the project name), a state badge, a detail line, and buttons.

How to

Create a new project

  1. Click the project switcher in the top bar.
  2. Click New project in the list footer.
  3. Type a name in Name.
  4. Optional: select an editor in IDE, or leave None.
  5. Optional: under File opening, choose where files open by default: Orkestra, Default application or Project IDE.
  6. Click Git repository or Plain folder under Kind.
  7. Check Parent folder. To change it, type a path or click the folder button (tooltip "Choose folder…").
  8. Optional: check Remember as my default project location.
  9. Click Create.

Result: The dialog closes. The new project is in the project list and becomes the current project. Its IDE link and its File opening default are saved with the project. To add rules for single extensions later, use Edit project. See Projects and the project switcher.

Clone a project from a Git URL

  1. Click the project switcher in the top bar.
  2. Click the folder-plus button (tooltip "Add project").
  3. Click Clone from URL.
  4. Type or paste the address in Source.
  5. Check Parent folder. To change it, type a path or click the folder button.
  6. Click Clone.

Result: A progress bar runs. When the clone ends, the title changes to "Clone finished". The project is already added and is the current project. Click Open project or Close to leave the dialog. If the clone fails, the title is "Clone failed". Click Edit & retry to show the form again.

Hide a running clone

  1. While the clone runs, click Hide.

Result: The dialog closes. The clone continues. When it ends, Orkestra adds the project.

Cancel a running clone

  1. While the clone runs, click Cancel clone.

Result: The dialog shows "Cancelling — removing the partial folder…". Orkestra removes the partial folder. Then the form shows again with your Source and Parent folder.

Open an existing folder

  1. Click the project switcher in the top bar.
  2. Click Open… in the list footer.
  3. Type a path in Path, or click the folder button (tooltip "Choose folder…") and pick a folder.
  4. Optional: select an editor in IDE, or leave None.
  5. Under Open as, keep Auto, or click Git or Folder.
  6. Click Add project.

Result: The dialog closes. A newly added project is in the project list and becomes current; the IDE link is saved with it. If the folder is already registered, Switch to it does not change its link.

Add a folder that Git cannot inspect

  1. In the Open existing folder dialog, click Add project. A warning says "git couldn't inspect this folder".
  2. Check that Open as now shows Folder.
  3. Click Add as folder.

Result: Orkestra adds the folder as a plain folder.

Scan a folder and import many repositories

  1. Click the project switcher in the top bar.
  2. Click the folder-plus button (tooltip "Add project").
  3. Click Scan a folder for repositories.
  4. Check Root folder. To change it, type a path or click the folder button.
  5. Optional: click Limits to change Max depth, Max repositories or Timeout (s).
  6. Click Scan.
  7. Clear the check box of each repository that you do not want. All start checked.
  8. Click Review import (N).
  9. Under Import as, click Separate projects or One group.
  10. For One group, type a name in Group name.
  11. Click Import N.
  12. Optional: if some imports failed, click Retry failed only.
  13. Click Done.

Result: The summary reads "N added · M already known · K failed". Each repository has a tag, added or failed. After Done, the scan results show again. Click the close button (tooltip "Close dialog") to leave.

Stop a scan

  1. While the dialog is titled "Scanning <folder>", click Stop.

Result: The scan ends. The dialog shows the setup form again.

Open the Project operations panel

  1. Click the clock button at the right end of the status bar (name Project operations).

Result: The panel opens upward. Click the same button, press Escape, or click the close button (tooltip "close Project operations") to close it.

Cancel a running operation

  1. Open the Project operations panel.
  2. Click Cancel on a row that shows RUNNING or QUEUED.

Result: The badge changes to CANCELLING, then to CANCELLED. Click Dismiss to remove the row.

Retry a failed operation

  1. Open the Project operations panel.
  2. Click Retry on a row that shows FAILED.

Result: A new row starts with the same request. The failed row stays in the list.

Add or discard a folder that is ready but not added

  1. Open the Project operations panel.
  2. On a SUCCEEDED row with the note "The folder is ready but the project wasn't registered", click Add it or Discard.

Result: Add it adds the project to the project list. Discard removes the row. The folder stays on disk.

Dismiss a finished operation

  1. Open the Project operations panel.
  2. Click Dismiss on a row that shows SUCCEEDED or CANCELLED.

Result: The row leaves the list.

States and messages

  • Add project checks whether Git is available. While the check runs, Clone from URL is disabled. If Git is missing, cloning is unavailable and Create project defaults to Plain folder; the Git check warning appears at the top if it could not complete.
  • In Create project, names allow letters, digits, ., - and _, with no spaces. Choose a parent folder and enter a full path. Git repository creation also requires user.name and user.email. If the target already exists and is nonempty, Create stays disabled; use Open existing instead or choose another name. Permission errors mean you need a writable parent folder.
  • A clone can be QUEUED while another project operation finishes. Cancel clone removes a partial folder; Hide closes the dialog while the clone continues. A failed clone reports the Git reason and whether cleanup left files behind. Supported sources are HTTPS, SSH, file URLs and absolute local paths; authentication failures require checking access or your SSH setup. Error messages redact credentials. An existing nonempty destination is never overwritten.
  • In Open existing folder, use an absolute readable path. A bare repository offers Clone instead. If Git cannot inspect a folder, switch Open as to Folder and click Add as folder. Choosing Git for a non-repository is rejected. A linked worktree opens its main checkout; an already registered project offers Switch to it rather than adding a duplicate.
  • Scan for repositories reports unreadable folders and may return partial results after reaching a limit or timing out. Max depth accepts 1–8, Max repositories up to 500, and Timeout (s) 0.5–30 seconds. If no repositories appear, choose another root or raise the depth. A scan result that has expired must be scanned again before import.
  • Import N repositories requires a group name when One group is selected. Candidates outside the scanned folder are skipped; failed rows show the reason. Review the counts for added, already known and failed repositories, then retry failed rows if needed.
  • In Project operations, the clock count includes QUEUED, RUNNING and CANCELLING jobs. Rows may also end as SUCCEEDED, FAILED or CANCELLED. A successful folder that was not registered offers Add it and Discard; discarding forgets the row but leaves the folder on disk. Failed rows can be retried. A failure may leave partial files if cleanup could not finish; cancelled operations leave other files unchanged, and timed-out operations should be checked before retrying.

Limits and tips

  • Default location. Create project and Clone from URL start Parent folder with your default project location. If none is set, they use ~/Orkestra/projects. Scan for repositories always starts at ~/Orkestra/projects. Remember as my default project location saves the parent folder when you click Create; it starts checked when a default exists. To change the default, go to Settings → Appearance & Behavior → Appearance → Projects → Default project location. See Settings: the window, appearance, terminal, workbench and notifications.
  • Path field. Type a full path. A relative path is rejected. When you leave the field, Orkestra trims spaces at the ends. If the folder picker cannot open, a red message shows.
  • Create. If the parent folder does not exist, Orkestra creates it. Create and Clone from URL never write into a folder that is not empty. Git repository runs git init and makes an empty first commit with the message "Initial commit".
  • Clone sources. Orkestra accepts an HTTPS address, an SSH address, a file address, an address such as user@host:path, or an absolute local path. Other address types, such as plain http, are refused. The clone runs without prompts and uses the Git credentials and SSH agent already set up on this computer. Orkestra removes passwords and tokens from messages.
  • File opening. Only Create project has this choice, and only the default; rules for extensions live in Edit project. Open existing folder (the Add project way) has no File opening choice: an added project starts with Orkestra and you can change it in Edit project. In Create project, Enter in Name or on the File opening choice does the same as the Create button when it is enabled. The Tab key stops once on File opening; use the Left and Right arrow keys to change it. The round close button at the top right of the dialogs is skipped by Tab: use Escape or Cancel.
  • IDE link. The selected IDE is saved when Create succeeds or a new project is added. Opening a folder that is already registered does not change that project's IDE link. Choose editor… saves the chosen path to the global list immediately, even if the dialog is later cancelled.
  • Open existing. A sub-folder of a repository opens as the repository root. A linked worktree opens as its main checkout. The project name is the folder name. A folder that is already in the list is not added twice. Auto adds a plain folder if the path is not a repository or if Git is missing. Folder skips the Git check.
  • Scan. The scan finds Git repositories only. It skips common dependency and build folders (for example node_modules, dist, build, vendor) and symbolic links. Stop ends the scan and drops its results. Cancel while the scan runs only closes the dialog; the scan is not stopped. Scan results expire after about 30 minutes.
  • One group. Orkestra makes one top-level group named by Group name. The start value is the name of the scanned folder. A sub-folder gets its own sub-group when it holds two or more imported repositories directly, or one directly and more deeper inside. Projects that are already in the list stay where they are. Separate projects adds the projects at the top level, with no group. After an import, Orkestra switches to the last project in the list.
  • The Create project, Clone from URL and Open existing folder dialogs have no Back button. To use another way, close the dialog and open Add project again.
  • Operation rows do not leave the panel by themselves. A FAILED row has only Retry; it has no Dismiss button. Jobs that a connected agent starts also show in this panel.
  • A busy Create project, Open existing folder or Scan for repositories dialog cannot be closed with Escape or the close button. A running clone can be hidden.