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:
.