Positron projects

Overview

This unit discusses the concepts of projects and how they are implemented in Positron.

Goals

• Know what the idea behind a project is.
• Understand how Positron implements projects.
• Be able to set up and manage projects in Positron.

Reading

Introduction

The concepts of projects are very useful for modeling and data analysis work. In Positron, projects are implemented in several flexible ways.

Projects

The general idea of a project is a collection of files and settings that are used together to accomplish a specific task, such as a modeling and data analysis project. Everything related to that project, such as data files, code files, documents, images, and settings are stored in one place, namely a folder (with subfolders) on your computer (and probably also in the cloud).

This way, you can easily find and access all the resources you need for that particular project. You will also be specifying locations for saving and loading files that are relative to your main project folder, thus allowing someone else to reproduce your work, even if they have a copy of your project folder and subfolders in a different location on their computer.

Organizing work into projects is very important for reproducibility, efficiency, automation and collaboration.

Projects in Positron

If you are familiar with R and RStudio, you know it has the concept of a project through an .Rproj file which is stored in some folder. The folder with this file indicates the top level project folder, and everything inside this folder - including sub-folders - is part of the project.

Positron does support .Rproj files. However, since Positron is designed to work with multiple programming languages, it also allows for other types of files to indicate the project folder. The naming convention in Positron-world is to call a project a workspace.

A very common setup is where a project/workspace corresponds to a Git/GitHub repository (Git/GitHub are explained in our Brief Introduction to Git/GitHub course). In this case, the project folder is the folder that contains the .git folder (which is hidden by default). Everything inside this folder - including sub-folders - is part of the project.

Similarly, for a Quarto project, e.g. a Quarto-based website, if Positron finds a _quarto.yml file in a folder, it considers it the main folder of a project/workspace.

Sometimes, Positron adds a file into the workspace at .vscode/settings.json, but only if the user sets custom settings. The existence of such a file also indicates the top folder of a project/workspace.

If at least one of these files/folders is present, Positron recognizes it as a top folder of a project/workspace.

Project creation in Positron

If you want to start a new project, there are multiple ways you can do so with Positron. One option is to go under File and select New Folder From Template. Then pick one of the available templates and follow the instructions. If unsure, you can always start with an empty project. If you know that you will be using Git/GitHub for the project (in general highly recommended), you can initialize it. Then open the new folder in Positron, and start working. Everything in that folder and subfolders is now considered part of your project.

Another approach is to first create a new GitHub repository (see our Brief Intro to Git/GitHub course) online, and then use New Folder from Git to clone it to your local machine and start using it as a new project/workspace within Positron.

Project use in Positron

If you already have a folder that corresponds to a project (with or without Git/GitHub tracking), you can simply open that folder in Positron using File -> Open Folder. Positron will then recognize it as a project/workspace, and everything inside that folder and subfolders will be part of the project.

There are more ways to open a project, for instance in Windows one can add Open with Positron in the context menu of folders, allowing you to right-click on a folder and open it directly in Positron. As you start working with projects and Positron, you’ll quickly figure out the most efficient ways for your personal style and setup. The further resources section below has some links with more information.

Summary

In this unit, we covered the concepts of projects, and how you can use them with Positron.

Further Resources

• Official Positron documentation on projects - the focus is on those who are used to the .Rproj setup, but it also provides good general information.
• VS Code workspace documentation - more information on how VS Code (and thus Positron) handles workspaces. Some of this is advanced, e.g. multi-root workspaces, which we generally don’t recommend.

Test yourself

Which of the following automatically marks a folder as the root of a Positron project/workspace?

A .git directory inside the folderA screenshot saved in the folderAny file named notes.txtA .csv data file

Positron treats common project markers like a .git directory as a signal that the folder is a workspace root.

• True
• False
• False
• False

What is a recommended way to start a new Positron project that will use Git/GitHub?

Create the repo on GitHub, then use New Folder from Git in Positron to clone itWrite code directly in the Downloads folder with no version controlOnly use the Julia REPL without saving any filesCopy random files into a temporary folder every time you work

Cloning a freshly created GitHub repo into Positron sets up a clean project folder that is ready for version control.

• True
• False
• False
• False

Why is it important to keep all files for a project inside the project/workspace folder?

It keeps paths consistent and makes the work reproducible for othersIt stops Positron from running codeIt prevents Git from tracking changesIt makes it impossible to share the project

Keeping everything inside the project folder means paths stay relative and the whole setup can be shared or reproduced easily.

• True
• False
• False
• False

Practice

• Try to create a new project/workspace using one of the approaches described above.
• Open an existing project/workspace, either the one you just created or something you already have. Navigate the folder structure to see what files are included in the project.