Sublime Forum

How The Hell Do Projects Get Created & Kept Separate?


The ST project creation is greatly confused by the different role of a workspace in ST compared to how it works in other IDEs.

In other IDEs, a workspace is usually just one big container folder for all project folders plus the user-configuration files needed for the IDE.

Could whoever designed the ST Project Management sub-system please explain the process (rather than the system design) to be followed by a user when making a new project ?

I ask as I am just running into one problem after another trying to surmise, in the absence of clear instructions from the documentation, how to do it for myself.
I thought I had it going right but found that after quick-switching to another project, the old projects file explorer remained in place.
So I cleared all existing projects and started to try creating all current projects anew. But now when I even open ST I get this message:
Unable to read ~/Desktop/Project A Webfiles/index.sublime-project …

I don’t care if this makes me look the dumbest dog in the farm - but I think that many other ST users have had, or to some degree still have, trouble with the project process on this code editor.



Projects in Sublime capture the state of individual windows and allow you to recall it at will; the two parts of this are Project files and Workspace files, but ignore that for the moment.

The first step in creating a project is to have a window for it; this could be an empty window that you’re using to start project creation from scratch, OR it could be an existing window you’re working in that you decide you want to use to represent a project.

So, you want one of the following

  • Create a new empty window with File > New Window
  • Create a new window with a specific folder open inside of it by using File > Open Folder
  • Add folders to any existing window by dragging and dropping them from your file manager or using Project > Add Folder from the menu
  • Projects capture the state of a window; folders are not required. Just want to work with a collection of files? Open them up by any means you like, either into an existing windowor into a new one.

So, now you have a window that has something useful in it and you want to be able to easily recall it back at any point. To do that, you need to do one of the following:

  • Project > Save Project As... will prompt you for a place to store a sublime-project file
  • Project > Save Workspace As... will prompt you for a place to store a sublime-workspace file

In both cases, choose whatever location you want; one of the folders you’re working inside of, some location you set up to store all of your sublime-project and sublime-workspace files, your desktop, etc.

What’s the difference between the two?

A sublime-project file stores the list of folders that are open and allows you to have settings and build systems that apply only to the window in which the project is opened.

A sublime-workspace file stores the state of one specific window; the files that are open, the layout, the position in each file that’s open, the text that’s selected, the find history, unsaved changes, and so on. With such a file you can instantly recall the contents of the workspace back to the exact state it was in when the workspace was closed.

Every project always has at least one sublime-workspace file associated with it; when you save a new project, you get a new sublime-workspace automatically. The workspace uses the same name as the project and will stored in the same location as you store the project.

The instructions above say that you can save a project OR a workspace. Why? Because it is possible to:

  • Never use a sublime-project file at all, just sublime-workspace files. In that case, you can’t apply project specific settings and you can’t make project specific build systems, but you can easily recall the state of a window at any point.

  • Have multiple sublime-workspace files associated with the same project if you want.

The workspace file is where the state of the window is stored, and when working with a project there’s always one. Perhaps you are a web developer and you focus sometimes on content (HTML files) and sometimes on Style (CSS) files, and for each you have different sets of files open or different window layouts, or both. In such a case, you could use two workspaces associated with the same project and easily swap between the two.

All else being equal, I would guess that the vast majority of people are just saving a single sublime-project file and getting the one workspace.

Despite the name, Quick Switch Project shows both sublime-project and sublime-workspace files; you can easily swap the contents of the current window with any of the displayed item, whichever way you go (hence why you can have multiple workspaces on the same project).

If you’re using just sublime-workspace files, that would be expected; multiple workspaces can associate with the same project (and give you the ability to have different layouts) ; always start a new project from either a new window or by opening an appropriate folder in a new window first.

If you’re on MacOS, you may also run afoul of the notion that on that operating system it’s possible for an application that creates multiple windows to have them all gathered together into a single window with extra tabs along the top. This is a MacOS specific thing, and in that case each upper tab represents a window.

You may also find this useful as a visual walk through of all of this:



The error I made was when copying an entire web project into a renamed folder in order to use the first project as a template for a load of content and styling being used in the second one.
The first project had its sublime-workspace folder with the root folder and I neglected to remove it.

Henceforth I’m starting each new project with a new clear window, add the project folder to it and save the project and associated workspace inside the project folder.

One thing not figured yet is this index.sublime-workspace option with the Quick Switch Project menu - see attached screenshot. When I select this option it doesn’t go anywhere, it just stays on the current project whatever that is.



That can happen if there was a project/workspace that used to exist but no longer does; it will persist in the list of known items unless manually cleared from the list. Otherwise if you had projects on say a file share that’s not currently connected (for example because you’re out of office) Sublime removing it would make you unhappy when you got back to the office and your project wasn’t easily openable.

If you’re using ST4, you can use Project > Open Recent > Remove Deleted to get Sublime to remove all items that represent files that no longer exist (but be wary of the situation above, if it happens to apply to you).



Old deleted project cleared. All well now.

Much obliged, :cowboy_hat_face:.

1 Like


I would like to add that the ProjectManager package really took a lot of the pain out of the process for me, as I don’t need to think at all about where my workspace files are being saved