GIO(1)

📦
version 2.90.1 · 9 versions
, in arch rolling, nixpkgs unstable, ubuntu stonking

🌸 NAME 🌸

gio — the GIO commandline tool. that's gio(1) bestie, and she does a lot. 💅

📜 SYNOPSIS 📜

gio help [COMMAND]
gio version
gio cat LOCATION…
gio copy [OPTION…] SOURCE… DESTINATION
gio info [OPTION…] LOCATION…
gio launch DESKTOP-FILE [FILE-ARG…]
gio list [OPTION…] [LOCATION…]
gio mime MIME-TYPE [HANDLER]
gio mkdir [OPTION…] LOCATION…
gio monitor [OPTION…] [LOCATION…]
gio mount [OPTION…] [LOCATION…]
gio move [OPTION…] SOURCE… DESTINATION
gio open LOCATION…
gio rename LOCATION NAME
gio remove [OPTION…] LOCATION…
gio save [OPTION…] DESTINATION
gio set [OPTION…] LOCATION ATTRIBUTE VALUE…
gio trash [OPTION…] [LOCATION…]
gio tree [OPTION…] [LOCATION…]

🦋 DESCRIPTION 🦋

okay so first things first: gio is a utility that makes a whole bunch of GIO features available straight from the commandline. how? by handing you commands that are similar to the traditional utilities you already know — except they let you use GIO locations instead of boring old local files. so like, you can literally use something like smb://server/resource/file.txt as a location. slay. 🔥

⚠️ lowkey important: plain filenames that contain a colon get interpreted as URIs with an unknown protocol. to dodge that, prefix them with a path such as ./, or with the file: protocol. no cap, this trips people up.

also, volumes, drives and mounts are limited to the ones that are considered interesting to the user — think removable drives. system mounts will not be shown, which means the output from gio mount is not equivalent to the output from tools like fdisk, and gio monitor --mounts will only list events relevant to selected mounts. that's just the vibe, bestie. 🫶

🌈 COMMANDS 🌈

help COMMAND

shows you a short synopsis of all the available commands, or — if you name a specific command — gives you the detailed help for just that one. your little study buddy. 📚

version

prints the GLib version that gio belongs to. simple as that. ✨

cat LOCATION…

concatenates the given files and prints them to standard output. it works just like the traditional cat utility.

Mote: just pipe through cat if you need its formatting options like -n, -T or other.

copy [OPTION…] SOURCE… DESTINATION

copies one or more files from SOURCE to DESTINATION. if you give it more than one source, then the destination must be a directory. it's basically the traditional cp utility but make it GIO. 💖

Options

  • -T, --no-target-directory — don't copy into DESTINATION even if it's a directory.
  • -p, --progress — show progress.
  • -i, --interactive — prompt for confirmation before overwriting files.
  • --preserve — preserve all attributes of copied files.
  • -b, --backup — create backups of existing destination files.
  • -P, --no-dereference — never follow symbolic links.
  • --default-permissions — use the default permissions of the current process for the destination file, instead of copying the permissions of the source file.

info [OPTION…] LOCATION…

shows information about the given locations. it's the traditional ls utility's cousin. 👑

Options

  • -w, --query-writable — list writable attributes.
  • -f, --filesystem — show information about the filesystem that the given locations reside on.
  • -a, --attributes=<ATTRIBUTES> — the attributes to get.

attributes can be specified with their GIO name, e.g. standard::icon, or just by namespace, e.g. unix, or by *, which matches all attributes. several attributes or groups of attributes can be specified, separated by commas.

by default, all attributes are listed.

  • -n, --nofollow-symlinks — don't follow symbolic links.

launch DESKTOP-FILE [FILE-ARG…]

launches a desktop file from any location you give it. 🚀

launch extends the behaviour of the open command by allowing any desktop file to be launched — not only the ones registered as file handlers. main character energy, honestly.

list [OPTION…] [LOCATION…]

lists the contents of the given locations. if you don't give it a location, it shows you the contents of the current directory. another traditional ls-style glow-up. 🎀

