ouRGeo
Open-Source Spatial IDE
Home Features Docs Download Forum News Plugins Contribute Privacy Sign in Account Sign out

Projects & Files

How ouRGeo keeps your work between saves and through a crash, and the library that keeps your documents with the project.

01 Scratch and saved projects

Two ways of working, and the difference decides what survives a restart.

Scratch
Where ouRGeo starts when no project was open at quit: a clean R session you never have to name. Scratch keeps its untitled documents — your notes — with their cursor and position, and nothing else. Leaving it, by quitting or opening a project, drops its R objects, map, plots, console, chats and open files at that moment.
Saved project
A .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.

On a shared drive, colleagues see what was last saved. The draft lives on your computer, not in the project file. Use Save before someone else opens the project, or before you move or send the file.

03 Saving, closing and reverting

Save
Writes everything into the project file. By default it does not write your open scripts to their own files — their edits travel inside the project, still unsaved, until you save each script. Turn on Settings → Projects → Save document edits when saving the project to write them on every project save, including automatic ones. If a file cannot be written, the save stops and offers Save As…, Skip this file or Cancel.
Closing a project
Settings → Projects → When closing a saved project chooses what closing ouRGeo or switching projects does: keep the changes on this computer (the default), save the project automatically, or ask. Answering Don’t Save to the question still keeps the changes on this computer.
Revert to Saved…
In the project menu. The one action that throws working changes away: it lists what will be lost and returns the project to its last saved state.

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.

On Windows there is no 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:

Discard my changes and open theirs
Opens the version on disk and drops your working changes.
Open my version and save it over theirs
After a second confirmation that names when theirs was saved.
Resolve conflicts…
A three-way comparison of your version, theirs, and the version you both started from. Changes only one side made are combined for you and listed. Where both changed the same thing, you choose: per conflicting part of a document (mine, theirs, both, or edit by hand), and per R object, layer, plot, chat or project file (mine, theirs, or keep both — yours is renamed with _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:

Open as this project
Keeps the existing identity, and shares its project memory history.
Open as a copy
Gives it new project and memory identities, so it can be edited and saved independently.

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.

In project
Files you add are copied into the project and travel inside the .ourgeoproj with their exact bytes. Editing the source elsewhere does not change the project copy.
Linked
Files in a linked folder stay where they are, and the bundle does not grow by their size.

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:

Reference
Supporting evidence.
Standard
Likely requirements — a specification the work must meet.
Example
An illustration of the desired result.

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.

Added · Not saved means the file is protected by local recovery storage but is not yet in the portable project. Use the project’s Save before sharing or moving the bundle. Storing a file and indexing its contents are separate: a file can be safely stored even when its contents cannot be searched.

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.

Save folder label
Renames the folder as the project shows it.
Rescan folder
Refreshes discovery and re-indexes changed files.
Relink folder…
Points the link at the corresponding folder on this computer — what you do after opening a shared project on another machine.
Forget link…
Removes the folder connection and its catalogue entries. Its confirmation says Files on disk are kept.

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.

Linked files are not a portable snapshot. Sharing the project carries folder labels, relative file references and the catalogue — never your absolute paths, and never permission to read another machine. Use Add files for reference material that must travel inside the bundle byte for byte.

11 Supported contents

Files are indexed locally in the background, with no model call. Previews are read-only.

FilesWhat is available
Markdown, UTF-8 text, source codeSearchable contents and original line ranges.
PDFPage previews and the existing text layer, with page citations. Image-only pages are identified; OCR is not automatic.
DOCXText, lists and tables with section locations. The preview does not reproduce Word pagination.
XLSXVisible 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 / TSVStrings keep leading zeros; quoted fields and source line ranges are preserved.
PNG, JPEG, WebPBounded previews and metadata. Interpreting an image needs a vision-capable image model.
Other or password-protected filesStored and exportable; the status explains when indexing or preview is unavailable.

Replace, export, reindex

Export original
Writes the original bytes — export to edit in another application.
Replace file
Brings a revised copy back. Old citations keep their old revision, so they never silently open different bytes.
Remove from project
Withdraws a file; Undo removal works until you save or switch projects. The source on disk is never touched.
Reindex file / Reindex project files
Rebuilds missing or outdated extracted contents. Keeps your descriptions and makes no paid model calls.

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
FunctionSignature 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 folder tables and the file summary.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 = FALSE refuses 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.

Replacing asks first. When an export would replace a file already in Project Files, ouRGeo asks. Tick Don’t ask again to stop the question and turn it back on in Settings → Project Files. R code never asks: 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

Settings → Projects
What closing a saved project does; whether a project save also writes open documents; the R snapshot interval and how long the last one took; and Stored unsaved changes — every draft on this computer with its size and whether its project file still exists. Delete one, or all older than 30, 90 or 365 days. Deleting a draft never touches a project file.
Settings → Prompts
Every question you have told ouRGeo not to ask again, each with a switch to bring it back.
Settings → Project Files
Whether exports ask before replacing a file in the library.
Health check
Reports stored drafts too, and offers the same clean-out with your approval.

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.