Project
FreeThe Project tool window (⌘1) is the editor's file tree. Here you open a folder as a project, see every file with its git status, create new ones, rename, move by dragging, and start a terminal or Claude right in the folder you need. Several folders can be combined in one window, and you can show any subfolder as a subproject of its own.
What you do here
- The tree: open a project, attach folders, the header bar, what rows show, keyboard
- Subprojects: show a subfolder as a project of its own, in Mission Control too
- New file: create files with the right file type, including Word and Excel
- The menu: everything the right-click offers on files and folders
- Dragging: move, copy, drop into the code area, a terminal, Claude or onto a server
- Multi-select: work on many entries at once
- Clone repository: get a git repository from an address, a local repository or GitHub
Page layout
- A header bar per folder: the project, every attached folder and every subproject has its own bar with name, git branch and buttons. A click on the bar expands or collapses that folder.
- Tree: the files and folders below it, with icons by file type, git colours and, if you like, the time of the last change.
- Handle between two folders: when several folders are expanded, you split the height by dragging.
With no project open the window shows No project open and the button Open folder…. Other ways to a project are ⌘O, the project menu in the title bar, File ▸ Recent projects and the start screen. With WebDonkey the start screen also lists your sites.
Free and Premium
The project tree is entirely free, including subprojects, cloning and creating Word and Excel files. Only the entries that connect a folder to a server (mappings, upload, compare) are Premium, see Mappings and sync.
The tree Free
The project tree shows your project folder with all its subfolders and files. You open files, expand folders, see at a glance what git considers changed, and do almost everything from the keyboard. If you attach more folders, each gets its own tree in the same window.
Where to find it
- ⌘1 shows and hides the Project window. By default it sits at the top left.
- The Project icon in the left stripe does the same.
How to do it
Open a project
- Press ⌘O, or click Open folder… in the empty window.
- Pick the folder in the Finder dialog.
- If a project is already open in this window, the editor asks where the folder should go:
- New window (default): the open project stays where it is, the folder opens in a window of its own.
- This window: the folder replaces the open project. Unsaved files are asked about first.
- Attach: the folder joins this window as one more folder (see below).
- Cancel
If a folder is already open in another window, the editor brings that window to the front instead of opening it twice. Recent projects are under File ▸ Recent projects, in the project menu and on the start screen.
Open a file
A click on a file opens it as a tab, a click on a folder expands or collapses it. From the keyboard both work with ↩. To open a file in a split, use Open to the side in the menu or drag it.
Attach folders
With Attach you add more folders to the same combination, for example a plugin next to the shop. Each folder gets its own header bar with its own tree. The bar of an attached folder has an X (Detach from project). The editor asks first and only removes the folder from the combination; nothing is deleted on disk. In the project menu, Rename combination… gives the whole thing a name of its own.
Close the project
File ▸ Close project asks “Close project …?”. Idle terminals are closed. Programs still running in a terminal keep running and are back when you open the project again.
The header bar
Every folder in the window has a bar. It shows:
- an arrow to expand and collapse. A click anywhere on the bar does the same.
- the folder's name. Hover over it for the full path.
- for a git repository the branch (⎇) with ↓ (commits to pull), ↑ (commits to push) and the number of changed files. ∅ means nothing to do.
- a coloured mark when the folder is mapped to a server (mappings).
The buttons on the main project's bar while it is expanded:
| Button | Effect |
|---|---|
| New file | opens the list of file types, see New file |
| New folder | adds a new row for a folder name |
| Reveal the active file | jumps in the tree to the file of the active tab |
| Collapse all | collapses every folder |
| Hide hidden files / Show hidden files | hides or shows files and folders whose name starts with a dot (.env, .git). They are visible by default. |
| Refresh | reads the tree and the git status again |
Attached folders have Refresh and Detach from project, subprojects Refresh and Remove subproject. To create files there, use the context menu. When the bar gets narrow, it shows the branch as an icon only and moves the buttons into the More actions menu (…). The name always stays readable.
Several folders below each other
When several folders are expanded, they share the window's height. Between two expanded folders there is a handle:
- Drag moves the border. It snaps at ¼, ⅓, ½, ⅔ and ¾. Each folder keeps at least its bar and two rows.
- Double-click splits the two evenly again.
Which folders are collapsed and how tall each one is, the editor remembers per project, across restarts too.
What the rows show
- Icons by file type. A folder that is a git repository itself carries a small branch mark and its own branch badge.
- Git colours on the name: modified and renamed in the accent colour, added to the index green, deleted and conflicts red, untracked files in the warning colour. Folders with changes inside are coloured too.
- Excluded by .gitignore: whatever
.gitignoreexcludes has a grey name and a subtle row background; the tooltip says so. - Hidden files (name starting with a dot) and cut entries are semi transparent.
- Symbolic links are in italics, the tooltip says Symbolic link.
- Mapped folders have a tinted background, the tooltip names the server and target (mappings).
- Last change on the right: for files their last change, for folders the newest change inside (the tooltip names the file). It reads now, minutes, hours, yesterday, a weekday, a date or a year. Changes from the last ten minutes are in the accent colour. Switch it under Settings › Appearance › Last change in the project tree (on by default).
- Run button on files and folders the editor can run, see Launchers.
Keyboard
Click into the tree once, then these keys apply:
| Key | Effect |
|---|---|
| ↑ ↓, Page Up Page Down, Home End | move; with ⇧ extend the selection |
| → | expand a folder; on an open folder go to its first entry |
| ← | collapse a folder, otherwise go to the parent folder |
| ↩ | open a file, expand or collapse a folder |
| Space | open a file |
| F2 or ⇧F6 | rename |
| ⌘D | duplicate |
| ⌘⌫ | move to Trash |
| ⌘N | new file with a file type |
| ⌘C, ⌘X, ⌘V | copy, cut, paste |
| ⌥⌘C / ⇧⌥⌘C | copy path / relative path |
| ⌥⌘R | reveal in Finder |
| ⇧F10 or the context menu key | open the context menu |
| Letters | jump to the next entry starting with them |
| Esc | cancels a pending “cut” |
If you copy entries with ⌘C and paste them into a terminal or a file, the paths arrive as text, one per line.
What happens in the background
- The editor watches the folders. Whatever changes on disk shows up in the tree by itself, in attached folders too. If an expanded folder was missing for a moment, it reloads as soon as it is back.
- Deleting moves to the macOS Trash. You can restore everything from there.
- The editor keeps the project's state (open folders, tabs, attached folders, subprojects, heights) in the project at
.webdonkey-editor/workspace.json. That folder brings its own.gitignore, which keeps everything in it out of git.
Troubleshooting
| What you see | Why | What to do |
|---|---|---|
| This folder no longer exists. in the tree | The folder was deleted or moved outside the editor. | Refresh in the header bar, or open the folder again |
| No permission for this location. | macOS does not let the editor read the folder. | check the folder's permissions in the Finder (Get Info, Sharing & Permissions) |
| An item with this name already exists. | when renaming or creating | pick another name |
Files like .env are missing |
Hidden files are hidden. | Show hidden files in the header bar |
See also
Subprojects Free
A subproject shows a subfolder of your project once more as a project of its own, with its own header bar right under the main project. That helps when you mostly work in one part of a large project, for example a plugin under custom/plugins/ of a shop. It is the very same folder as in the main tree: no copy and no link on disk. Whatever you change there applies in both places at once.
Where to find it
Right-click a folder in the project tree ▸ Show as subproject.
How to do it
- In the project tree, expand the folder that holds the subfolder you want.
- Right-click the subfolder ▸ Show as subproject.
- Right under the main project's header bar an indented bar appears with the subfolder's name and a small arrow (↳). The arrow's tooltip says Subproject of ….
- Expand the bar. Below it is the subfolder's tree, with the same gestures as the main tree.
Rename
A subproject is named after its folder at first. Right-click its header bar (or the folder in the main tree) ▸ Rename subproject… gives it a name of its own. Leave the field Name (empty = folder name) empty to go back to the folder's name. The folder on disk keeps its name.
Remove
The X on the subproject's header bar or Remove subproject in the context menu takes the bar away again. The folder stays in the main tree, nothing changes on disk.
Rules
- One level: a subproject lies inside one of the window's folders, so in the project or in an attached folder. There is no subproject inside a subproject, and a folder that already holds a subproject cannot become one.
- The project itself and attached folders already have bars of their own, so the entry is missing for them.
- A subproject of an attached folder sits under that folder's bar.
- If you rename the folder or move it along with the project, it stays a subproject.
In Mission Control
Every subproject is a project of its own in Mission Control, with its own sessions. A Claude session started without a chosen project belongs to the project whose folder it starts in, and a subproject comes before its main project. A project chosen in the New session dialog always wins.
What happens in the background
The editor keeps the subprojects with the project's state in .webdonkey-editor/workspace.json, with paths relative to the project. They survive a restart and apply to this project only.
Troubleshooting
| What you see | Why | What to do |
|---|---|---|
| Show as subproject is missing from the menu | The folder is the project itself, an attached folder, lies inside a subproject or holds one. Or you selected several entries. | select exactly one suitable folder, remove a subproject in the way first |
| The subproject's tree says This folder no longer exists. | The folder was deleted or moved outside the editor. | remove the subproject and create it again at the new place |
See also
New file Free
⌘N in the project tree creates a new file and offers a list of file types. Pick a type and the extension is fixed already, and the file starts with what practically every file of that type needs, such as <?php or the skeleton of an HTML page. You only type the name.
Where to find it
- ⌘N while the project tree has the focus. The file goes into the selected folder or next to the selected file.
- The New file button in the project's header bar.
- Right-click a folder, a file or the empty area ▸ New ▸.
File ▸ New file and File ▸ New folder in the menu bar add an empty row in the project tree right away, without the list of types. There you type name and extension freely.
How to do it
- Select the folder the file should go into (or a file in it) in the tree and press ⌘N.
- Empty file is at the very top and already highlighted, ↩ takes it. With ⌘N and New ▸, New folder follows.
- Below are In this project (the types most common in the folder and the project, five at most) and Recently used (your last types, three at most).
- Then come the groups Web, Scripts, Programming languages, Data and configuration and Documents as submenus.
- Or just start typing: Type to filter finds types by name or extension (
php,.twig,yaml,excel). The best match is on top, ↩ takes it. - After you pick a type, a new row appears in the tree. The extension stands in grey behind the field. Type the name and confirm with ↩. Esc cancels.
The file opens as a tab right away; for types with a template the cursor sits where you go on writing.
The file types
| Group | Types |
|---|---|
| Web | HTML, CSS, SCSS, JavaScript, TypeScript, TSX, JSX, Vue, Twig (.html.twig), PHP |
| Scripts | Shell script, Python, Ruby |
| Programming languages | Go, Rust, Java, Kotlin, Swift, C, C++, C# |
| Data and configuration | JSON, YAML (.yaml and .yml), TOML, XML, SQL, CSV, .env |
| Documents | Markdown, Text file, Word document, Excel workbook |
Types that start with content: HTML (skeleton with the language of the interface), PHP (<?php), Shell script (#!/usr/bin/env bash), Python (#!/usr/bin/env python3), JSON ({}) and XML (UTF-8 declaration). All others start empty. Word document and Excel workbook are an empty, valid document; the workbook has a first sheet.
How the name becomes a file name
- Only a name: the type's extension is added (
CheckoutbecomesCheckout.php). - The start of the type's own extension typed: the rest is completed (
index.htmlas Twig becomesindex.html.twig). - Another extension from the list typed: it wins, and the file starts empty (
Foo.htmlwith the PHP type becomes an emptyFoo.html). - A path like
src/Service/Foo: missing folders are created along the way and shown in the tree. - For the
.envtype the whole name is in the field already, and you can type on behind it (.env.local).
Free and Premium
Every file type is free, Word document and Excel workbook included. You edit such files in the editor with the viewers.
Troubleshooting
| What you see | Why | What to do |
|---|---|---|
| An item with this name already exists. under the field | The name is taken in that folder. | type another name, the field stays open |
| This name is not allowed | The name has . or .. as a part. |
change the name |
| ⌘N does nothing | The focus is not in the project tree. | click into the tree once, or use the New file button |
See also
Dragging Free
In the project tree you grab files and folders with the mouse and drop them somewhere else: into another folder, the code area, a terminal, Claude, onto a server or out of the editor into the Finder. A drag only starts once you move the mouse a few pixels. A normal click stays a click.
How to do it
Move within the tree
- Grab a file, a folder or a multi-selection and drag it onto a folder. The target folder is highlighted.
- Rest for a moment (about three quarters of a second) over a collapsed folder and it expands by itself.
- Let go. The editor asks Move to “Folder”? and shows what goes where. Confirm with Move.
So an accidental drag never moves anything unnoticed. Open tabs follow the moved files, expanded folders stay expanded at their new place.
Copy within the tree
Hold ⌥ when you let go. The editor then copies without asking, and the original stays where it is.
When the name already exists
If the target already holds an entry with the same name, the editor asks Name already exists:
- Skip: this entry stays where it is.
- Keep both (default): the new entry gets a number.
- Replace: the existing entry goes to the Trash. For folders that means the old folder is swapped as a whole; the contents are not merged. If the dragged entry lies inside the folder it would replace, Replace is not offered.
If several dragged entries share a name, the question names them. All of them are moved, from the second on with a number (“name 2”). The editor cannot move a folder into itself.
Dragging onto other targets
| Drop onto | Effect |
|---|---|
| Code area | opens the files as tabs. At the edge of an editor group the editor splits first and opens them in the new half. |
| Terminal | inserts the paths at the prompt. If Claude Code is running there, they arrive as mentions in Claude's input. |
| The input field of a session in Mission Control | attaches the files to the next message |
| A folder on a server (Remote window) | uploads the entries there (Premium), see Transfers |
| Finder, Mail, a browser upload field | Dragged out of the editor window, macOS hands the files on as normal files (as a copy). |
From the Finder into the editor
- Onto the project tree: the editor copies the files into the folder under the pointer. If the name exists, the same question as above appears.
- Onto the code area: the files open in that editor group.
- Onto a terminal: the paths land at the prompt.
Rows from a server's tree dropped onto the project tree are downloaded into the target folder.
Tool windows and tabs can be dragged to other places as well, see Places and window types.
Troubleshooting
| What you see | Why | What to do |
|---|---|---|
| A folder cannot be moved into itself. | The target lies inside the dragged folder. | pick another target |
| Not every entry arrived | A name was taken at the target in the meantime. | check the target and drag the rest again |
| Nothing happens when dropping onto its own folder | Moving a file into its own folder changes nothing. | copy with ⌥ or pick another target |
See also
Multi-select Free
In the project tree you select several files and folders at once and work on them together: move, copy, delete, copy paths, send them to Claude or run git actions.
How to do it
- Click the first entry.
- Extend the selection:
- ⌘-click adds an entry or takes it out again.
- ⇧-click selects everything from the last selected entry to the clicked one.
- ⇧↑ / ⇧↓, ⇧Page Up / ⇧Page Down and ⇧Home / ⇧End extend it from the keyboard.
- Right-click one of the selected entries to open the menu for all of them, or use a shortcut directly.
A click without a modifier selects a single entry again.
What works with several entries
| Action | Note |
|---|---|
| Cut (⌘X), Copy (⌘C), Paste (⌘V) | Cut entries are semi transparent until you paste. Esc cancels the cut. |
| Move to Trash (⌘⌫) | The question names the items and counts them. |
| Moving by dragging | The whole group moves together. Equal names get a number from the second on (“name 2”). |
| Copy path (⌥⌘C), Copy relative path (⇧⌥⌘C) | one path per line |
| Send to Claude | all selected entries as mentions |
| Git ▸ | acts on the selected files, for example Restore (discard changes)… or Commit… with these files preselected |
Rename and Duplicate only work with exactly one entry. With several selected they are greyed out in the menu.
⌘-click, ⇧-click and ⇧↑ / ⇧↓ select several entries in a server's tree too, see Files on the server.
See also
Clone repository Free
Clone repository… brings a git repository onto your Mac and then opens it as a project. The source is an address, a repository that already lives on your Mac, or one of your repositories on GitHub. You pick branch, tag or commit, target folder and folder name. The editor never overwrites an existing folder and never sees a password or token.
Where to find it
- File ▸ Clone repository…
- in the project menu of the title bar
- on the start screen
- in the command palette (⌘K): Clone repository…
- right-click a folder in the project tree that is not inside a repository ▸ Clone repository…. That folder is then set as the target.
How to do it
From an address
- Open Clone repository…. The address field at the very top has the focus.
- Paste a link (
https://…,git@…,ssh://…) or writeowner/repofor short. - Check Target folder and Folder name below.
- Press ↩ or click Clone.
From a local repository
- Switch to the Local tab. The editor looks for repositories in the folders of your projects (the open project, attached folders, recent projects, sites from WebDonkey), never in your whole home folder.
- Pick a repository. Several worktrees of the same repository are one entry with “n worktrees”. Filter repositories narrows the list.
- Under Branches, Tags or Commits, pick the state, or leave Current state.
- Choose Worktree or Copy (see below).
- Click Create worktree or Clone.
From GitHub
- Switch to the GitHub tab. The editor asks the GitHub CLI
ghwho is logged in. - Under your account you find My repositories and your organisations. Pick one of them.
- The list shows the repositories, newest first, with fork, archived and the time of the last push. Filter repositories searches the loaded list. If GitHub has more, ↩ searches there (Search GitHub for “…”). Load more fetches the next page.
- Pick a repository, then branch, tag or commit if needed. The Default branch is marked.
- Click Clone.
If gh holds several accounts, an inactive one appears with not the active account in gh. Switch makes it the active account of gh, for gh in the terminal as well. An account with login expired needs a new login in the terminal.
Fields and options
| Field | Meaning |
|---|---|
| Source | line above the target: what is cloned, with branch, tag or commit. Without a choice it reads Enter an address or pick a repository. |
| Branch, Tag, Commit | the state that is checked out. A tag or a single commit is checked out without a branch (detached HEAD); the editor tells you to create a branch there first. |
| Worktree | local repositories only: a folder of its own on the same repository. History and branches are shared, the main checkout stays untouched. Git allows a branch in one worktree only, so a worktree needs another branch, a tag or a commit than the one already checked out. |
| Copy | local repositories only: an independent repository, cloned from the local folder. A copy holds local branches only. |
| Target folder | where the new folder is created. Choose… opens the Finder dialog. Default: the folder from the context menu, else the one chosen last, else the folder most of your projects live in, else your home folder. |
| Folder name | proposal: the repository's name, with branch, tag or short commit added when you picked one (theme-feature-cart). Below it you read what will happen: Will be created: … or Uses the empty folder …. |
When something is not possible, the option is greyed out and a line below says why.
What happens in the background
- While cloning, the output of
git(orgh) runs along visibly. Cancel stops the run and removes the folder it created. - When cloning is done, the editor says Cloned: … and opens the folder as a project, with the usual question about New window, This window or Attach.
- The editor reads the GitHub lists through
gh, each one only when you open it.ghand the keychain keep the login. The editor stores no credentials. - If the target exists and is not empty, the editor writes nothing into it.
Troubleshooting
| What you see | What to do |
|---|---|
| The GitHub CLI (gh) is not installed | Install in the terminal (installs gh with Homebrew) or Open cli.github.com, then Check again. Cloning from an address and from local repositories works without gh. |
| gh is not logged in to GitHub | Log in in the terminal: gh shows a one-time code and opens the browser. The clone window steps aside meanwhile. Then Back to “Clone repository”. |
| git needs an answer (password, passphrase, unknown host key) | Run in terminal runs the very same command visibly in a terminal, where you answer the prompt. |
| The target exists and is not empty | choose another Folder name; nothing is overwritten |
| The organisation requires single sign-on. | run gh auth refresh in a terminal and authorise the organisation |
| GitHub's request limit is reached. | wait a few minutes |
| Not found (or no access) | check the spelling, use Switch to make an account with access the active one |
| git is not installed. | install git on the Mac, then open the window again |