xdg-desktop...filechooser(5)

xdg-desktop...filechooser(5) 🦋✨

okay so this is the xdg-desktop...filechooser(5) page from the File Formats Manual, and it's all about xdg-desktop-portal-termfilechooser — the terminal-filechooser portal backend. bestie, it's actually useful, I promise 💅

✨ NAME ✨

xdg-desktop-portal-termfilechooser — an xdg-desktop-portal backend to choose files with your favorite terminal file manager.

🌸 DESCRIPTION 🌸

xdg-desktop-portal-termfilechooser (or xdptf for short, because we are not typing all that every time 😭) allows applications to choose files via xdg-desktop-portal using your favorite terminal filechooser. It's giving terminal-native file-picking main character energy fr fr.

xdptf will try to load the configuration file from these locations:

• $XDG_CONFIG_HOME/xdg-desktop-portal-termfilechooser/$XDG_CURRENT_DESKTOP
• $XDG_CONFIG_HOME/xdg-desktop-portal-termfilechooser/config
• /etc/xdg/xdg-desktop-portal-termfilechooser/$XDG_CURRENT_DESKTOP
• /etc/xdg/xdg-desktop-portal-termfilechooser/config

$XDG_CONFIG_HOME defaults to ~/.config. $XDG_CURRENT_DESKTOP can be a colon separated list. Each element of that list will be tried — all of them, no cap.

🎀 WRAPPERS 🎀

Wrappers are shell scripts that take in a number of arguments and launch the file manager with the correct settings to select files. Refer to WRAPPER ARGUMENTS for specifics — that's where the deets live 👑

There are several included wrappers provided in either /usr/local/share/xdg-desktop-portal-termfilechooser or /usr/share/xdg-desktop-portal-termfilechooser by default.

These wrappers are designed to use the environment variable TERMCMD for launching a terminal emulator. If TERMCMD is not set, kitty is used as the default terminal emulator. slay.

🦋 WRAPPER ARGUMENTS 🦋

These arguments need to be captured by the wrapper to allow the selection of files. Every single one is essential, don't skip:

• Name: multiple — Description: Selection of multiple files. Position: Argument 1. Value: boolean < 0 | 1 >.
• Name: directory — Description: Selection of a directory. Position: Argument 2. Value: boolean < 0 | 1 >.
• Name: save — Description: Selection for saving files. Position: Argument 3. Value: boolean < 0 | 1 >.
• Name: path — Description: The suggested file or directory received from the application. Position: Argument 4. Value: string < file/directory path >.
• Name: out — Description: The file to write selected files/directories to. Position: Argument 5. Value: string < file path >.
• Name: debug — Description: Enable/Disable debug output for the wrapper (Log levels 4/DEBUG and higher). Position: Argument 6. Vaule: boolean < 0 | 1 > — yes bestie, Vaule is literally how it's written in the original, and we're keeping that detail 💅.

💖 FILECHOOSER CONFIGURATION 💖

The configuration file uses the INI file format. The only implemented section is [filechooser] at the time of writing. Keys declared multiple times are overwritten with the value of the last declaration (except for env described below).

Last one wins, except the special env exception — noted, bestie 🫶

🌟 FILECHOOSER OPTIONS 🌟

These options need to be placed under the [filechooser] section. Like, they live there, okay?

• cmd = command — Command to execute. This is typically set to a wrapper script. For invocation details, please refer to the default wrapper script.

If the command is not a full path, a modified PATH environment variable is searched for commands/scripts.

The modified PATH prioritizes searching as follows:

• $XDG_CONFIG_HOME/xdg-desktop-portal-termfilechooser
• /usr/local/share/xdg-desktop-portal-termfilechooser
• /usr/share/xdg-desktop-portal-termfilechooser
• Global $PATH

The default value is yazi-wrapper.sh.

• create_help_file = bool — Populates the destination save file with instructions.

Accepted values are 0 and 1.

The default value is 1.

• default_dir = directory — Default directory to open in your file manager if the invoking program does not provide one.

The default value is $HOME with a fallback of /tmp.

• env = name=value — Environment variable to launch cmd with. This key allows for several environment variables to be set. Either set env= multiple times, or indent the values as shown in EXAMPLE CONFIG.
• open_mode = mode — Sets what path the file manager starts in when selecting files/directories. The mode needs to be one of suggested, default, or last. A brief description of these modes is:
  • suggested — Uses the application's suggested path.
  • default — Uses the value set for default_dir.
  • last — Uses the parent directory of the last selected file. If the last selection was a directory, that is used instead.

The default value is suggested.

• save_mode = mode — Sets what path the file manager starts in when saving files. The mode needs to be one of suggested, default, or last.
  • suggested — Uses the application's suggested path.
  • default — Uses the value set for default_dir.
  • last — Uses the parent directory of the last selected file. If the last selection was a directory, that is used instead.

The default value is suggested.

🌈 EXAMPLE CONFIG 🌈

Here's the exact config vibe, bestie:

[filechooser]
cmd=yazi-wrapper.sh
create_help_file=0
default_dir=$HOME
env=TERMCMD=foot
     EDITOR=nvim
open_mode=suggested
save_mode=last

---

That's the whole page, bestie 🫶. This iconic lil manual page is dated 1980-01-01, and it's the xdg-desktop...filechooser(5) page from the File Formats Manual — go forth and pick files with terminal main character energy 💅✨