DEB-GIR-TOOL(1)

📦 version 1.86.0, in ubuntu resolute, ubuntu stonking

💖 DEB-GIR-TOOL(1) 💖

okay bestie, gather round, because this is the deb-gir-tool page from the gobject-introspection family and it is lowkey a whole vibe. it's the Debian packaging helper for GObject-Introspection GIR XML and she is here to help you wrangle those .gir files. ✨

🦋 NAME 🦋

deb-gir-tool — Debian packaging helper for GObject-Introspection GIR XML. periodt.

🌸 SYNOPSIS 🌸

deb-gir-tool COMMAND [--upstream-paths] [--verbose] [--zero-terminated]
[OPTION...]

deb-gir-tool print-search-path [COMMON_OPTION...]

deb-gir-tool find [--if-exists] [--target-directory=DIR]
[--with-dependencies] [COMMON_OPTION...]  NAMESPACE-VER
[NAMESPACE-VER...]

✨ DESCRIPTION ✨

so deb-gir-tool manipulates GObject-Introspection GIR XML files (.gir files, iykyk) in all these different ways that come in clutch during Debian packaging. 💅

this tool is Debian-specific and you should not assume it's just hanging out on non-Debian-derived operating systems. she's exclusive, she's main character energy, she doesn't travel. 🎀

on Debian and Debian derivatives, depend or build-depend on gobject-introspection (>= 1.86.0-3~) to get access to this tool. no cap.

👑 COMMON OPTIONS 👑

these options are accepted by all commands, so they're basically the group chat everyone's in.

  • --upstream-paths — by default, deb-gir-tool only shows or searches paths that are appropriate for GIR XML packaged in .deb packages, currently /usr/share/gir-1.0 and /usr/lib/${DEB_HOST_MULTIARCH}/gir-1.0. but with --upstream-paths, instead deb-gir-tool mimics the behaviour of upstream tools like gi-compile-repository(1) and g-ir-scanner(1), showing or searching all search paths including those configured locally by the user or the sysadmin. it's giving "we're doing it the upstream way now". 🌈
  • --verbose, -v — show more informational output on standard error. deb-gir-tool find --verbose --with-dependencies shows which dependencies were a result of which modules, and deb-gir-tool find --verbose --target-directory=DIR shows which files it has copied. and if you repeat it, it enables debug-level logging on standard error. she said "more". 😌
  • --zero-terminated, -z — for commands that normally output a series of items one per line, terminate each item with a zero byte instead of a newline, like sed -z. iconic honestly.

💀 COMMANDS 💀

🔍 find

locate GIR XML and act on each file found. by default, each filename found is printed on standard output followed by a newline, or a zero byte if the --zero-terminated option was used. each namespace/version pair found is only shown or copied once, even if it appears on the command-line more than once. she does not do duplicates, bestie. 🙅

this command requires one or more non-option arguments, each consisting of a namespace, a dash and an API version number, for example GLib-2.0, Gtk-4.0 or Adw-1. yes the format matters. the dash is doing a lot of heavy lifting.

🍓 ADDITIONAL OPTIONS 🍓

  • --if-exists — silently ignore any nonexistent namespaces or versions specified. she's chill like that, no drama.
  • --keep — if the destination for copying already exists, skip copying instead of failing with an error. this is only useful in conjunction with --target-directory.
  • --overwrite — overwrite files instead of failing with an error. this is only useful in conjunction with --target-directory. she's not asking permission, she's just doing it. 💅
  • --target-directory DIR — instead of printing XML files' names on standard output, copy the XML files to the given DIR.
  • --with-dependencies — in addition to the modules given on the command-line, load each GIR XML file to find its dependencies, and show or copy those too. this is done recursively: the dependencies of dependencies are included. it's giving "and their friends, and their friends' friends". 🧚

output the directories that would be searched for GIR XML on standard output. each directory name is followed by a newline, or a zero byte if the --zero-terminated option was used.

this command does not accept any non-option arguments or additional options. that's it, that's the whole command. simple. clean. iconic. ✨

💜 ENVIRONMENT 💜

  • DEB_HOST_MULTIARCH — if set, search paths that would be appropriate for the given architecture, instead of the architecture for which deb-gir-tool was compiled. if it is run from debian/rules this will typically happen automatically. love that for us.
  • DEBUG_INVOCATION — if set to a non-empty value, show verbose log messages on standard error, similar to -v -v. the double v. the extra chatty era. 😭
  • G_MESSAGES_DEBUG — if set to a non-empty list of space-separated log domains, show verbose log messages on standard error for the given log domains (see GLib documentation for details). a value of all is typical. go big or go home.
  • GI_GIR_PATH — colon-separated list of paths to prepend to the search path if the --upstream-paths option was used. conditional queen.
  • XDG_DATA_HOME, XDG_DATA_DIRS — used to form the search path according to the freedesktop.org Base Directory specification if the --upstream-paths option was used. respect the spec, respect the vibe.

⭐ OUTPUT ⭐

machine-readable output is emitted on standard output. see the description of each command for details of the format. it's structured, it's parseable, it's serving.

human-readable diagnostic information may be emitted on standard error. it should not be parsed. do not parse the diagnostics bestie, i am begging you, that's the vibes-only channel. 🙈

🎀 EXIT STATUS 🎀

  1. 0 — the tool ran successfully. slay. 💖
  2. 1 — an error occurred. 😭
  3. 2 — the command-line arguments were invalid or not understood. girl what did you type.

🔥 EXAMPLES 🔥

show the absolute path where gi-compile-repository(1) would find GLib-2.0.gir if referenced as a dependency:

deb-gir-tool find --upstream-paths GLib-2.0

show where arm-linux-gnueabi-gi-compile-repository(1), the version of gi-compile-repository(1) for the armel architecture, would find GLib-2.0.gir, ignoring local configuration and using only standard OS paths:

dpkg-architecture -aarmel -c deb-gir-tool find GLib-2.0

copy Adw-1.gir and all of its recursive dependencies such as Gtk-4.0.gir and GLib-2.0.gir to the current working directory:

deb-gir-tool find -v --with-dependencies --target-directory=. Adw-1

🫶 SEE ALSO 🫶

gi-compile-repository(1), g-ir-compile(1), g-ir-scanner(1)

okay that's the whole page bestie, you're officially certified in deb-gir-tool behaviour. this was the gobject-introspection era of the docs, version 1.86.0-6build1, dated 2026-01-22. mwah, go package something cute. 💖✨🎀

📦 where this page comes from