Options

  • -a, --attributes=<ATTRIBUTES> — the attributes to get.

attributes can be specified with their GIO name, e.g. standard::icon, or just by namespace, e.g. unix, or by *, which matches all attributes. several attributes or groups of attributes can be specified, separated by commas.

by default, all attributes are listed.

  • -h, --hidden — show hidden files.
  • -l, --long — use a long listing format.
  • -n, --nofollow-symlinks — don't follow symbolic links.
  • -d, --print-display-names — print display names.
  • -u, --print-uris — print full URIs.

mime MIME-TYPE [HANDLER]

if you don't hand it a handler, mime lists the registered and recommended applications for the MIME type. if you do give it a handler, that handler gets set as the default for that MIME type. 💅

handlers must be specified by their desktop file name, including the extension. example: org.gnome.gedit.desktop.

mkdir [OPTION…] LOCATION…

creates directories. the traditional mkdir utility, but you already knew that. ✨

Options

  • -p, --parent — create parent directories when necessary.

monitor [OPTION…] [LOCATION…]

monitors files or directories for changes — such as creation deletion, content and attribute changes, and mount and unmount operations affecting the monitored locations. 👀

monitor uses the GIO file monitoring APIs to do its thing. GIO has different implementations for different platforms, and the most common implementation on Linux uses inotify.

Options

  • -d, --dir=<LOCATION> — monitor the given location as a directory. normally, the file type is used to determine whether to monitor as a file or as a directory.
  • -f, --file=<LOCATION> — monitor the given location as a file. normally, the file type is used to determine whether to monitor as a file or as a directory.
  • -D, --direct=<LOCATION> — monitor the file directly. this allows changes made via hardlinks to be captured.
  • -s, --silent=<LOCATION> — monitor the file directly, but don't report changes.
  • -n, --no-moves — report moves and renames as simple deleted/created events.
  • -m, --mounts — watch for mount events.

mount [OPTION…] [LOCATION…]

gives you commandline access to all the various aspects of GIO's mounting functionality. 🔌

mounting here means the traditional concept of arranging multiple file systems and devices in a single tree, rooted at /. classical mounting happens in the kernel and is controlled by the mount utility. GIO expands that concept by introducing mount daemons that can make file systems available to GIO applications without kernel involvement. fancy, right?

GIO mounts can require authentication, and the mount command may ask for user IDs, passwords, and so on, when required. 🙈

Options

  • -m, --mountable — mount as mountable.
  • -d, --device=<ID> — mount volume with device file, or other identifier.
  • -u, --unmount — unmount the location.
  • -e, --eject — eject the location.
  • -t, --stop=<DEVICE> — stop drive with device file.
  • -s, --unmount-scheme=<SCHEME> — unmount all mounts with the given scheme.
  • -f, --force — ignore outstanding file operations when unmounting or ejecting.
  • -a, --anonymous — use an anonymous user when authenticating.
  • -l, --list — list all GIO mounts.
  • -o, --monitor — monitor mount-related events.
  • -i, --detail — show extra information.
  • --tcrypt-pim — the numeric PIM when unlocking a VeraCrypt volume.
  • --tcrypt-hidden — mount a TCRYPT hidden volume.
  • --tcrypt-system — mount a TCRYPT system volume.

move [OPTION…] SOURCE… DESTINATION

moves one or more files from SOURCE to DESTINATION. if more than one source is specified, the destination must be a directory. traditional mv behaviour, GIO flavour. 🦋

Options

  • -T, --no-target-directory — don't copy into DESTINATION even if it is a directory.
  • -p, --progress — show progress.
  • -i, --interactive — prompt for confirmation before overwriting files.
  • -b, --backup — create backups of existing destination files.
  • -C, --no-copy-fallback — don't use copy and delete fallback.

open LOCATION…

opens files with the default application that's registered to handle files of that type. 🫶

GIO gets this information from the shared-mime-info database, with per-user overrides stored in $XDG_DATA_HOME/applications/mimeapps.list.

