01 Scratch and saved projects
Two ways of working, and the difference decides what survives a restart.
.ourgeoproj file, created with Save As…. It
keeps the whole working state, between saves as well as in the file, and reopens
exactly where you left it. If a project was open when you quit, ouRGeo reopens it
at the next launch.Leaving scratch
Before anything is dropped, ouRGeo lists it and offers Save as project…, which keeps all of it — including edits to open files, carried as unsaved edits inside the new project. Don’t ask again stops the offer, and Settings → Prompts turns it back on. Then each open file with unsaved edits is asked about: Apply writes the edits to the file, Drop discards them, and Apply to all remaining answers for the rest. A file that cannot be written is named, with Save As… or Drop. Files dropped from scratch are listed under Recently Closed Files in the project menu.
02 What a saved project keeps
Everything, continuously, on this computer — so closing never costs you work.
While you work, ouRGeo keeps a draft of the project on this computer alongside the project file:
- every open document, with its unsaved edits, cursor, selection, scroll position, folding, Source or Visual mode and chunk output;
- Data Viewer and function editor tabs;
- the R environment, including your own environments and attached packages;
- the map: layers, symbology, named map sessions, extent, legend, and geometry edits not yet written to R;
- plots, the console history and assistant chats;
- R’s working directory and the environment the console works in;
- pending Project Files imports and changes.
Close ouRGeo or open another project and nothing is asked: the next time you open the project it comes back exactly as it was. While the draft holds changes the file does not, the project menu shows a dot and reads Unsaved changes, kept on this computer.
03 Saving, closing and reverting
Closing a document
Closing a document with unsaved edits — its ×, Ctrl+W, Close Others, Close All, or the assistant — asks Save / Discard / Cancel, or Save to file… / Discard / Cancel for a document that has never been saved. Closing several at once adds Apply to all remaining.
04 The R environment snapshot
R objects are snapshotted once R has been idle for 30 seconds and something has changed. On Linux and macOS a forked copy of the R process writes the snapshot in the background, so a command you run is never held up. Change the R snapshot interval in Settings → Projects — from 10 seconds to 30 minutes, or only when closing or switching — and the time the last snapshot took is shown beside it.
Some objects cannot survive a restart. ouRGeo rebuilds what it can: .Rgeo
datasets reconnect, raster map layers re-register, and terra rasters and
vectors are packed so they come back (a file-backed raster is reopened from its
file). The rest are named, with the reason, in one warning:
Not restored: con (database connection), r_tmp (temporary raster file is gone)
The warning has Don’t show again; the console always gets the same list.
fork, so the snapshot runs in R itself and
pauses it briefly. The idle interval keeps that pause away from your own
commands.
05 After a crash
If ouRGeo did not close properly, the next launch recovers what it had kept and says so, in a message that cannot be turned off:
- the documents restored, and any whose recovery copy could not be read;
- the time of the R snapshot the objects came from — objects created after it need re-running, and the console history shows what you ran;
- the time of the newest recovered change.
If only R stops, nothing else is touched: R restarts, the objects come back from the last snapshot, and a message says from when.
06 When the project file changes elsewhere
If someone else saves the project file after you opened it, ouRGeo notices — when you open the project and again before you save — and offers three choices:
_mine).Everything can be inspected before you choose: str(), class and size for
R objects, feature counts and fields for layers, and both images for plots. Nothing
is written until Finish and save; Cancel leaves your version open and
asks again next time.
07 Project identity and copies
A project carries a portable identity, so its memories and settings follow the project rather than the file name. Moving a bundle keeps its identity. Opening a duplicate — the same project in a second folder — asks which it is:
A project can be open in one window at a time. Opening it in a second window says so and offers to show the first.
Scripts and .Rgeo databases linked from a project reconnect when you
reopen it on the same computer. On another computer, scripts open from the text
bundled in the project and you choose the local database files — a bundle can
never grant access to unrelated absolute paths on the machine that opens it.
09 Project Files
Keep reports, standards, figure examples and supporting documents with the project — or link folders whose originals stay on disk.
Open Project Files from the project menu, or from its tab beside R console and Terminal; drag the pane anywhere and ouRGeo remembers it. The library works without an AI account or an R connection once the project is saved.
.ourgeoproj with their exact bytes. Editing the source elsewhere does
not change the project copy.Adding and organising
Choose Add files, or drop files onto the pane. In scratch the button reads Save project to add files and creates a named project first; cancelling that save imports nothing.
Select a file and open Preview / details to edit its display name, logical folder, description and role:
A role helps the assistant find the right document; it does not insert the document into every conversation. Your descriptions survive reindexing. Logical folders classify files without moving anything on disk.
Search, sort and filter the list by location, role, folder, status or assistant availability. All locations includes linked folders; In project shows only embedded files, and each linked folder has its own filter. Use Select multiple, Ctrl/⌘-click or Shift-click to select; arrow keys, Home/End and Enter navigate, Delete opens the removal review and Esc clears a selection.
10 Linked folders
Choose Linked folders in the Project Files header, then either:
- Link folder… — select an existing folder;
- Create linked folder… — name a new folder, then Choose parent and create folder… to create it on disk and link it.
Both need a saved, named project. Linked files appear in the same list with a Linked badge, and their details show the relative path, folder label and the location on this computer. You can edit their description, role, display name and folder — none of which renames or moves the original. Edit the original in its folder, then choose Rescan folder. The pane’s footer reports In project bytes separately from Linked external bytes.
A missing or stale folder stays visible with an explanation and a recovery action; its files cannot be attached to the assistant until the link is ready. Remove from project hides a linked file from this project and never deletes the source.
11 Supported contents
Files are indexed locally in the background, with no model call. Previews are read-only.
| Files | What is available |
|---|---|
| Markdown, UTF-8 text, source code | Searchable contents and original line ranges. |
| Page previews and the existing text layer, with page citations. Image-only pages are identified; OCR is not automatic. | |
| DOCX | Text, lists and tables with section locations. The preview does not reproduce Word pagination. |
| XLSX | Visible sheets and cells: typed values, displayed values and stored formulas. Formulas are not recalculated, so cached results may be old. Hidden contents need an explicit selection. |
| CSV / TSV | Strings keep leading zeros; quoted fields and source line ranges are preserved. |
| PNG, JPEG, WebP | Bounded previews and metadata. Interpreting an image needs a vision-capable image model. |
| Other or password-protected files | Stored and exportable; the status explains when indexing or preview is unavailable. |
Replace, export, reindex
Limits
The library holds up to 2,000 files, 100 MiB per original and 1 GiB of originals in total, separately from the R snapshot. Extraction has its own page, cell and text limits, and a large file may be listed as metadata only; Partly searchable marks incomplete coverage. A locked destination, a full disk or a failed verification preserves the last successful save.
12 Project Files from R
Keep your usual readers and writers, and change only the path.
Five functions are available in every R session ouRGeo runs — the console, document chunks, toolbox tools and Knit.
# Read: an embedded file is copied, read-only and with its name and extension, # into R's temporary directory; a linked file is read where it is. sites <- read.csv(ourgeo_project_file("data/sites.csv")) roads <- sf::st_read(ourgeo_project_file("roads.gpkg")) # Write: any function that takes a file path. write.csv(summary, ourgeo_project_path("tables/summary.csv"), row.names = FALSE) ggsave(ourgeo_project_path("figures/map.png"), p, width = 7, height = 5) # Bring an existing file in now. ourgeo_project_save("~/Downloads/standard.pdf", "reference/standard.pdf", description = "Clearance standard") ourgeo_project_files() # list the library ourgeo_project_commit() # save pending writes before the command ends
| Function | Signature and purpose |
|---|---|
ourgeo_project_file() | (name, location = NULL)
— a path to read. location picks "project" or a
linked folder when a name exists in both. |
ourgeo_project_path() | (name, folder = NULL,
description = NULL, location = "project", overwrite = TRUE) — a path to
write; the file joins the library when the command finishes. |
ourgeo_project_save() | (path, name = basename(path),
folder = NULL, description = NULL, location = "project", overwrite = TRUE)
— copy an existing file into the library now. |
ourgeo_project_files() | (pattern = NULL, location =
NULL) — list the library, optionally filtered by a regular expression
on "folder/name". |
ourgeo_project_commit() | (quiet = FALSE)
— save files written so far, rather than when the command ends. |
- Names are the names in the Project Files pane.
"tables/summary.csv"means the logical foldertablesand the filesummary.csv; folders are labels, not locations on disk, and..is refused. Names are unique across the library. - When a written file is saved.
ourgeo_project_path()hands the writer a temporary path. The file is added to Project Files when the console command or chunk finishes, and the console reports it. Reading a staged name later in the same command saves it first, so write-then-read inside one script works. A path nothing wrote to is forgotten, with a note. - Writing the same name again replaces that file, keeping its folder and
description, as writing over a file on disk would. Identical bytes are reported as
unchanged.
overwrite = FALSErefuses instead. - Saving the project is what puts new or replaced files into the
.ourgeoproj. Until then they show Added · Not saved and are recoverable. - Linked folders.
ourgeo_project_path("out/result.csv", location = "Field data")writes into that linked folder on disk and rescans it. - Scratch has no library: the functions stop and ask you to save the project
first. Outside ouRGeo, in a plain
Rscript, they stop with a message — export the file from the pane and use its path.
13 Exporting into the project
Every export dialog that writes a file offers Project Files as a destination
beside a folder on disk, with an optional logical folder (figures or
tables by default):
- plot export from the Plots panel;
- map Export to IMG and Export Code (tmap/ggplot) in the spatial editor;
- Export to Project Files in the Environment panel’s menu;
- the Data Viewer’s checked Export layer…
— a new GeoPackage is named after the layer (
data/roads.gpkg), and Add layer or Replace named layer update a GeoPackage already in the library. Only the verified file is saved.
Each dialog echoes the R it ran, with ourgeo_project_path() in place of a
path, so the console record is replayable:
ourgeo_save_plot(ourgeo_project_path("figures/plot.png"), width = 7, height = 5, units = "in", dpi = 300)
The map image is a screenshot with no R behind it, so the console records where it was saved and points at Export Code for the reproducible version.
ourgeo_project_path() replaces a file of the same name, as writing over a
file on disk does.
14 Project Files and the assistant
The chat’s Add files imports into the same library, Choose project files attaches existing ones, and Attach to chat is in every file’s details. Attach a PDF page, a document section, a sheet or cell range, or a line range when only one part matters — up to three sources per message.
The assistant discovers documents and reads only the relevant excerpts; importing never uploads the whole library to a model. Answers cite the file and its page, section or cells, and clicking a citation opens that location. Clear Available to the assistant to keep a file’s name, description and contents out of its reach. Separate document and image models, and optional AI descriptions, are covered under File analysis models.
15 Settings and housekeeping
Compatibility and limits
- A project that uses Project Files cannot be opened by an ouRGeo without it: older versions reject the newer project rather than resave it without its files. Projects from older versions open with an empty library and upgrade the first time the library is saved.
- A live drawing session — its undo stack and a half-drawn shape — is not kept; staged geometry edits are.
- Unlabelled R Markdown chunks may lose their output on reopen; labelled chunks keep it.
- A Data Viewer tab comes back on the same object, but not at the row it was scrolled to or with its sort.
- Persistence and Project Files were verified on Linux. Windows and macOS have not yet been verified natively.