g.mapsets(1)

📦
version 8.4.2 · 8 versions
, in fedora 44

💖 NAME 💖

g.mapsets — the icon that modifies/prints the user's current mapset search path. It's literally the thing that controls your access to data living under the other mapsets in your current project, bestie. No cap.

🌸 KEYWORDS 🌸

general, settings, search path — iykyk 🎀

✨ SYNOPSIS ✨

g.mapsets
g.mapsets --help
g.mapsets [-lps] mapset=name[,name,...] operation=string format=name [separator=character] [--help] [--verbose] [--quiet] [--ui]

🦋 Flags

  • -l — list all the available mapsets, in alphabetical order 💅
  • -p — print the mapsets in your current search path
  • -s — launch the mapset selection GUI dialog
  • --help — print usage summary
  • --verbose — verbose module output (chatty era)
  • --quiet — quiet module output (shhh era)
  • --ui — force launching the GUI dialog

🎀 Parameters

  • mapset=name[,name,...] [required] — name of mapset (default: current search path). It's the name(s) of existing mapset(s) to add/remove or set.
  • operation=string [required] — the operation to be performed. Options: set, add, remove. Default: add.
  • format=name [required] — output format. Options: plain, json. Default: plain.
    • plain: plain text output
    • json: JSON (JavaScript Object Notation)
  • separator=character — field separator. Special characters: pipe, comma, space, tab, newline.

💜 DESCRIPTION 💜

So g.mapsets modifies/prints the user's current mapset search path. If you want the basics on GRASS mapset, project and data base, go peek at GRASS Quickstart, bestie. 🌈

A mapset holds a distinct set of data layers, each one relevant to the same geographic region (or a subset of the same region), and each drawn in the same map coordinate system. At the very start of every GRASS session, you identify a GRASS data base, a project (previosuly called location — spelling's theirs, the lore is real 🫶), and a mapset, and those become your current data base, current project, and current mapset for the whole session. Any maps you create during the session get stored under the current mapset that was set at the session's outset. (Peep g.mapset — that's the one without an "s" — and g.gisenv if you wanna change the mapset mid-session. 🧚)

You can add, modify, and delete data layers that live under your current mapset. And yes, you can also access (i.e., use) data stored under other mapsets in the same GRASS project, either through the mapname@mapsetname notation or through the mapset search path — but here's the catch, babe: you can only make permanent changes (create or modify data) that are located in the current mapset. Your mapset search path is the list of the order in which the other mapsets in the same GRASS project get searched and their data accessed by you. You can modify that listing and that order by modifying the mapset search path — that's literally what g.mapsets is for. It lets you use other people's relevant map data without altering the original data layer, and without taking up disk space with a copy of the original map. And the mapname@mapsetname notation can be used irrespective of the mapset search path — like, any map found in another mapset with sufficient g.access privileges may be called in that manner. Slay. 🔥

g.mapsets shows you the available mapsets under the current GRASS project, lists the mapsets you currently have access to, and lists the order in which accessible mapsets will be accessed by GRASS programs searching for data files. Then you get the opportunity to add or delete mapset names from the search path, or modify the order in which mapsets will be accessed. Main character energy, honestly. 👑

When you specify the name of a data base element file to a GRASS program (say a particular vector map, raster map, imagery group file, etc.), the program searches for the named file under each of the mapsets listed in your mapset search path, in the order listed there, until it finds a file with that name. You can also specify a file by its mapset, to make explicit which mapset the file is drawn from — for example, this command:

g.copy raster=soils@PERMANENT,my_soils

ensures that a new file named my_soils is a copy of the file soils from the mapset PERMANENT.

In each project there's the special mapset PERMANENT included in the mapset search path, because this mapset typically contains base maps relevant to tons of applications. Often, other mapsets containing sets of interpreted maps will likewise be included in your mapset search path. Suppose, for example, that the mapset Soil_Maps contains interpreted soils map layers you want access to. Then the mapset Soil_Maps should be included in your search path variable. 💅

The mapset search path is saved as part of the current mapset. So when you work with that mapset in later GRASS sessions, the previously saved mapset search path will be used (and it keeps being used until you modify it with g.mapsets). It remembers. It's loyal. 🥹

⭐ NOTES ⭐

  • By default, g.mapsets adds to the current mapset search path the mapsets named by the mapset option. Alternatively, mapsets can be removed (operation=remove) from the search path, or defined by operation=set.
  • Users can restrict other people's access to their mapset files through use of g.access. And here's the tea: mapsets with restricted access can still be listed in someone else's mapset search path — but access to those mapsets will remain restricted. Listing ≠ permission, bestie. 💀

🌈 EXAMPLES 🌈

🎀 Selecting mapsets with the graphical mapset manager

Using the -s flag, a convenient graphical mapset manager opens up so you can select and deselect other mapsets (the actual mapset and the PERMANENT mapset are always selected):

g.mapsets -s

All available mapsets in the current project can be printed out by

g.mapsets -l

Available mapsets:

PERMANENT user1 user2

Mapsets can also be printed out as json by setting the format option to "json" (format="json").

g.mapsets format="json" -l
{
  "mapsets": [
    "PERMANENT",
    "user1",
    "user2"
  ]
}

🎀 Add new mapset

Add mapset 'user2' to the current mapset search path:

g.mapsets mapset=user2 operation=add

The current mapset search path is changed accordingly:

g.mapsets -p

Accessible mapsets:

user1 user2

🎀 Overwrite current search path

Overwrite current search path:

g.mapsets mapset=user1,PERMANENT operation=set

🎀 Using shortcuts for search path

The current mapset can be defined by a shortcut . (dot):

g.mapsets mapset=.,PERMANENT operation=set
Note: the current mapset will be always included in the search path on the first position, even if you change its position or omit the current mapset from the mapset option. She goes first. Periodt. 👑
g.mapsets -p

Accessible mapsets:

user1 PERMANENT

🦋 SEE ALSO 🦋

g.access, g.copy, g.gisenv, g.list, g.mapset

💖 AUTHORS 💖

  • Michael Shapiro, U.S.Army Construction Engineering Research Laboratory
  • Greg Koerper, ManTech Environmental Technology, Inc.
  • Updated to GRASS 7 by Martin Landa, Czech Technical University in Prague, Czech Republic

🌸 SOURCE CODE 🌸

Available at: g.mapsets source code (history)

Accessed: Saturday Jan 17 05:40:39 2026

Main index | General index | Topics index | Keywords index | Graphical index | Full index

© 2003-2025 GRASS Development Team, GRASS GIS 8.4.2 Reference Manual

And that's the whole page, bestie 🫶 — straight outta the GRASS GIS User's Manual, running GRASS 8.4.2, filed under g.mapsets(1). Go fix your search path, you gorgeous genius. ✨💅🎀

📦 where this page comes from