the mime command can be used to change the default handler for a MIME type.

⚠️ heads up: environment variables will not be set on the application, because it may be an existing process which is activated to handle the new file.

rename LOCATION NAME

renames a file. it's the traditional rename utility, bestie. 💅

remove [OPTION…] LOCATION…

deletes each given file.

💀 this command removes files irreversibly. if you want a reversible way to remove files, see the trash command instead. do not play with this one unless you mean it.

note that not all URI schemes supported by GIO may allow deletion of files.

remove is similar to the traditional rm utility.

Options

  • -f, --force — ignore non-existent and non-deletable files.

save [OPTION…] DESTINATION

reads from standard input and saves that data to the given location. 💾

this is similar to just redirecting output to a file using traditional shell syntax, but save lets you save to a location that GIO can write to.

Options

  • -b, --backup — back up existing destination files.
  • -c, --create — only create the destination if it doesn't exist yet.
  • -a, --append — append to the end of the file.
  • -p, --private — when creating, restrict access to the current user.
  • -u, --unlink — when replacing, replace as if the destination did not exist.
  • -v, --print-etag — print the new ETag in the end.
  • -e, --etag=<ETAG> — the ETag of the file that is overwritten.

set [OPTION…] LOCATION ATTRIBUTE VALUE…

sets a file attribute on a file. ✨

okay so file attributes? you can specify them with their GIO name, like standard::icon. but heads up bestie, not all GIO file attributes are writable — some are just for looking. if you wanna see which ones you can actually write to, use the --query-writable option of the info command. she'll list 'em for you. 💅

if the TYPE is unset, then you don't have to specify VALUE at all. and if the TYPE is stringv, you can give multiple values. slay.

✨ Options for set ✨

  • -t, --type=<TYPE> — this sets the type of the attribute. the supported types are string, stringv, bytestring, boolean, uint32, int32, uint64, int64, and unset. if you don't specify the type, string is assumed. no biggie.
  • -d, --delete — unsets an attribute. literally the same as setting its type to unset. bye felicia 👋
  • -n, --nofollow-symlinks — don't follow symbolic links. we stay on the surface, no rabbit holes. 🐇

🗑️ trash

sends files or directories to the ‘Trashcan’ — or restores them from ‘Trashcan’. the trash folder can be a different folder depending on where the file is located, and not all file systems support this concept. in the common case that the file lives inside a user’s home directory, the trash folder is $XDG_DATA_HOME/Trash. periodt.

⚠️ note that moving files to the trash does not free up space on the file system until the ‘Trashcan’ is emptied. so it's giving "out of sight, out of mind" but not "out of disk". if you are interested in deleting a file irreversibly, see the remove command.

inspecting and emptying the ‘Trashcan’ is normally supported by graphical file managers such as Nautilus, but you can also see the trash with the command: gio trash --list or gio list trash://. iykyk.

Options

  • -f, --force — ignore non-existent and non-deletable files. it's giving "i don't see it, i don't care". 💅
  • --empty — empty the trash. yeet everything. 🗑️✨
  • --list — list files in the trash with their original locations. so you can see where they came from. 👀
  • --restore — restore a file from trash to its original location. a URI beginning with trash:// is expected here. if the original directory doesn’t exist, it will be recreated. so it's like "u up? come back home". 🏠

🌳 tree

lists the contents of the given locations recursively, in a tree-like format. if no location is given, it defaults to the current directory. the tree command is similar to the traditional tree utility. same vibes, GIO edition. 🌲

Options

  • -h, --hidden — show hidden files. let's see the secrets. 🙈
  • -l, --follow-symlinks — follow symbolic links. chase the links, bestie. 🔗

💥 EXIT STATUS 💥

on success, 0 is returned. otherwise, a non-zero failure code. that's it. no cap.

👀 SEE ALSO 👀

and that's the whole page, bestie. the footer says gio() — that's the source/version and date. periodt. 💖✨

📦 where this page comes from