# CommandSection

title: CAVEATS
content:
The GEM <i>.img</i> format can have variations; <b>gemtopnm</b> might not support all specific permutations or non-standard <i>.img</i> files.<br>It always outputs to standard output, so redirection (e.g., `>`) is necessary to save the image to a file.<br>Color handling is limited to monochrome, 2-color, and 16-color, reflecting the capabilities of the original GEM graphics environment.


title: INPUT/OUTPUT
content:
<b>gemtopnm</b> reads the GEM <i>.img</i> file from the filename specified as an argument or from standard input if no filename is provided. The resulting PNM image is always written to standard output. Therefore, to save the output, you typically need to redirect it to a file, for example: `gemtopnm image.img > image.pnm`.


title: OUTPUT IMAGE TYPES
content:
Depending on the color depth of the input GEM image, <b>gemtopnm</b> automatically produces either a Portable Bitmap (PBM) for monochrome and 2-color images or a Portable Pixmap (PPM) for 16-color images. The output PNM type is chosen to best represent the original GEM image data, ensuring compatibility with other Netpbm tools.


title: HISTORY
content:
<b>gemtopnm</b> is a component of the Netpbm project, a comprehensive toolkit for manipulating graphical images that originated in the early 1990s as Pbmplus. It was developed to handle the GEM <i>.img</i> format, which was prevalent on systems like the Atari ST and early PC graphical environments, making these legacy images accessible and convertible to more common formats. The Netpbm suite, including <b>gemtopnm</b>, has been continuously maintained and expanded by various contributors, with Bryan Henderson being a key figure in recent decades.


title: PARAMETERS
content:
<b><i>EXECUTIVE</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;An optional executable file from which <b>gendesk</b> can attempt to infer information like the application name or execution command.<br><br><b><b>--name</b> <i>NAME</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the <b>Name</b> field in the <i>.desktop</i> file, which is the application's displayed name.<br><br><b><b>--exec</b> <i>COMMAND</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the <b>Exec</b> field, specifying the command to execute when the application is launched. Arguments can be included.<br><br><b><b>--icon</b> <i>ICON_PATH</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the <b>Icon</b> field, pointing to the application's icon file (e.g., a PNG, SVG, or icon theme name).<br><br><b><b>--type</b> <i>TYPE</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the <b>Type</b> field. Common types include <i>Application</i> (for programs), <i>Link</i> (for URLs), or <i>Directory</i>.<br><br><b><b>--comment</b> <i>COMMENT</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the <b>Comment</b> field, providing a short description or tooltip for the application.<br><br><b><b>--category</b> <i>CATEGORY</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Adds a category to the <b>Categories</b> field (e.g., <i>Utility</i>, <i>Game</i>). This option can be used multiple times.<br><br><b><b>--terminal</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets <b>Terminal=true</b>, indicating the application should be run in a terminal window.<br><br><b><b>--nodisplay</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets <b>NoDisplay=true</b>, meaning the application should not be shown in menus, but can still be launched programmatically.<br><br><b><b>--hidden</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets <b>Hidden=true</b>, marking the application as deprecated or no longer relevant.<br><br><b><b>--mimetype</b> <i>MIME_TYPE</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Adds a MIME type to the <b>MimeType</b> field (e.g., <i>text/plain</i>). This option can be used multiple times for multiple types.<br><br><b><b>--output</b> <i>FILE</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the output file path where the generated <i>.desktop</i> content will be saved, instead of printing to standard output.<br><br><b><b>--user</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;If supported by the implementation, installs the <i>.desktop</i> file for the current user (typically in <i>~/.local/share/applications/</i>).<br><br><b><b>--all-users</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;If supported, installs the <i>.desktop</i> file system-wide for all users (typically in <i>/usr/share/applications/</i>).<br><br><b><b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a brief usage message and exits.<br><br><b><b>--version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays version information and exits.<br><br>


title: DESCRIPTION
content:
The <b>gendesk</b> command is a utility designed to simplify the creation of freedesktop.org compliant <i>.desktop</i> files. These files are crucial for desktop environments like GNOME, KDE, and XFCE, as they provide metadata about applications, including their name, icon, execution command, categories, and MIME types.<br><br>Instead of manually crafting complex <i>.desktop</i> files, <b>gendesk</b> allows users or package maintainers to generate them from simpler input, often by deriving information from existing executable files or through concise command-line arguments. It helps automate the process of creating proper application launchers, ensuring applications integrate smoothly into the desktop environment.


title: CAVEATS
content:
The exact set of supported options and their behavior can vary slightly between different implementations of <b>gendesk</b> across Linux distributions. For full integration, generated <i>.desktop</i> files often require placement in standard directories (e.g., <i>/usr/share/applications/</i> or <i>~/.local/share/applications/</i>) and a cache refresh via <b>update-desktop-database</b>.


title: .DESKTOP FILE FORMAT
content:
<i>.desktop</i> files are INI-like configuration files used by XDG compliant desktop environments to describe applications, documents, and directories. They contain metadata such as <b>Name</b>, <b>Exec</b>, <b>Icon</b>, <b>Categories</b>, and <b>MimeType</b>, enabling the desktop environment to display applications in menus, handle file associations, and launch programs correctly.


title: INTEGRATION WITH DESKTOP ENVIRONMENTS
content:
By generating standardized <i>.desktop</i> files, <b>gendesk</b> ensures applications are correctly represented and launched within various desktop environments. This includes proper menu integration, icon display, and association with relevant file types, contributing to a seamless user experience on Linux desktops.


title: HISTORY
content:
<b>gendesk</b> emerged as a convenience script to automate the creation of <i>.desktop</i> files, which became the standard for application launchers in Freedesktop.org compliant desktop environments (GNOME, KDE, XFCE). Its development aligns with the broader effort to standardize Linux desktop components, often appearing as part of development utility packages (like <i>devscripts</i> on Debian/Ubuntu) or build tools, simplifying packaging processes for application developers and maintainers.


title: SYNOPSIS
content:
<br><b><code>openssl gendsa</code></b> [<i>options</i>] <i>dsa_parameters_file</i><br><br>Where <i>dsa_parameters_file</i> is a path to a file containing the DSA parameters (P, Q, G) to be used for key generation.


title: PARAMETERS
content:
<b><i>dsa_parameters_file</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Required argument.</i> Specifies the path to a file containing the DSA parameters (P, Q, G) from which the private key will be derived.<br><br><b>-out <i>filename</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the output file for the generated DSA key. If this option is not used, the key is written to standard output (stdout).<br><br><b>-rand <i>file(s)</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies one or more files (colon-separated) to read random data from, used to seed the Pseudo-Random Number Generator (PRNG).<br><br><b>-engine <i>id</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies a cryptographic engine to be used, overriding the default engine.<br><br><b>-passout <i>arg</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the source for the output file's pass phrase, used if the private key is encrypted.<br><br><b>-aes128 | -aes192 | -aes256 | -camellia128 | -camellia192 | -camellia256 | -des | -des3 | -idea | -seed</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Encryption options. These flags encrypt the generated private key using the specified symmetric cipher (e.g., AES, DES3). A passphrase will be prompted or read via <b><code>-passout</code></b>.<br><br>


title: DESCRIPTION
content:
<b><code>openssl gendsa</code></b> is a subcommand of the <i>openssl</i> command-line tool, used for generating a new DSA (Digital Signature Algorithm) private key. Unlike RSA key generation, <b><code>gendsa</code></b> does not create the DSA parameters (P, Q, G) itself. Instead, it requires these parameters to be provided in an input file, typically generated beforehand using commands like <i>openssl dsaparam</i>.<br><br>Once provided with valid parameters, <b><code>gendsa</code></b> generates the private component (X) of the DSA key pair and calculates the corresponding public component (Y). The generated private key can be optionally encrypted with a passphrase using various symmetric encryption algorithms. This command is a fundamental part of establishing secure communications and digital signing capabilities in systems relying on DSA cryptography, providing the essential private key required for these operations.


title: CAVEATS
content:
<ul><li>The <b><code>gendsa</code></b> command itself does not generate DSA parameters (P, Q, G). These must be pre-generated, typically using <b><code>openssl dsaparam</code></b>, and provided as an input file. Without valid parameters, the command will fail.</li><li>The security of the generated DSA key heavily relies on the quality of the DSA parameters provided and the randomness used by the PRNG. Ensure parameters are strong and the PRNG is sufficiently seeded, especially for production environments.</li></ul>


title: DSA PARAMETERS
content:
The Digital Signature Algorithm (DSA) requires a set of global parameters (P, Q, G) to be established first. These parameters define the cryptographic group in which the key operations occur. <b><code>gendsa</code></b> uses these parameters to generate the unique private (X) and public (Y) components of an individual DSA key pair.


title: KEY PROTECTION
content:
When a private key is generated, it's often encrypted with a passphrase to protect it from unauthorized access. <b><code>gendsa</code></b> supports various symmetric encryption algorithms (e.g., AES, DES3) for this purpose, ensuring that even if the key file is compromised, its contents remain unreadable without the correct passphrase.


title: HISTORY
content:
The <b><code>gendsa</code></b> subcommand has been a part of the OpenSSL toolkit for a long time, evolving with the OpenSSL project itself. Its development is tied to the general support for DSA cryptography within OpenSSL, providing a standard utility for generating the private component of DSA key pairs once the domain parameters are established. As a core cryptographic tool, its functionality has remained relatively stable, with updates primarily focusing on security enhancements, performance, and integration with newer OpenSSL features like engines and various symmetric encryption algorithms for key protection.


title: PARAMETERS
content:
<b>-U, --uuid</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Generate entries using filesystem UUIDs. This is generally the recommended and default behavior for stable booting.<br><br><b>-L, --label</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Generate entries using filesystem labels instead of UUIDs or device paths.<br><br><b>-P, --path</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Generate entries using device paths (e.g., <i>/dev/sda1</i>). Less robust than UUIDs/labels.<br><br><b>-R, --root <dir></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the root directory of the target system. This is crucial when running <b>genfstab</b> from a live environment or another system.<br><br><b>-r, --old-root <dir></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the old root directory. Useful when running <b>genfstab</b> from within a <i>chroot</i> where the original root is still accessible.<br><br><b>-F, --fstab <file></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify an alternative <i>fstab</i> file to read from instead of <i>/etc/fstab</i>.<br><br><b>-A, --all</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Include all currently mounted filesystems, including bind mounts, virtual filesystems (<i>proc</i>, <i>sys</i>, <i>devpts</i>), etc.<br><br><b>--no-dump</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Do not include the <i>dump</i> field (the fifth field) in the generated entries.<br><br><b>--no-pass</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Do not include the <i>pass</i> field (the sixth field) in the generated entries. This field determines fsck order.<br><br><b>--no-defaults</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Do not add <i>defaults</i> as a mount option if no specific options are determined.<br><br><b>--preserve-swap</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Preserve existing swap entries from the specified <i>fstab</i> file.<br><br><b>--preserve-all</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Preserve all existing non-root entries from the specified <i>fstab</i> file, merging them with newly generated entries.<br><br><b>--exclude <mntpoint></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Exclude a specific mount point from the generated entries.<br><br><b>--exclude-fs <filesystem></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Exclude filesystems of a specific type (e.g., <i>tmpfs</i>, <i>proc</i>) from the generated entries.<br><br><b>--help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display a help message and exit.<br><br><b>--version</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Output version information and exit.<br><br>


title: DESCRIPTION
content:
The <b>genfstab</b> command is a utility designed to automatically generate entries for the <i>/etc/fstab</i> file, based on the currently mounted filesystems or a specified root directory. It scans the detected mount points, determines filesystem types, device paths (or more robustly, UUIDs or labels), and appropriate mount options (like <i>defaults</i>, <i>noatime</i>).<br><br>It is most commonly used in system installation or recovery scenarios, particularly within a <i>chroot</i> environment, to create an initial or updated <i>fstab</i> file for a new or existing Linux system. This helps ensure that filesystems are mounted correctly upon boot, especially for partitions that might not be easily identified by traditional device paths (e.g., due to kernel device naming changes). By default, it prioritizes using UUIDs or labels for greater reliability and persistence across reboots or hardware changes.


title: CAVEATS
content:
<b>genfstab</b> generates entries based on the current system state or a specified root. It might not perfectly replicate a hand-tuned <i>fstab</i> file, especially regarding custom mount options or specific dump/pass values. Always review the generated output before redirecting it to <i>/etc/fstab</i>, as an incorrect <i>fstab</i> can prevent your system from booting. It's primarily a tool for generating an initial <i>fstab</i> or for basic system recovery, not for complex, nuanced configurations.


title: TYPICAL USAGE
content:
The most common use case involves generating an <i>fstab</i> for a new system mounted at a specific directory (e.g., <i>/mnt</i>) from a live environment. The output is usually redirected to the target system's <i>/etc/fstab</i>.<br><br>Example: genfstab -U /mnt > /mnt/etc/fstab<br><br>This command scans the filesystems mounted under <i>/mnt</i> (including <i>/mnt/boot</i>, <i>/mnt/home</i>, etc.) and generates <i>fstab</i> entries using UUIDs, writing them to <i>/mnt/etc/fstab</i>.


title: UUIDS VS. DEVICE PATHS
content:
While <b>genfstab</b> can generate entries using device paths (e.g., <i>/dev/sda1</i>), it strongly recommends and often defaults to using UUIDs (Universally Unique Identifiers) or LABELS. UUIDs are unique identifiers assigned to filesystems and remain constant even if the device path changes (e.g., due to adding or removing other drives), making them far more reliable for system booting.


title: HISTORY
content:
The <b>genfstab</b> utility is typically part of distribution-specific scripts or utilities (e.g., in Arch Linux's <i>arch-install-scripts</i> package) or integrated into installation environments. Its primary development focus has been on simplifying the creation of a correct <i>/etc/fstab</i>, especially for new installations or when dealing with systems where device names might be inconsistent. Over time, it has evolved to prioritize the use of UUIDs and filesystem labels for increased robustness, moving away from less reliable device paths.


title: PARAMETERS
content:
<b><I>TYPE</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the type of ID to generate. Common types include <i>uuid</i>, <i>machine</i>, <i>boot</i>, <i>host</i>, etc. If omitted, a UUID is usually generated.<br><br><b><b>--uuid</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Generates a standard version 4 UUID.<br><br><b><b>--machine</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Generates a unique Machine ID, typically used for <i>/etc/machine-id</i>.<br><br><b><b>--boot</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Generates a unique Boot ID for the current system boot.<br><br><b><b>--host</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Generates a unique Host ID.<br><br><b><b>--from-name=<I>NAME</I></b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Generates a version 5 UUID from a specified string <i>NAME</i>, based on a namespace.<br><br><b><b>--namespace=<I>ID</I></b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies a namespace ID (UUID) to be used with <b>--from-name</b> for deterministic ID generation.<br><br><b><b>--random</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Ensures the generated ID is cryptographically random.<br><br><b><b>--pretty</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Formats the output ID with hyphens (e.g., xxxxxxxx-xxxx-...). Default is typically raw hex.<br><br><b><b>--save-to=<I>PATH</I></b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Saves the generated ID to the specified file path.<br><br><b><b>--version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays the version information and exits.<br><br><b><b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a help message and exits.<br><br>


title: DESCRIPTION
content:
The <b>genid</b> command is a utility, typically part of the <i>systemd-id128</i> package, used for generating different types of 128-bit unique identifiers. These IDs include Universally Unique Identifiers (UUIDs), Globally Unique Identifiers (GUIDs), Machine IDs, Boot IDs, and Host IDs.<br><br>These identifiers are fundamental to <i>systemd</i>'s operation, ensuring unique identification for system components, boots, and installations. <b>genid</b> can produce IDs based on cryptographic randomness, derived from names, or from file contents. It's often employed by system administrators or scripts to initialize or re-generate specific system identifiers, such as the content of <i>/etc/machine-id</i>. The command ensures generated IDs conform to standard UUID formats (e.g., DCE 1.1, ISO/IEC 11578). While it can generate general-purpose UUIDs, its primary role is in low-level system identifier management rather than typical end-user application development.


title: CAVEATS
content:
<b>genid</b> is often a symlink to <i>systemd-id128</i>. It's primarily a low-level utility for system-level ID management within <i>systemd</i> environments. Modifying critical system IDs like the Machine ID should be done with extreme caution, as it can impact system uniqueness and services depending on it. Elevated privileges are often required for such operations.


title: TYPES OF 128-BIT IDS
content:
<b>genid</b> is capable of producing several distinct types of 128-bit unique identifiers:<br><b>UUID</b>: A Universally Unique Identifier, typically a version 4 (random) or version 5 (name-based) identifier, used for general-purpose unique identification.<br><b>Machine ID</b>: A unique ID for a specific host installation, usually stored in <i>/etc/machine-id</i>. It persists across reboots and is crucial for many <i>systemd</i> services and network identification.<br><b>Boot ID</b>: A unique ID generated for each system boot. It changes every time the system starts up, used for distinguishing individual boot sessions.<br><b>Host ID</b>: Another form of unique identifier for a host, distinct from the Machine ID, used in specific contexts.


title: HISTORY
content:
The <b>genid</b> command, as part of <i>systemd-id128</i>, emerged with the development of the <i>systemd</i> init system, which gained prominence in the early 2010s. It was designed to provide standardized and robust mechanisms for generating and managing critical 128-bit unique identifiers required by <i>systemd</i> for various components and operations, replacing older, less centralized ID generation methods.


title: SYNOPSIS
content:
<I>genisoimage</I> [<I>options</I>] <B>-o</B> <I>filename</I> <I>pathspec</I> [<I>pathspec</I> ...]<br>


title: PARAMETERS
content:
<b><B>-o</B> <I>filename</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the output filename for the ISO image. This option is mandatory.<br><br><b><B>-R</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enable Rock Ridge extensions, preserving UNIX file attributes like long filenames, permissions, and symbolic links.<br><br><b><B>-r</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Similar to <B>-R</B>, but sets all files to read-only for everyone and turns off UID/GID preservation, making the image more portable.<br><br><b><B>-J</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enable Joliet extensions, providing compatibility with Microsoft Windows systems by supporting Unicode filenames up to 64 characters.<br><br><b><B>-U</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Allows 'untranslated' filenames, useful when using Joliet or Rock Ridge for filenames that do not map to the ISO9660 filename character set.<br><br><b><B>-V</B> <I>id</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the volume ID (or volume label) of the CD/DVD. Max 32 characters.<br><br><b><B>-b</B> <I>eltorito_boot_image</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the path to the El Torito boot image, making the CD/DVD bootable. The path must be relative to the source directory.<br><br><b><B>-c</B> <I>boot_catalog</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the path to the El Torito boot catalog file, which contains information about the boot images.<br><br><b><B>-udf</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Creates a UDF (Universal Disk Format) filesystem image, which offers better support for large files and modern operating systems than ISO9660.<br><br><b><B>-hfs</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Creates an Apple HFS+ filesystem image, compatible with macOS.<br><br><b><B>-print-size</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints the estimated size of the ISO image in sectors to standard error before writing it.<br><br><b><B>-iso-level</B> <I>level</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the ISO9660 conformance level (1, 2, 3, or 4). Higher levels allow longer filenames and deeper directory structures.<br><br><b><B>-input-charset</B> <I>charset</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the character set used for input filenames. Useful when dealing with filenames containing non-ASCII characters.<br><br><b><B>-exclude-list</B> <I>file</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Reads a list of paths from <I>file</I> to be excluded from the ISO image. Each path must be on a new line.<br><br><b><B>-v</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables verbose output, showing more details about the image creation process.<br><br>


title: DESCRIPTION
content:
The <I>genisoimage</I> command is a powerful utility used to create <B>ISO9660</B>, <B>Joliet</B>, and <B>UDF</B> filesystem images from a given set of files and directories. These images are typically used for optical media like CDs, DVDs, and Blu-ray discs, or for creating bootable USB drives and virtual machine images. It functions by arranging files into a structure that conforms to various CD/DVD/BD standards, handling file permissions, timestamps, and symbolic links. <br><br>As a robust and widely used tool, <I>genisoimage</I> supports several extensions, including <B>Rock Ridge</B> (for UNIX-like systems, preserving long filenames and permissions), <B>Joliet</B> (for Windows, supporting Unicode filenames), and <B>El Torito</B> (for creating bootable media). It is an essential part of the Linux toolkit for anyone needing to archive data, distribute software, or prepare system installation media.


title: CAVEATS
content:
When creating images, be aware of character set issues, especially with non-ASCII filenames; explicit use of <B>-input-charset</B> or <B>-output-charset</B> may be necessary. Combining different extensions like Joliet and Rock Ridge can lead to complex filename mappings. Large file support is limited by ISO9660 specifications unless UDF is explicitly used. <I>genisoimage</I> needs sufficient temporary disk space, often twice the size of the final image, during its operation.


title: FILESYSTEM EXTENSIONS
content:
Beyond the basic ISO9660 standard, <I>genisoimage</I> supports several extensions to enhance compatibility and features:<br><br><B>Rock Ridge</B>: Designed for UNIX and Linux systems, allowing for long filenames (up to 255 chars), deep directory hierarchies, UNIX file permissions, and symbolic links.<br><B>Joliet</B>: Developed by Microsoft, primarily for Windows systems, supporting Unicode filenames up to 64 characters and deeper directory structures than basic ISO9660.<br><B>UDF (Universal Disk Format)</B>: A newer standard offering robust support for larger files (over 4GB) and better cross-platform compatibility, often used for DVDs and Blu-ray discs. <I>genisoimage</I> can create pure UDF images or hybrid ISO9660/UDF images.


title: CREATING BOOTABLE IMAGES
content:
<I>genisoimage</I> supports the <B>El Torito</B> standard for creating bootable CDs/DVDs. This involves specifying a boot image using <B>-b</B> and optionally a boot catalog using <B>-c</B>. The boot image can be a floppy emulation, hard disk emulation, or a 'no emulation' boot image, which is common for modern Linux distributions. Proper configuration of these options is crucial for creating a bootable disk that systems can recognize and boot from.


title: HISTORY
content:
The <I>genisoimage</I> command is a fork of the original <I>mkisofs</I> program, which was developed by Eric Youngdale. The split occurred mainly due to licensing disagreements between the `cdrtools` suite (which includes <I>mkisofs</I>) and the GPL license commonly used in Linux distributions. <I>genisoimage</I> became part of the <B>cdrkit</B> project, initiated by Debian, ensuring an open-source, GPL-compatible alternative for CD/DVD image creation. It maintains much of the functionality and command-line syntax of its predecessor.


title: PARAMETERS
content:
<b>all</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Builds the kernel, modules, and a corresponding initramfs. This is the most commonly used action for a complete build.<br><br><b>bzImage</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Builds only the kernel bzImage (the compressed kernel executable) without modules or initramfs.<br><br><b>initramfs</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Builds only the initramfs from the currently installed kernel modules. Useful for updating the initramfs without recompiling the kernel.<br><br><b>install</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Installs the previously built kernel, modules, and initramfs to the appropriate locations (e.g., /boot and /lib/modules).<br><br><b>clean</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Cleans the <i>genkernel</i> build directories and temporary files generated during previous runs.<br><br><b>--menuconfig</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Launches <i>make menuconfig</i> interactively before compiling the kernel, allowing custom kernel configuration. The resulting <i>.config</i> is then used for the build.<br><br><b>--oldconfig</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Uses the existing <i>.config</i> file and prompts for new kernel options, similar to <i>make oldconfig</i>. Useful for minor updates to an existing configuration.<br><br><b>--mrproper</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Performs a full clean of the kernel source tree before compilation, equivalent to <i>make mrproper</i>. This removes all generated files, including configuration files.<br><br><b>--kernel-config=&lt;path&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies an alternative kernel configuration file to use instead of the default. This allows building with a custom <i>.config</i> from a specific location.<br><br><b>--mountboot</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Automatically mounts the /boot partition if it's not already mounted before attempting to install the kernel and initramfs.<br><br><b>--symlink</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Creates symbolic links for the newly installed kernel and initramfs (e.g., <i>vmlinuz-genkernel-x86</i> and <i>initramfs-genkernel-x86</i>), making it easier to update bootloader configurations.<br><br><b>--ramdisk-modules</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Includes all compiled kernel modules in the initramfs. This creates a larger initramfs but ensures maximum compatibility during early boot, especially for diverse hardware.<br><br><b>--hostonly</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Includes only modules necessary for the current host's detected hardware in the initramfs. This typically results in a much smaller and faster-loading initramfs.<br><br><b>--lvm</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Adds support for Logical Volume Manager (LVM2) to the initramfs, essential for booting from LVM-managed root filesystems.<br><br><b>--luks</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Adds support for Linux Unified Key Setup (LUKS) encryption to the initramfs, required for booting from encrypted root filesystems.<br><br><b>--bootloader</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Attempts to update the bootloader configuration (e.g., GRUB) after kernel installation, making the new kernel bootable.<br><br><b>--no-install</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prevents <i>genkernel</i> from installing the compiled kernel and modules after a successful build. Useful for testing or manual installation.<br><br><b>--no-clean</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prevents <i>genkernel</i> from cleaning its temporary build directories after completion, useful for debugging build issues.<br><br><b>--kernel-sources=&lt;path&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the path to the Linux kernel source tree to be used for compilation. Defaults to <i>/usr/src/linux</i>.<br><br><b>--compress-initramfs=&lt;compressor&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the compression algorithm for the initramfs (e.g., <i>gzip</i>, <i>bzip2</i>, <i>lzma</i>, <i>xz</i>, <i>zstd</i>). Defaults vary based on system configuration.<br><br><b>--force</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Forces certain actions, such as overwriting existing files without prompting.<br><br><b>--verbose</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Increases the verbosity of the output, showing more details about the compilation process.<br><br><b>--help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a help message with available commands and options.<br><br>


title: DESCRIPTION
content:
<i>genkernel</i> is a powerful utility designed specifically for Gentoo Linux to simplify and automate the process of compiling the Linux kernel, its modules, and a corresponding initramfs (initial RAM filesystem). Its primary goal is to provide a 'just works' kernel for a wide range of hardware, reducing the need for users to manually configure complex kernel options via <i>make menuconfig</i>. This automation makes system upgrades and hardware changes significantly easier, as it ensures all necessary drivers for common hardware are included. <br><br>While it aims for a generic kernel, <i>genkernel</i> offers numerous options to fine-tune the build, allowing users to include support for specific features like LVM, LUKS encryption, software RAID, or network booting, directly within the initramfs. It handles the full compilation process, from cleaning the source tree to installing the compiled kernel and modules, and can even update bootloader configurations.


title: CAVEATS
content:
<i>genkernel</i> is primarily designed for Gentoo Linux and might not be directly applicable or easily portable to other distributions. While it simplifies kernel compilation, the resulting 'generic' kernel can sometimes be larger than a hand-tuned one, potentially consuming more disk space and memory. It relies heavily on the kernel source tree being correctly installed and managed, typically via Gentoo's <i>emerge</i> and <i>eselect kernel</i> tools. For highly specific or bleeding-edge hardware, manual kernel configuration via <i>--menuconfig</i> might still be necessary to ensure optimal driver selection or performance.


title: DEFAULT KERNEL CONFIGURATION
content:
When run without a specified kernel configuration (e.g., <i>--menuconfig</i> or <i>--kernel-config</i>), <i>genkernel</i> typically starts with a default configuration. This default is often based on the kernel running on the system or a generic configuration provided by Gentoo, which <i>genkernel</i> then modifies by auto-detecting hardware and enabling essential drivers for system functionality.


title: INITRAMFS IMPORTANCE
content:
The initramfs generated by <i>genkernel</i> is a critical component for many modern Linux systems. It provides a minimal root filesystem in RAM that contains necessary modules and utilities (like LVM, LUKS, or network drivers) to mount the actual root filesystem. This allows booting from complex storage configurations or network locations before the main system is fully available, offering significant flexibility for diverse system setups.


title: INTEGRATION WITH GENTOO
content:
<i>genkernel</i> is deeply integrated into the Gentoo ecosystem. It expects kernel sources to be managed via <i>emerge</i> (e.g., <i>sys-kernel/gentoo-sources</i>) and typically uses default paths like <i>/usr/src/linux</i> for source code. Its installation process aligns with Gentoo's standards, placing compiled artifacts in well-defined locations, facilitating seamless system updates and bootloader interaction within a Gentoo environment.


title: HISTORY
content:
<i>genkernel</i> emerged as a crucial utility for Gentoo Linux users, specifically to address the complexity of manual kernel compilation which is a hallmark of Gentoo. In the early days of Gentoo, users were expected to compile their kernels from scratch, a process that, while offering ultimate control, could be daunting and time-consuming. <i>genkernel</i> was developed to automate this process, making Gentoo more accessible while retaining its flexibility. It has since evolved to include various features for initramfs generation and bootloader integration, remaining a core component of the Gentoo ecosystem, simplifying updates and system maintenance for a wide range of users.


title: PARAMETERS
content:
<b>-algorithm <alg></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the public key algorithm to use (e.g., <b>RSA</b>, <b>DSA</b>, <b>EC</b>, X25519, X448).<br><br><b>-pkeyopt <opt:val></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set a private key algorithm option, e.g., <i>rsa_keygen_bits:2048</i> for key length or <i>ec_paramgen_curve:prime256v1</i> for <b>EC</b> curves.<br><br><b>-out <filename></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Output the generated private key to the specified file. Defaults to standard output.<br><br><b>-pass <arg></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The password source for encrypting the output key. Can be <i>pass:<text></i>, <i>file:<path></i>, <i>env:<var></i>, etc.<br><br><b>-aes128|-aes192|-aes256|-camellia128|-camellia192|-camellia256|-des|-des3|-idea</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Encrypts the output key using the specified symmetric cipher algorithm.<br><br><b>-genparam</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Generates algorithm parameters rather than a private key. Useful for <b>DSA</b> or <b>EC</b>.<br><br><b>-paramfile <file></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Uses algorithm parameters from the specified file to generate the key.<br><br><b>-rand <files></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies one or more files or an <b>EGD</b> socket for seeding the random number generator.<br><br><b>-writerand <file></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Writes additional random data to the specified file after key generation.<br><br><b>-verbose</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints extra information and progress during the key generation process.<br><br><b>-traditional</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Outputs the key in the traditional format (e.g., <b>PKCS#1</b> for <b>RSA</b>/<b>DSA</b>/<b>DH</b>, <b>SECP</b> for <b>EC</b>).<br><br><b>-f4</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Uses 65537 (0x10001) as the <b>RSA</b> public exponent (default for <b>RSA</b> key generation).<br><br><b>-pubexp <exponent></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies an alternative <b>RSA</b> public exponent, e.g., <i>3</i>.<br><br><b>-noout</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prevents printing of the encoded key to standard output or file.<br><br><b>-text</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints the private key in plain text form (including public key components).<br><br><b>-engine <id></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies a hardware cryptographic engine to use for operations.<br><br><b>-old</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Uses the old <b>PKCS#8</b> format for encrypted private keys (less common now).<br><br>


title: DESCRIPTION
content:
<i>genpkey</i> is a utility command in the OpenSSL toolkit used for generating private keys. It supports various algorithms including <b>RSA</b>, <b>DSA</b>, <b>EC</b>, and X25519/X448. The command provides options for specifying the algorithm, key length (where applicable), public exponent for <b>RSA</b>, and parameters for <b>EC</b> keys. It can also encrypt the generated private key using a passphrase. The output can be written to a file or standard output. This tool is fundamental for cryptographic operations, secure communication, and digital certificate management, forming the basis for Public Key Infrastructure (PKI). It replaces older, algorithm-specific key generation commands like <i>genrsa</i> and <i>gendsa</i> by providing a unified interface for key generation across different cryptographic algorithms.


title: CAVEATS
content:
The security of generated keys heavily depends on the quality of the random number source; ensure sufficient entropy using <i>-rand</i>.<br>Keys generated with non-standard public exponents (for <b>RSA</b>) might face compatibility issues with some legacy systems.<br>Generating parameters with <i>-genparam</i> can be computationally intensive and time-consuming, especially for large key sizes or complex algorithms.<br>The default output format is <b>PKCS#8</b>, which is generally preferred over traditional formats for its versatility and standardization.


title: KEY ALGORITHM OPTIONS DETAILS
content:
<i>genpkey</i> uses the <i>-pkeyopt</i> option to specify algorithm-specific parameters. For <b>RSA</b>, common options include <i>rsa_keygen_bits:<length></i> (e.g., <i>rsa_keygen_bits:2048</i> for a 2048-bit key) and <i>rsa_keygen_pubexp:<exponent></i>. For <b>DSA</b>, it's typically <i>dsa_paramgen_bits:<length></i>. For <b>EC</b>, it's often <i>ec_paramgen_curve:<curve_name></i> (e.g., <i>ec_paramgen_curve:prime256v1</i> or <i>secp384r1</i>).


title: OUTPUT KEY FORMATS
content:
By default, <i>genpkey</i> outputs the private key in <b>PKCS#8</b> format, a standard for storing private key information. The <i>-traditional</i> option can be used to output in older, algorithm-specific formats (e.g., <b>PKCS#1</b> for <b>RSA</b>). For encrypted keys, the default is <b>PKCS#8</b> encrypted. The <i>-old</i> option can be used to output encrypted keys in the traditional <b>PKCS#8</b> old format, though this is less common now.


title: HISTORY
content:
The <i>genpkey</i> command was introduced in OpenSSL to provide a unified and more flexible interface for generating private keys across different cryptographic algorithms. Prior to <i>genpkey</i>, users typically relied on algorithm-specific commands such as <i>genrsa</i> for <b>RSA</b> keys, <i>gendsa</i> for <b>DSA</b> keys, and <i>gensec</i> for <b>EC</b> keys. These separate commands sometimes had inconsistent option sets and required users to learn multiple interfaces. <i>genpkey</i> streamlines the process by allowing the algorithm to be specified as an option (<i>-algorithm</i>), consolidating key generation into a single command. This unification simplifies scripting and improves user experience by offering a consistent syntax for all supported private key types. It reflects OpenSSL's ongoing effort to modernize its command-line utilities and improve cryptographic flexibility.


title: PARAMETERS
content:
<b><i>--remote</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Hypothetically, fetches and lists Node.js versions available from remote repositories (e.g., Node.js download servers).<br><br><b><i>--local</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Hypothetically, lists Node.js versions that are already installed on the local system.<br><br><b><i>--lts</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Hypothetically, filters the output to show only Long Term Support (LTS) versions of Node.js.<br><br><b><i>--current</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Hypothetically, displays the Node.js version currently active or in use within the environment.<br><br><b><i>[pattern]</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Hypothetically, an optional argument to filter the list of versions by a specific pattern (e.g., '16.', 'v18.x').<br><br>


title: DESCRIPTION
content:
<i>get-nodeversions</i> is not a standard Linux command found in typical distributions. Instead, it is highly likely a custom script or an internal function used within a Node.js development environment, such as a Node Version Manager (like <b>nvm</b>) or a specialized build/deployment system. Its primary purpose, based on its name, is to retrieve or enumerate available Node.js runtime versions.<br><br>This utility would typically help developers or CI/CD pipelines identify which Node.js versions are installed locally, which are available remotely, or to filter specific types of releases (e.g., Long Term Support - LTS versions). While its exact behavior and available options depend entirely on its specific implementation, it provides a crucial programmatic way to interact with Node.js version management, facilitating tasks like switching versions, installing new ones, or validating compatibility.


title: CAVEATS
content:
This command is <b>not</b> a standard, universally available Linux utility. Its existence, syntax, and behavior depend entirely on a custom implementation, often as part of a Node.js version management tool (like <b>nvm</b>'s internal functions) or a project-specific build script. The information provided here is illustrative and based on the likely functionality implied by its name. Users should consult the documentation of the specific system or script where <i>get-nodeversions</i> is employed.


title: COMMON USE CASES
content:
While not a direct user command, the functionality implied by <i>get-nodeversions</i> is crucial in several scenarios:<br><b>CI/CD Pipelines:</b> To dynamically select or validate Node.js versions before building or testing applications.<br><b>Development Environment Setup:</b> Automating the installation of specific Node.js versions required by a project.<br><b>Scripting:</b> Building custom scripts that interact with Node.js version managers or need to list available versions for reporting or decision-making.


title: IMPLEMENTATION CONSIDERATIONS
content:
A script named <i>get-nodeversions</i> would typically be implemented as a shell script (e.g., Bash, Zsh) that might:<br>Parse local directories where Node.js versions are installed (e.g., ~/.nvm/versions/node/).<br>Make HTTP requests to the official Node.js distribution servers to fetch available release lists.<br>Utilize internal functions of a Node Version Manager to query its state.<br>The output format (e.g., plain text, JSON) would vary based on its specific design.


title: HISTORY
content:
As <i>get-nodeversions</i> is typically a custom or internal script, it does not have a formal, documented history like standard Linux commands. Its conceptual origin lies in the increasing need for robust Node.js version management, driven by rapid Node.js release cycles and the requirement for projects to target specific runtime versions. The rise of tools like <b>nvm</b> (Node Version Manager) implicitly created the need for internal functions or helpers that can programmatically enumerate and manage these versions, making commands like <i>get-nodeversions</i> a functional necessity in modern Node.js development workflows.


title: PARAMETERS
content:
<b><b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a help message and exits. (Common for Python scripts)<br><br><b><b>--domain</b> <i>&lt;DOMAIN_NAME&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the Active Directory domain to query (e.g., <i>example.com</i>).<br><br><b><b>--server</b> <i>&lt;DC_IP_OR_HOSTNAME&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the IP address or hostname of a domain controller to connect to. If not specified, it might attempt to discover one.<br><br><b><b>--user</b> <i>&lt;USERNAME&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The username for authenticating to Active Directory (e.g., <i>'user@domain.com'</i> or <i>'DOMAIN\user'</i>).<br><br><b><b>--password</b> <i>&lt;PASSWORD&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The password for the specified user. It's often recommended to avoid providing passwords directly on the command line for security reasons.<br><br><b><b>--filter</b> <i>&lt;LDAP_FILTER&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;An LDAP search filter to narrow down the user results (e.g., <i>'(sAMAccountName=jdoe*)'</i> or <i>'(&(objectClass=user)(!(userAccountControl:1.2.840.113556.1.4.803:=2)))'</i> for active users).<br><br><b><b>--fields</b> <i>&lt;ATTR1,ATTR2,...&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;A comma-separated list of Active Directory attributes to retrieve for each user (e.g., <i>'sAMAccountName,mail,displayName,description'</i>).<br><br><b><b>--output</b> <i>&lt;FORMAT&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the output format, such as <i>'csv'</i>, <i>'json'</i>, or <i>'text'</i>.<br><br><b><b>--limit</b> <i>&lt;NUMBER&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Limits the number of users returned by the query.<br><br>


title: DESCRIPTION
content:
<i>getadusers.py</i> is typically a custom Python script designed to query and extract user information from an Active Directory (AD) domain. Unlike standard Linux commands, this script is not part of a default distribution and its exact functionality, syntax, and options are entirely dependent on how it was programmed. It commonly leverages Python libraries like <b><I>ldap3</I></b>, <b><I>python-ldap</I></b>, or similar modules to interact with LDAP (Lightweight Directory Access Protocol) services provided by Active Directory domain controllers. The script's primary purpose is often to automate tasks such as user enumeration, auditing user attributes, or integrating AD user data with other systems. Because it's a custom script, users must typically obtain the script's source code or documentation to understand its specific capabilities and usage.


title: CAVEATS
content:
<b><I>getadusers.py</I></b> is a custom script, meaning its behavior, options, and security implications are entirely dependent on its implementation. <br><br><b>Security:</b> Be cautious when providing credentials on the command line, as they might be visible in process listings (e.g., <b><I>ps</I></b> output) or command history. Secure methods like environment variables or interactive prompts are often preferred. <br><br><b>Dependencies:</b> The script requires Python 3 and specific Python libraries (e.g., <b><I>ldap3</I></b>, <b><I>dnspython</I></b>) to be installed in the Python environment. <br><br><b>Network Connectivity:</b> Proper network connectivity to the Active Directory domain controllers is essential. Firewalls or network configurations can prevent the script from connecting. <br><br><b>Permissions:</b> The user account used for authentication must have sufficient read permissions within Active Directory to query the desired user attributes.


title: TYPICAL USAGE
content:
A common use case involves running the script on a Linux server to pull user lists for inventory, to synchronize user data with other systems, or to perform ad-hoc lookups of user attributes. Example:<br><b><I>python3 getadusers.py --domain mydomain.com --server 192.168.1.10 --user 'svc_adreader' --password 'SecureP@ss1' --filter '(objectClass=user)' --fields 'sAMAccountName,mail' --output csv > ad_users.csv</I></b><br>This command would query all user objects in <i>mydomain.com</i>, retrieve their <i>sAMAccountName</i> and <i>mail</i> attributes, and save the output in CSV format to <i>ad_users.csv</i>.


title: REQUIRED LIBRARIES
content:
To function, <i>getadusers.py</i> often relies on Python packages that can be installed via <b><I>pip</I></b>, such as: <br><b><I>pip install ldap3</I></b> <br><b><I>pip install python-ldap</I></b> (requires development headers for LDAP libraries on the system) <br><b><I>pip install dnspython</I></b> (often used for domain controller discovery)


title: HISTORY
content:
Python scripting for Active Directory interaction has evolved significantly, particularly with the growth of cross-platform AD management needs. Scripts like <i>getadusers.py</i> emerged as lightweight, flexible alternatives to native Windows tools or heavier open-source packages. They often started as simple utilities to fetch basic user data but have grown in complexity to handle more advanced queries, authentication methods (like Kerberos), and data processing. Their development is typically driven by specific administrative or integration requirements within organizations, leveraging Python's rich ecosystem of LDAP and network libraries.


title: PARAMETERS
content:
<b>--help, -h</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display a help message and exit.<br><br><b>--version, -V</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show script's version information and exit.<br><br><b>--machine, -m</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Output only the hardware machine name (e.g., x86_64).<br><br><b>--os, -o</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Output only the operating system name (e.g., Linux).<br><br><b>--kernel, -k</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Output only the kernel release version.<br><br><b>--processor, -p</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Output only the processor type (e.g., i386, x86_64).<br><br><b>--all, -a</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Output all available architecture details in a structured format.<br><br><b>--short, -s</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Output a concise architecture string (e.g., x86_64-Linux).<br><br>


title: DESCRIPTION
content:
The <b>getarch.py</b> script is a non-standard, custom Python utility designed to extract and present information about the underlying system's architecture. Unlike native Linux commands such as <i>uname</i> or <i>arch</i>, <b>getarch.py</b> is often developed to provide a consistent, cross-platform interface for obtaining system architecture details, making it particularly useful in environments where portability across different operating systems (Linux, macOS, Windows) is crucial. <br><br>It typically leverages Python's built-in <i>platform</i> module to query details like the hardware machine name (e.g., x86_64, aarch64), operating system name (e.g., Linux, Darwin), kernel release, and processor type. Its output can be configured to be concise for scripting purposes or detailed for informational display, depending on the options provided. As a Python script, it requires a Python interpreter to be installed on the system.


title: CAVEATS
content:
<b>getarch.py</b> is not a standard Linux command; it is typically a custom Python script. Therefore, its availability, exact functionality, and accepted options may vary depending on how it was implemented. It requires a Python interpreter to be installed on the system to execute. Permissions issues may arise if the script is not executable or not located in the system's PATH.


title: USAGE EXAMPLES
content:
To get the machine architecture only: <br><code>getarch.py --machine</code><br><br>To get all available details: <br><code>getarch.py --all</code><br><br>To get a concise architecture identifier: <br><code>getarch.py --short</code>


title: TYPICAL OUTPUT
content:
Without options, <b>getarch.py</b> typically outputs a single line describing the architecture, similar to `uname -m`. When using options like `--all`, it might provide a more detailed, possibly structured (e.g., key-value pairs or JSON) output, including information about the operating system, kernel version, and processor type.


title: HISTORY
content:
As a custom script, <b>getarch.py</b> does not have a formal historical development like standard Linux commands. It represents a common pattern in scripting where developers create small, self-contained utilities to achieve specific tasks, often with an emphasis on cross-platform compatibility. Such scripts are frequently found in software projects or build systems that need to dynamically adapt their behavior based on the detected system architecture, ensuring consistent results where native OS commands might differ or be unavailable.


title: PARAMETERS
content:
<b>-v</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Verbose mode. Displays more information, such as parsing warnings or when capabilities are being applied.<br><br><b>-r</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Recursive mode. When a directory is specified, it recursively traverses the directory and displays capabilities for all files and subdirectories.<br><br><b>-n</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Numeric output. Displays capabilities in their numeric form rather than symbolic names.<br><br><b>-p <i>PID</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Process capabilities. Displays the capabilities of a running process identified by its Process ID (PID). This shows the Effective, Permitted, and Inheritable capability sets of the process.<br><br><b>-P</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Capability as a specific permission set string. When used for files, this option tries to output the capability as a permission set string, making it more human-readable.<br><br>


title: DESCRIPTION
content:
The <i>getcap</i> command is used to inspect file capabilities and, less commonly, process capabilities on a Linux system. Capabilities are a security feature that allows a process to be granted a subset of the privileges normally associated with the root user, rather than granting full root access. This mechanism enables more fine-grained control over permissions, reducing the attack surface compared to traditional SUID/SGID binaries.<br><br>When applied to files, capabilities allow non-root users to execute specific programs with certain elevated privileges. For example, a program might be granted the <i>CAP_NET_RAW</i> capability to create raw sockets without requiring the entire program to run as root. <i>getcap</i> reads the extended attributes of a file to display these assigned capabilities, showing how the system grants specific powers to executables. It is often used in conjunction with the <i>setcap</i> command, which is used to assign or remove capabilities from files. Understanding a file's capabilities is crucial for auditing security and troubleshooting permission-related issues.


title: CAVEATS
content:
Capabilities are supported by the Linux kernel from version 2.2 onwards and require filesystem support for extended attributes (e.g., ext2/3/4, XFS, Btrfs). NFS and some other network filesystems may not support them directly.<br><br>Incorrectly applied capabilities can introduce security vulnerabilities by granting unnecessary privileges to non-root users or programs. It is crucial to understand the implications of each capability.<br><br>The effectiveness of capabilities can be limited by kernel settings (e.g., sysctl kernel.grsecurity.rlimits_enforce).


title: SECURITY CONTEXT
content:
Capabilities are intrinsically linked to the security context of a file or process. For files, they are stored as extended attributes (<i>xattrs</i>). For processes, they exist in the process's credential structure. <i>getcap</i> provides visibility into these crucial security attributes, which are otherwise opaque to standard <i>ls -l</i> commands.


title: INTERACTION WITH SUID/SGID
content:
While capabilities offer a more granular alternative, SUID/SGID bits can still coexist. However, capabilities are generally preferred for specific privilege grants because they allow for auditing and restrict privileges to only what's necessary, whereas SUID grants full root privileges to the executing process.


title: HISTORY
content:
The concept of capabilities was introduced in Linux kernel 2.2 to replace the traditional coarse-grained superuser (root) model with a finer-grained permission system. It was developed as part of the <i>libcap</i> project, which provides the necessary user-space tools and libraries to manipulate and query process and file capabilities. The <i>getcap</i> command emerged as a vital component of this suite, allowing administrators and developers to inspect the privileges associated with executables, helping to audit and secure systems by reducing the reliance on SUID binaries. Its development has been intertwined with the evolution of Linux security mechanisms, aiming to provide more robust and controlled privilege management.


title: SEE ALSO
content:
<b>setcap</b>(8) - Set file capabilities, <b>cap_from_text</b>(3) - Convert textual representation of capabilities to internal form, <b>capabilities</b>(7) - Overview of Linux capabilities


title: PARAMETERS
content:
<b><b>--numeric</b>, <b>-n</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays UIDs/GIDs numerically instead of attempting to resolve them to user or group names. This can be useful when name resolution services are unavailable or when dealing with unmapped SIDs.<br><br><b><i>file...</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;One or more paths to files or directories located on a mounted CIFS/SMB filesystem for which to retrieve ACLs. The command will read and display the ACLs for each specified path.<br><br>


title: DESCRIPTION
content:
<b>getcifsacl</b> is a command-line utility used to display the Access Control Lists (ACLs) associated with files and directories on a CIFS/SMB filesystem mounted in Linux. Unlike POSIX ACLs which <b>getfacl</b> handles, <b>getcifsacl</b> specifically retrieves the Windows-style ACLs, providing a more accurate representation of permissions as seen from a Windows environment. This tool is essential for administrators and users who need to understand and debug permission issues on CIFS/SMB shares, especially when interacting with Active Directory or Windows servers. It reads the Security Descriptor from the specified file or directory and translates it into a human-readable format, detailing owner, group, and individual Access Control Entries (ACEs) including SIDs (Security Identifiers), permission types (allow/deny), and inheritance flags. It is part of the <i>cifs-utils</i> package.


title: CAVEATS
content:
This command is specific to CIFS/SMB mounted filesystems and will not function on other filesystem types (e.g., ext4, XFS).<br>The remote CIFS/SMB server must support CIFS ACLs for this command to function correctly.<br>Interpreting the output can sometimes be challenging due to complex SIDs and permission flags, especially when SIDs cannot be resolved to names.<br><b>getcifsacl</b> only <i>reads</i> ACLs; use <b>setcifsacl</b> to modify them.


title: HISTORY
content:
<b>getcifsacl</b> is a component of the <i>cifs-utils</i> suite, a collection of tools designed to manage the Linux CIFS client. Its development is closely tied to the evolution of the Linux kernel's CIFS client, which enabled deeper interoperability with Windows file servers. The command was introduced to bridge the gap between Linux's native permission model and Windows' ACL-based security, allowing Linux users to inspect and manage permissions on CIFS shares in a way that is consistent with Windows. This became increasingly important as Linux systems integrated more deeply into mixed-OS environments, requiring robust tools for managing cross-platform file access and security.


title: DESCRIPTION
content:
The <b>getcon</b> command is a specialized utility within the SELinux (Security-Enhanced Linux) framework, designed to retrieve and display the security context of the process that executes it. In SELinux, a security context is a label applied to every object (processes, files, network ports, etc.) that defines its security attributes, including the user, role, type, and optionally, sensitivity and category (for MLS/MCS systems). This context is fundamental to how SELinux enforces access control, determining what a process can and cannot do based on its own context and the contexts of other objects it tries to access.<br><br><b>getcon</b> is primarily used for debugging, scripting, or quickly verifying the security context of a running shell or application. Unlike commands like <i>ls -Z</i> or <i>ps -Z</i> which show contexts of files or other processes, <b>getcon</b> specifically reports the context of the current process, making it a direct tool for understanding the caller's privileges from an SELinux perspective. Its output is typically in the format <i>user:role:type:level</i>, providing a concise summary of the process's current security identity.


title: CAVEATS
content:
This command is only useful and will only produce meaningful output if SELinux is enabled and running on the system. If SELinux is disabled, it might return an error or a default unconfined context.<br><br><b>getcon</b> exclusively displays the security context of the <i>current process</i> (the shell or script from which it's executed). It cannot be used to query the contexts of other files, directories, or processes. For those purposes, related SELinux utilities like <i>ls -Z</i>, <i>ps -Z</i>, or <i>id -Z</i> should be used.<br><br>The output format is fixed and cannot be customized via command-line options.


title: OUTPUT FORMAT
content:
The output of <b>getcon</b> typically follows the format:<br><i>user:role:type:level</i><br>For example: <i>unconfined_u:unconfined_r:unconfined_t:s0</i><br>Where:<br><i>user</i>: Represents the SELinux user identity.<br><i>role</i>: Defines the role that the SELinux user is allowed to assume.<br><i>type</i>: The most crucial component, representing the domain for a process or the type for a file. This is the primary attribute used by policy rules to determine access.<br><i>level</i>: (Optional) Sensitivity and category information, relevant for Multi-Level Security (MLS) or Multi-Category Security (MCS) systems (e.g., s0, s0:c0.c1023).


title: HISTORY
content:
The <b>getcon</b> command emerged as part of the ongoing development of SELinux, a mandatory access control (MAC) security mechanism for Linux, primarily initiated by the National Security Agency (NSA) and later integrated into the Linux kernel and widely adopted by distributions like Red Hat Enterprise Linux. Its inclusion in the <i>libselinux-utils</i> package highlights its role as a fundamental utility for interacting with and understanding the SELinux security context system. Its design is intentionally minimalistic, reflecting its core purpose of providing a quick, straightforward way for users and scripts to query the current process's security identity within the SELinux security model.


title: PARAMETERS
content:
<b><b>-a</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays all supported configuration variables and their current values. This option allows users to see a comprehensive list of what <b>getconf</b> can query on their system.<br><br><b><i>name</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the name of the configuration variable to query. These names are typically uppercase and often prefixed with an underscore (e.g., <I>_SC_PAGESIZE</I>, <I>ARG_MAX</I>, <I>_POSIX_VERSION</I>). The output will be the value of this variable.<br><br><b><i>path</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;An optional pathname. When provided, <b>getconf</b> queries configuration variables that are specific to the file system on which the specified <I>path</I> resides. For example, variables like <I>_POSIX_NO_TRUNC</I> or <I>NAME_MAX</I> can vary per file system.<br><br>


title: DESCRIPTION
content:
The <b>getconf</b> command is a utility designed to retrieve and display the values of system configuration variables and limits. These variables typically conform to POSIX standards and provide crucial information about the operating environment, such as maximum file sizes, buffer sizes, process limits, and other system-wide or file-system-specific characteristics.<br><br>It serves as a command-line interface to the underlying <i>sysconf(3)</i> and <i>pathconf(3)</i> C library functions, making these system capabilities accessible for shell scripting and diagnostic purposes. Developers and system administrators use <b>getconf</b> to write portable scripts that adapt their behavior based on the system's capabilities and limitations, ensuring applications can function correctly across various Unix-like environments. For instance, one might query <i>ARG_MAX</i> to determine the maximum length of arguments to an <i>exec</i> family function, or <i>_POSIX_VDISABLE</i> to find the character used to disable special terminal characters.


title: CAVEATS
content:
Variable names are case-sensitive and must exactly match the standard definitions. If a variable is not recognized or not defined on the system, <b>getconf</b> may output 'undefined' or an error.<br>Not all variables listed in POSIX standards are necessarily defined or have meaningful values on every system. Compliance varies across implementations.<br>Some non-standard options, like <i>-v var</i> (a GNU extension), might exist in certain implementations but should be avoided for portability.<br>Variables queried without a <i>path</i> argument are system-wide, while those with a <i>path</i> argument are specific to that file system. Understanding this distinction is crucial for correct usage.


title: TYPES OF CONFIGURATION VARIABLES
content:
<b>getconf</b> can query two main types of configuration variables:<br><b>System-wide variables:</b> These apply to the entire operating system, such as <i>ARG_MAX</i> (maximum length of arguments to a command), <i>_POSIX_PAGESIZE</i> (system page size), or <i>LONG_BIT</i> (number of bits in a long integer). These are queried by providing only the <i>name</i> argument.<br><b>Path-specific variables:</b> These vary depending on the file system a given path resides on, such as <i>NAME_MAX</i> (maximum filename length in a directory), <i>PATH_MAX</i> (maximum pathname length), or <i>_POSIX_NO_TRUNC</i> (behavior for truncated filenames). These require both the <i>name</i> and <i>path</i> arguments.


title: PORTABILITY AND SCRIPTING
content:
One of the primary uses of <b>getconf</b> is in writing portable shell scripts. By querying system limits rather than hardcoding values, scripts can adapt to different environments. For example, a script might check <i>ARG_MAX</i> before constructing a very long command line, or <i>NAME_MAX</i> before creating files with extremely long names, thus avoiding potential errors or unexpected behavior across various Unix-like systems.


title: HISTORY
content:
<b>getconf</b> is an integral part of the POSIX.1 standard, providing a portable command-line interface to query system and path configuration values that are otherwise accessible through the <i>sysconf()</i> and <i>pathconf()</i> C library functions. Its development is closely tied to the evolution of the POSIX standard, which aims to ensure application portability across different Unix-like operating systems. It was introduced to give shell scripts and command-line users a standardized way to access system characteristics, mirroring the capabilities available to compiled programs. This allows for robust and adaptive scripting that can, for instance, determine maximum path lengths or argument sizes before attempting operations that might fail due to system limitations.


title: PARAMETERS
content:
<b><b>-o</b> &lt;output_file&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the path for the output file where the extracted boot image will be saved. If omitted, the output is directed to standard output (<b>stdout</b>).<br><br><b><b>-a</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Extracts <i>all</i> boot images found within the specified ISO. Each image will be named based on a pattern (e.g., boot.img.0, boot.img.1).<br><br><b><b>-i</b> &lt;image_number&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Selects a specific boot image to extract when multiple are present in the ISO. Image numbers typically start from 0.<br><br><b><b>-h</b>, <b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a brief help message and exits.<br><br><b><b>-v</b>, <b>--version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays the program's version information and exits.<br><br>


title: DESCRIPTION
content:
<b>geteltorito</b> is a specialized utility designed to extract the bootable El Torito image from an ISO 9660 or UDF CD/DVD image. The El Torito specification defines how a CD-ROM can be made bootable, often mimicking a floppy disk, hard disk, or a non-emulated boot sector. This tool is invaluable when you need to create a bootable USB drive from a CD/DVD ISO image, or when you wish to analyze or manipulate the boot image itself. It can identify multiple boot images within an ISO and allows you to select which one to extract, or extract all of them.<br><br>The extracted image is typically a raw disk image (e.g., a floppy disk image, a hard disk image, or a non-emulated boot sector) that can then be written directly to a device (like a USB stick) using tools such as <b>dd</b>. It is commonly found as part of packages that deal with bootloaders or ISO image manipulation, serving as a crucial step in the process of transferring bootable content from optical media to other storage devices.


title: CAVEATS
content:
Requires the input ISO image to be compliant with the El Torito bootable CD-ROM specification.<br>May not correctly identify or extract boot images from non-standard or proprietary ISO formats.<br>The extracted image is a raw binary image and must be written to a suitable device (e.g., USB drive) using tools like <b>dd</b> to become bootable. It does not modify the original ISO file.


title: USAGE EXAMPLES
content:
<i><br><b>Extracting the first boot image to a file named 'boot.img':</b><br></i>geteltorito -o boot.img my_iso.iso<br><br><i><b>Writing the extracted image to a USB stick (replace /dev/sdX with your actual device):</b><br></i>sudo dd if=boot.img of=/dev/sdX bs=4M status=progress<br><i>(Always double-check the target device path, as incorrect usage of <b>dd</b> can lead to data loss.)</i><br><br><i><b>Listing available boot images and their details (often prints to stderr):</b><br></i>geteltorito my_iso.iso<br><i>Alternatively, for more detailed information about boot images within an ISO:<br></i>isoinfo -d -i my_iso.iso


title: HISTORY
content:
<b>geteltorito</b> is often distributed as part of the <b>syslinux</b> project or other bootloader utility suites. Its purpose is to facilitate the use of El Torito boot images, which became standard for making CDs bootable in the mid-1990s. Its development closely tracks the need for extracting and deploying these bootable images, especially for creating bootable USB drives as optical drives became less common, making it a vital component in modern bootable media creation workflows.


title: PARAMETERS
content:
<b><i>DATABASE</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The name of the database to query. Common databases include <b>passwd</b> (user accounts), <b>group</b> (user groups), <b>hosts</b> (hostnames and IP addresses), <b>services</b> (network services), <b>protocols</b> (network protocols), <b>rpc</b> (RPC program numbers), and <b>netgroup</b> (network groups).<br><br><b><i>KEY</i>...</b><br>&nbsp;&nbsp;&nbsp;&nbsp;An optional argument specifying one or more specific entries to look up within the <i>DATABASE</i>. For example, a username for <b>passwd</b>, an IP address for <b>hosts</b>, or a service name for <b>services</b>. If omitted, <i>getent</i> will attempt to list all entries in the specified database (if supported by that database type and its configured sources).<br><br><b><b>-s</b> <i>CONFIG_STR</i>, <b>--by-source=</b><i>CONFIG_STR</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify an alternative source configuration string for the lookup. This string directly defines the NSS sources to consult for this query, overriding the default behavior defined in <i>/etc/nsswitch.conf</i> for the specified <i>DATABASE</i>. This option is less commonly used than relying on the standard NSS configuration.<br><br>


title: DESCRIPTION
content:
<i>getent</i> is a command-line utility used to retrieve entries from the Name Service Switch (NSS) databases. It provides a unified interface for querying various system databases, such as user accounts, groups, hostnames, services, and protocols. Instead of directly parsing configuration files like <i>/etc/passwd</i> or <i>/etc/hosts</i>, <i>getent</i> consults the system's NSS configuration (typically defined in <i>/etc/nsswitch.conf</i>) to determine the order and sources for database lookups. This allows it to fetch information transparently from local files, DNS, LDAP, NIS, or other configured services.<br><br>This command is invaluable for system administrators and scripts that need to reliably resolve system entities, as it reflects the same lookup logic that system libraries use. It can query for a specific key within a database or, for some databases, list all available entries.


title: CAVEATS
content:
<ul><li><i>getent</i>'s behavior is entirely dependent on the system's <i>/etc/nsswitch.conf</i> configuration. If NSS sources are misconfigured or external services are unavailable, <i>getent</i> may return incomplete results or exhibit timeouts.</li><li>Listing all entries (e.g., <b>getent passwd</b> without a key) can be very slow and resource-intensive if the database is large and sourced from remote services like LDAP. Some databases (e.g., <b>netgroup</b>) may not support enumeration without a specific key.</li><li>It requires appropriate permissions to read <i>/etc/nsswitch.conf</i> and access underlying data sources.</li></ul>


title: ENUMERATION BEHAVIOR
content:
While <i>getent</i> can list all entries for databases like <b>passwd</b> and <b>group</b> when no key is provided, this functionality depends on the specific database type and its configured NSS sources. Not all databases support full enumeration; for example, <b>netgroup</b> typically requires a key. Enumerating a large database from remote sources can take a significant amount of time and consume network resources.


title: <I>NSSWITCH.CONF</I> INTEGRATION
content:
The strength of <i>getent</i> lies in its direct consultation of <i>/etc/nsswitch.conf</i>. This file dictates the order and types of sources (e.g., <b>files</b>, <b>dns</b>, <b>ldap</b>, <b>nis</b>) to be queried for each database. This makes <i>getent</i> an indispensable tool for diagnosing and verifying the correct operation of your system's Name Service Switch configuration, reflecting exactly how system libraries will resolve entities.


title: HISTORY
content:
<i>getent</i> is part of the GNU C Library (glibc) and was developed as a fundamental component of the Name Service Switch (NSS) architecture. NSS emerged to provide a consistent and extensible framework for resolving various system entities across diverse data sources (local files, network services like NIS, LDAP, DNS, etc.). <i>getent</i>'s existence allows administrators and applications to leverage this standardized lookup mechanism, abstracting away the complexity of underlying data storage. Its core functionality has remained stable and essential for Linux systems since its introduction.


title: SYNOPSIS
content:
<pre>getfacl [<i>OPTIONS</i>] <i>FILE</i>...</pre><br>Example: <i>getfacl</i> <i>myfile.txt</i><br>Example: <i>getfacl</i> <i>-R</i> <i>/data/project</i>


title: PARAMETERS
content:
<b>-a, --access</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display the file access ACL. This is the default if neither -a nor -d is specified.<br><br><b>-d, --default</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display the default ACL for directories. Default ACLs are inherited by newly created objects within that directory.<br><br><b>-D, --omit-header</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Do not display the comment header (file name, owner, group).<br><br><b>-p, --physical</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Do not follow symbolic links; display ACLs of the symbolic link itself instead of the target file.<br><br><b>-R, --recursive</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Recursively list ACLs of subdirectories and their contents.<br><br><b>-s, --skip-base</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Skip the base ACL entries (user::, group::, other::) from the output.<br><br><b>-t, --tabular</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Use a tabular output format for easier parsing, showing only effective rights.<br><br><b>--all-effective</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Print all effective rights, combining access and default ACLs with their masks applied.<br><br><b>--absolute-names</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Do not strip leading '/' in pathnames when listing files.<br><br><b>-v, --version</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display version information and exit.<br><br><b>-h, --help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display a help message and exit.<br><br>


title: DESCRIPTION
content:
The <i>getfacl</i> command is used to retrieve and display the Access Control Lists (ACLs) of files and directories. Traditional Unix permissions offer a limited set of permissions for the owner, owning group, and others. ACLs extend this by allowing more granular control, enabling you to define specific permissions for additional users and groups beyond the standard three. When invoked, <i>getfacl</i> outputs a detailed list of permissions, including the owning user, owning group, and then specific entries for named users, named groups, and the effective rights mask. This command is crucial for understanding the exact access rights for a file, especially in environments where standard permissions are insufficient. It complements the <i>setfacl</i> command, which is used to modify these ACLs. <i>getfacl</i> is particularly useful for auditing security configurations and troubleshooting access issues on filesystems that support ACLs, such as Ext3, Ext4, XFS, and Btrfs.


title: CAVEATS
content:
<b>Filesystem Support</b>: ACLs are only supported by certain filesystems (e.g., Ext3, Ext4, XFS, Btrfs, NFSv4). Older filesystems or those mounted without the 'acl' option enabled will not properly store or display ACLs.<br><b>Mount Options</b>: For ACLs to function, the filesystem often needs to be mounted with the <i>acl</i> option explicitly enabled in <i>/etc/fstab</i> or via the <i>mount</i> command.<br><b>Interoperability</b>: Files with ACLs moved to or accessed from systems that do not support ACLs may lose their extended permissions, reverting to traditional Unix permissions.<br><b>Complexity</b>: While powerful, managing ACLs can add complexity to permission management, especially in large environments, and requires careful consideration to avoid unintended access.


title: UNDERSTANDING <I>GETFACL</I> OUTPUT
content:
The output of <i>getfacl</i> typically includes a header with the file name, owner, and owning group. Below this, it lists ACL entries, usually in the format: <br><br><i>user::rw-</i> (owner)<br><i>group::r--</i> (owning group)<br><i>other::---</i> (others)<br><i>user:john:rwx</i> (named user 'john')<br><i>group:devs:r-x</i> (named group 'devs')<br><i>mask::rwx</i> (effective rights mask)<br><br>The 'mask' entry specifies the maximum permissions that can be granted to any named user, named group, or to the owning group. The effective permissions for any entry are the logical AND of its specified permissions and the mask permissions. If the mask is more restrictive than an entry's specified permissions, the mask will limit the effective rights.


title: DEFAULT ACLS
content:
For directories, <i>getfacl</i> can also display 'default' ACLs using the <i>-d</i> option. Default ACLs are not directly applied to the directory itself but are inherited by new files and subdirectories created within it. This allows for automatic propagation of specific access controls to new content, simplifying management for shared folders.


title: HISTORY
content:
The concept of Access Control Lists (ACLs) on Unix-like systems gained prominence with the POSIX.1e draft standard, which aimed to provide a more granular permission model than the traditional owner/group/other permissions. Although POSIX.1e itself was never finalized, its influence led to the adoption of ACL implementations in various Unix and Linux distributions. The <i>getfacl</i> command, along with its counterpart <i>setfacl</i>, is part of the `acl` package, which provides utilities for managing these extended ACLs on Linux. This development addressed the growing need for finer-grained access control in server environments and shared storage systems, allowing administrators to specify permissions for multiple users and groups on a single file or directory, significantly enhancing security and flexibility beyond the UGO (User, Group, Other) model.


title: SYNOPSIS
content:
<b>geth</b> [<i>OPTIONS</i>]<br><b>geth</b> <i><COMMAND></i> [<i>ARGS...</i>]<br><b>geth</b> <b>attach</b> [<i>URL</i>]<br><b>geth</b> <b>console</b> [<i>OPTIONS</i>]<br><b>geth</b> <b>init</b> <i>&lt;GENESIS_FILE&gt;</i><br><b>geth</b> <b>removedb</b>


title: PARAMETERS
content:
<b><b>--datadir</b> <i>&lt;path&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Path to the root data directory for the node.<br><br><b><b>--networkid</b> <i>&lt;id&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Explicitly set the network ID (e.g., 1 for mainnet, 3 for Ropsten).<br><br><b><b>--syncmode</b> <i>&lt;mode&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Blockchain synchronization mode: <i>full</i>, <i>fast</i>, <i>snap</i>, or <i>light</i>.<br><br><b><b>--mine</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enable CPU mining.<br><br><b><b>--etherbase</b> <i>&lt;address&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Public address for block rewards (coinbase).<br><br><b><b>--rpc</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enable the HTTP RPC server for client applications.<br><br><b><b>--rpcaddr</b> <i>&lt;ip&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;HTTP RPC server listening interface (default: <i>localhost</i>).<br><br><b><b>--rpcport</b> <i>&lt;port&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;HTTP RPC server listening port (default: <i>8545</i>).<br><br><b><b>--rpccorsdomain</b> <i>&lt;domains&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Comma-separated list of domains to accept cross-origin requests from.<br><br><b><b>--ws</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enable the WS-RPC server (WebSocket).<br><br><b><b>--wsaddr</b> <i>&lt;ip&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;WS-RPC server listening interface (default: <i>localhost</i>).<br><br><b><b>--wsport</b> <i>&lt;port&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;WS-RPC server listening port (default: <i>8546</i>).<br><br><b><b>--ipcdisable</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Disable the IPC (Inter-Process Communication) interface.<br><br><b><b>--ipcpath</b> <i>&lt;path&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Filename for IPC socket/pipe.<br><br><b><b>--maxpeers</b> <i>&lt;n&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Maximum number of network peers (default: <i>50</i>).<br><br><b><b>--verbosity</b> <i>&lt;level&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Logging verbosity (0=silent, 1=error, 2=warn, 3=info, 4=debug, 5=trace).<br><br><b><b>--console</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Start the interactive JavaScript console.<br><br><b><b>--attach</b> <i>&lt;url&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Attach to a running <i>geth</i> node via RPC/IPC URL.<br><br><b><b>--unlock</b> <i>&lt;addresses&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Comma-separated list of accounts to unlock during startup.<br><br><b><b>--password</b> <i>&lt;file&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;File containing password(s) for unlocked accounts.<br><br><b><b>--allow-insecure-unlock</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Allow insecure account unlocking via HTTP RPC (use with caution).<br><br><b><b>--dev</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enable developer mode with a pre-configured private network.<br><br><b><b>--txpool.globalslots</b> <i>&lt;n&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Maximum number of executable transaction slots for the global transaction pool.<br><br>


title: DESCRIPTION
content:
<i>geth</i> is the official command-line interface for running an Ethereum node implemented in Go. It allows users to connect to the Ethereum network (mainnet, testnets), synchronize the blockchain, manage accounts, send transactions, deploy smart contracts, and interact with the Ethereum Virtual Machine (EVM). It serves as a full node, light node, or even a remote client to an existing node. <i>geth</i> is essential for developers building on Ethereum, miners, and users wanting to have a direct interface with the decentralized network. It provides a JavaScript console for interactive operations and exposes various RPC interfaces (HTTP, WebSockets, IPC) for programmatic access, making it a cornerstone of the Ethereum ecosystem.


title: CAVEATS
content:
Running a <i>geth</i> full node can be resource-intensive, requiring significant disk space (hundreds of GBs) and RAM. Unlocking accounts via command-line flags or insecure RPC interfaces poses security risks and should be avoided in production environments. Synchronization can take a long time, especially for a full sync from scratch. Command options and default behaviors may evolve with future protocol upgrades.


title: RPC AND IPC INTERFACES
content:
<i>geth</i> exposes powerful RPC (Remote Procedure Call) interfaces over HTTP, WebSockets (WS), and IPC (Inter-Process Communication). These interfaces allow developers and applications to interact programmatically with the Ethereum blockchain, query node status, manage accounts, send transactions, and deploy smart contracts. IPC is generally preferred for local applications due to its higher security and performance, while HTTP/WS are used for remote or web-based interactions.


title: SYNCHRONIZATION MODES
content:
<i>geth</i> offers several blockchain synchronization modes:<br><b>Full Sync:</b> Downloads and validates all blocks from genesis, including executing all transactions. Requires significant disk space and time.<br><b>Fast Sync:</b> Downloads block headers and receipts, then state trie data, skipping transaction execution for older blocks. Faster and less demanding than full sync.<br><b>Snap Sync:</b> The default and most efficient sync mode, it downloads recent state snapshots directly from peers, significantly reducing sync time and disk usage.<br><b>Light Sync:</b> Downloads only block headers and relies on peer nodes to serve state information on demand, requiring minimal local storage but relying heavily on network connectivity.


title: ACCOUNT MANAGEMENT
content:
<i>geth</i> provides robust tools for managing Ethereum accounts. Users can create new accounts, import existing ones, and manage their private keys securely, typically encrypted with a passphrase within the <i>geth</i> <i>datadir</i>. Accounts are used for signing transactions, participating in mining, and interacting with smart contracts. While accounts can be unlocked for automation, careful security practices are crucial to protect private keys.


title: HISTORY
content:
<i>geth</i> (Go Ethereum) is the original and most widely used client implementation of the Ethereum protocol, developed by the Ethereum Foundation. It was launched alongside the Ethereum network in 2015. Over the years, <i>geth</i> has continuously evolved, incorporating major protocol upgrades (hard forks) like Homestead, Metropolis, Constantinople, Istanbul, Berlin, London, and Shanghai. Key developments include various synchronization modes (<i>fast</i>, <i>light</i>, <i>snap</i>) to improve user accessibility and reduce resource demands, as well as robust RPC interfaces crucial for dApp development and ecosystem tooling.


title: SYNOPSIS
content:
Since <b>gethostip</b> is typically a custom script, its syntax varies. A common invocation pattern would be:<br><b>gethostip</b> <i><hostname></i> [<i>options</i>]<br><br>Where <i><hostname></i> is the target domain name or host.


title: PARAMETERS
content:
<b><i><hostname></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The target hostname or domain name to resolve.<br><br><b><b>-4</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>(Optional)</i> Force resolution to IPv4 addresses only.<br><br><b><b>-6</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>(Optional)</i> Force resolution to IPv6 addresses only.<br><br><b><b>-a</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>(Optional)</i> Display all resolved IP addresses, not just the first one found.<br><br>


title: DESCRIPTION
content:
The term <b>gethostip</b> does not refer to a standard, pre-installed Linux command. Instead, it commonly represents a user-created <i>shell script</i> or <i>function</i> designed to quickly retrieve the IP address (or addresses) associated with a given hostname. Users often implement this functionality by wrapping existing DNS lookup utilities such as <b>host</b>, <b>dig</b>, or <b>nslookup</b>.<br><br>The primary purpose of such a script is to simplify the process of obtaining IP addresses, whether IPv4 or IPv6, without needing to remember the specific syntax or parse the potentially verbose output of the underlying commands. It's a convenience utility, making DNS resolution more accessible for scripting or command-line usage.


title: CAVEATS
content:
<i>Non-Standard Command</i>: <b>gethostip</b> is <i>not</i> a standard Linux command; it is a conceptual name for a user-defined script. Its existence, behavior, and options depend entirely on how a user has implemented it. <br><br><i>Underlying Tools</i>: Its functionality relies on other installed DNS resolution tools (e.g., <b>host</b>, <b>dig</b>, <b>nslookup</b>) and the system's DNS configuration. If these tools are not available or DNS resolution fails, the script will not function. <br><br><i>Output Format</i>: The output format of a custom <b>gethostip</b> script can vary widely depending on its implementation, unlike standard commands with well-defined outputs.


title: COMMON IMPLEMENTATION EXAMPLE (BASH)
content:
A very basic example of how a <b>gethostip</b> script might be implemented using the <b>host</b> command. Note that this example is provided as plain text due to tag limitations:<br><br>#!/bin/bash<br># gethostip script<br><br>if [ -z \"$1\" ]; then<br>  echo \"Usage: $0 <hostname>\"<br>  exit 1<br>fi<br><br>host_output=$(host \"$1\")<br><br>if echo \"$host_output\" | grep -q \"has address\"; then<br>  echo \"$host_output\" | awk '/has address/ {print $4}' | head -n 1<br>elif echo \"$host_output\" | grep -q \"has IPv6 address\"; then<br>  echo \"$host_output\" | awk '/has IPv6 address/ {print $5}' | head -n 1<br>else<br>  echo \"Could not resolve $1\"<br>  exit 1<br>fi<br><br>This example demonstrates extracting the IP address, but a real-world script might include more robust error handling, option parsing (e.g., for IPv4/IPv6), and potentially use <b>dig</b> for more control.


title: ROLE IN SCRIPTING
content:
Custom <b>gethostip</b> scripts are often used within larger shell scripts or automation workflows where an IP address is needed from a hostname without human interaction. They provide a convenient abstraction layer over complex DNS lookup commands, allowing for cleaner and more readable script logic.


title: HISTORY
content:
The concept of a simple command to resolve a hostname to an IP address has existed since the early days of networking. While no official <b>gethostip</b> command exists, the need for this quick lookup led users to create custom shell scripts or functions. These often evolved from direct usage of tools like <b>nslookup</b> (popular in earlier Unix/Linux systems) and later shifted towards <b>host</b> or <b>dig</b> due to their cleaner output and more modern capabilities. The naming convention "gethostip" likely arose organically as a descriptive identifier for such a common utility.


title: DESCRIPTION
content:
The <b>getkeycodes</b> command is a utility from the <I>kbd</I> package, designed to output the current scancode-to-keycode mapping table maintained by the Linux kernel. When a key is pressed on a keyboard, it sends a hardware-specific <I>scancode</I>. The kernel then translates this scancode into a more abstract <I>keycode</I>, which represents the logical meaning of the key (e.g., "A", "Enter", "F1").<br><br>This command provides a diagnostic view of how the kernel interprets these raw hardware signals. It is particularly useful for debugging keyboard issues on the Linux console, for understanding custom key layouts, or for verifying the effects of changes made with the <I>setkeycodes</I> command. The output consists of pairs of hexadecimal scancodes and their corresponding decimal keycodes, offering a direct insight into the low-level keyboard configuration.


title: CAVEATS
content:
<I>getkeycodes</I> displays the mapping for the <I>console</I> keyboard driver. It does <B>not</B> affect or display the keyboard mapping used within graphical environments like X11 or Wayland, which manage their own input devices and keymaps independently.<br><br>This command is purely informational; it reads and prints the current state and does not modify any system settings.


title: UNDERSTANDING SCANCODES AND KEYCODES
content:
A <I>scancode</I> is a raw value generated by the keyboard hardware when a key is pressed or released. These values are specific to the keyboard's internal design.<br><br>A <I>keycode</I>, on the other hand, is a kernel-level representation of a key's logical function, independent of the specific hardware scancode. The kernel uses a mapping table to translate scancodes into keycodes, which are then used by applications. <I>getkeycodes</I> reveals this crucial translation layer.


title: OUTPUT FORMAT
content:
The output of <I>getkeycodes</I> consists of lines, each containing two numbers separated by a space: the first is the hexadecimal <I>scancode</I>, and the second is its corresponding decimal <I>keycode</I>. For example, "0x1e 48" means that scancode 0x1e (typically 'a') maps to keycode 48.


title: HISTORY
content:
The <I>getkeycodes</I> command has been a stable part of the <I>kbd</I> (keyboard) utilities for Linux for many years. The <I>kbd</I> project focuses on managing the Linux console's keyboard, fonts, and screen modes. Its purpose as a diagnostic tool for the kernel's scancode-to-keycode mapping has remained consistent since its inception, reflecting the underlying need for a low-level understanding of hardware input on the console.


title: SYNOPSIS
content:
As <i>getnpusers.py</i> is a custom script, its synopsis is not standardized. However, typical invocation would involve the Python interpreter, followed by the script name and any custom arguments or options it expects. A generic example might look like:<br><br><b>python getnpusers.py</b> [<i>options</i>] [<i>arguments</i>]<br><br>Users should check the script's internal documentation (e.g., by running it with <i>--help</i> or inspecting the source code) for its specific syntax and usage.


title: PARAMETERS
content:
<b>Custom Parameters</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Since this is a custom script, there are no universally defined parameters. However, similar custom scripts often accept parameters to specify:<br><b>--host</b> <i><hostname_or_ip></i>: The target host or server to query.<br><b>--port</b> <i><number></i>: The port number for communication with the target service.<br><b>--username</b> <i><user></i>: A username for authentication to the target system.<br><b>--password</b> <i><pass></i>: The password for authentication.<br><b>--output</b> <i><format></i>: Desired output format (e.g., json, csv, text).<br><b>--filter</b> <i><expression></i>: Criteria to filter the retrieved users.<br><b>--verbose</b>: Enable verbose output for debugging.<br><b>--help</b>: Display usage information and available options.<br><br><i>These are illustrative examples only. The actual parameters depend entirely on the script's implementation.</i><br><br>


title: DESCRIPTION
content:
The <i>getnpusers.py</i> command is not a standard Linux utility found in typical distributions. It is almost certainly a custom Python script developed for a specific purpose, such as retrieving user information from a particular system, service, or network component. The 'np' in its name could potentially stand for 'Network Policy', 'Named Pipe', 'NPS (Network Policy Server)', or another domain-specific abbreviation.<br><br>Its exact functionality, the type of user data it retrieves, its input requirements, and its output format are entirely dependent on how the script has been implemented by its creator. Common use cases for such a script might include querying user accounts from a directory service (like LDAP or Active Directory), pulling user sessions from network devices, or extracting user lists from specific application logs or databases. To understand its precise operation, one would need to inspect the script's source code or consult its documentation, if available.


title: CAVEATS
content:
<b>Custom Script:</b> This is not a standard system utility. Its presence, functionality, and behavior are specific to the environment where it was deployed.<br><b>Dependency on Implementation:</b> Without access to the script's source code or its specific documentation, its exact purpose, required inputs, and expected outputs are unknown.<br><b>Security Implications:</b> If the script handles credentials or retrieves sensitive user data, its security should be thoroughly vetted. Ensure it's sourced from a trusted origin and handles data securely.<br><b>Maintenance:</b> Custom scripts may not be regularly updated or maintained, potentially leading to issues with newer system versions or security vulnerabilities.<br>


title: HOW TO UNDERSTAND THE SCRIPT
content:
The most reliable way to understand <i>getnpusers.py</i> is to examine its source code directly. This can often be done using commands like <b>cat getnpusers.py</b> or opening it in a text editor. Look for comments, `argparse` definitions, or usage messages within the script. Additionally, running the script with <b>python getnpusers.py --help</b> (if implemented) is often the quickest way to see its usage.


title: HISTORY
content:
As <i>getnpusers.py</i> is a custom script, it does not have a public or documented history like standard Linux commands. Its development and usage history are specific to the organization or individual who created and deployed it.


title: SEE ALSO
content:
who(1): Show who is logged on., w(1): Show who is logged on and what they are doing., users(1): Print the user names of users currently logged in., id(1): Print real and effective user and group IDs., getent(1): Get entries from Name Service Switch libraries (e.g., for users or groups).


title: PARAMETERS
content:
<b><b>-o</b> <i>shortopts</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<b>Short Options</b>.<br>Specifies a string of valid short option characters. If a character is followed by a colon (<b>:</b>), the option requires an argument. If followed by two colons (<b>::</b>), the option takes an optional argument.<br><br><b><b>-l</b> <i>longopts</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<b>Long Options</b>.<br>Specifies a comma-separated list of valid long option names. If an option name is followed by a colon (<b>:</b>), it requires an argument. If followed by two colons (<b>::</b>), it takes an optional argument.<br><br><b><b>-n</b> <i>progname</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<b>Program Name</b>.<br>The program name to use in error messages. Defaults to <i>getopt</i>.<br><br><b><b>-q</b>, <b>--quiet</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<b>Quiet Mode</b>.<br>Suppresses error messages (e.g., for unrecognized options).<br><br><b><b>-u</b>, <b>--unquoted</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<b>Unquoted Output</b>.<br>Do not quote the output. (Dangerous for arguments with spaces or shell meta-characters).<br><br><b><b>-s</b> <i>shell</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<b>Shell Quoting Style</b>.<br>Sets the quoting style for the output. Typically <b>sh</b> (default) or <b>csh</b>.<br><br><b><b>-V</b>, <b>--version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<b>Version Information</b>.<br>Print version information and exit.<br><br><b><b>-h</b>, <b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<b>Help Information</b>.<br>Print help message and exit.<br><br>


title: DESCRIPTION
content:
<i>getopt</i> is a utility designed to parse command-line options and parameters for shell scripts. It reorders the arguments so that options are processed first, followed by non-option arguments, and properly handles quoted arguments. This allows scripts to use standard option parsing conventions (e.g., <b>-a</b>, <b>--long-option</b>).<br><br>The command generates a reformatted argument string that can be used with <b>eval set -- "$(getopt ...)"</b>. This is particularly useful for robust script development, as it simplifies the parsing logic and ensures compatibility with standard UNIX option conventions. It supports both short options (e.g., <b>-f</b>) and long options (e.g., <b>--file</b>). Unlike the <i>getopts</i> shell builtin, <i>getopt</i> is an external command and can handle long options and complex argument reordering.<br><br>It is crucial for scripts that need to adhere to standard command-line interfaces, allowing them to accept options with or without arguments, and to separate them from positional parameters gracefully.


title: CAVEATS
content:
<i>getopt</i> is an external command, requiring a subprocess call, which can be slightly slower than shell builtins. For simpler cases, the <i>getopts</i> shell builtin is often preferred, but it does not support long options.<br><br>The output of <i>getopt</i> must typically be <b>eval</b>uated and <b>set --</b> to correctly re-assign the shell's positional parameters, which can be a source of quoting issues if not handled carefully, especially with the original <i>getopt</i>. <b>GNU</b> <i>getopt</i> is much more robust in this regard.<br><br>The original <i>getopt</i> utility had limitations with arguments containing spaces; <b>GNU</b> <i>getopt</i> (common on Linux) largely overcomes this with proper quoting.


title: TYPICAL USAGE PATTERN
content:
Shell scripts commonly use <i>getopt</i> in conjunction with <b>eval</b> and <b>set --</b> to parse arguments. A typical pattern is:<br><br><b>TEMP=$(getopt -o "a:bc" -l "alpha:,beta,gamma" -n "$0" -- "$@")</b><br><b>if [ $? -ne 0 ]; then exit 1; fi</b><br><b>eval set -- "$TEMP"</b><br><b>while true; do</b><br><b>  case "$1" in</b><br><b>    -a|--alpha)</b><br><b>      ARG_A="$2"; shift 2;;</b><br><b>    -b|--beta)</b><br><b>      ARG_B=true; shift;;</b><br><b>    -c|--gamma)</b><br><b>      ARG_C=true; shift;;</b><br><b>    --) shift; break;;</b><br><b>    *) echo "Internal error!"; exit 1;;</b><br><b>  esac</b><br><b>done</b><br><br>This pattern safely reorders and parses arguments, making subsequent <b>case</b> statements straightforward.


title: HISTORY
content:
The original <i>getopt</i> utility was developed for Unix systems to standardize command-line argument parsing. It had limitations, particularly with complex arguments and quoting. The more robust <b>GNU</b> <i>getopt</i> was developed as part of the GNU project to address these shortcomings, notably by providing better handling of spaces in arguments and supporting long options. Modern Linux distributions almost exclusively use the <b>GNU</b> version, which has become a de-facto standard for parsing options in shell scripts due to its power and flexibility compared to its predecessor or the simpler <i>getopts</i> shell builtin.


title: PARAMETERS
content:
<b>optstring</b><br>&nbsp;&nbsp;&nbsp;&nbsp;The `<b>optstring</b>` defines valid options and whether they require an argument.<br>Characters in `<b>optstring</b>` represent valid options (e.g., `<i>"ab:c"</i>` means `<i>-a</i>`, `<i>-b</i>` with an argument, and `<i>-c</i>` are valid).<br>A colon `<b>:</b>` immediately following an option character indicates that it requires an argument.<br>A leading colon `<b>:</b>` in `<b>optstring</b>` enables "silent error reporting", preventing `<b>getopts</b>` from printing error messages for unknown options or missing arguments; instead, `<b>OPTARG</b>` and `<b>name</b>` are set specifically to indicate the error.<br><br><b>name</b><br>&nbsp;&nbsp;&nbsp;&nbsp;The `<b>name</b>` of a shell variable that `<b>getopts</b>` will set to the current option character found (e.g., `<i>'a'</i>`, `<i>'b'</i>`, `<i>'?'</i>`, `<i>':'</i>`).<br><br><b>arg...</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Optional list of arguments to parse. If omitted, `<b>getopts</b>` parses the script's positional parameters (i.e., `<i>$1</i>`, `<i>$2</i>`, ...).<br><br>


title: DESCRIPTION
content:
<i><b>getopts</b></i> is a built-in shell command (commonly in Bash, ksh, zsh) used for parsing command-line options and arguments passed to shell scripts.<br>It provides a standardized and portable way to handle options following Unix conventions (e.g., <i>-a</i>, <i>-b value</i>).<br>The command iterates through the provided arguments, setting a specified variable (often `<b>option_char</b>`) to the current option character found.<br>If an option requires an argument, its value is placed in the `<b>OPTARG</b>` shell variable.<br>Additionally, `<b>OPTIND</b>` is a shell variable maintained by `<b>getopts</b>` that tracks the index of the next argument to be processed.<br>This mechanism simplifies the development of robust scripts that accept flexible command-line input, similar to standard utilities.


title: CAVEATS
content:
<i><b>getopts</b></i> is a shell built-in, so its exact behavior may vary slightly between different shells (e.g., Bash, ksh, zsh).<br>It does not directly support long options like `<i>--help</i>`; for such cases, the external `<b>getopt(1)</b>` utility or manual parsing is generally required.<br>The `<b>OPTIND</b>` variable must be reset to 1 if `<b>getopts</b>` is intended to process a new set of arguments or if it's called multiple times within the same shell script instance to parse different argument lists.


title: SPECIAL VARIABLES
content:
`<b>getopts</b>` interacts with and modifies specific shell variables during its execution:<br><i><b>OPTIND</b></i>: The index of the next argument to be processed. It is initialized to 1 when a shell script starts or when the shell is invoked. It should be reset to 1 if `<b>getopts</b>` is called multiple times within the same script.<br><i><b>OPTARG</b></i>: Contains the argument of the option found, if the option requires one. For example, if `<i>-f filename</i>` is parsed and `<i>f:</i>` is in `<b>optstring</b>`, then `<b>OPTARG</b>` will hold `<i>filename</i>`.<br><i><b>name</b></i> (the variable passed to `<b>getopts</b>`): Stores the option character itself. If an invalid option is found, `<i>'?'</i>` is stored. If a required argument is missing (and `<b>optstring</b>` does not start with `<i>:</i>`), `<i>'?'</i>` is stored and an error message is printed. If `<b>optstring</b>` starts with `<i>:</i>` (silent error mode), `<i>':'</i>` is stored for a missing argument and `<b>OPTARG</b>` holds the option character (e.g., `<i>'f'</i>` for `<i>-f</i>`).


title: COMMON USAGE PATTERN
content:
`<b>getopts</b>` is typically used within a `<i>while</i>` loop to process all options:<br>`<i>while getopts optstring name; do<br> &nbsp;&nbsp;case "$name" in<br> &nbsp;&nbsp;&nbsp;&nbsp;a) echo "Option -a chosen";;<br> &nbsp;&nbsp;&nbsp;&nbsp;b) echo "Option -b with argument $OPTARG";;<br> &nbsp;&nbsp;&nbsp;&nbsp;\?) echo "Invalid option -$OPTARG"; exit 1;;<br> &nbsp;&nbsp;&nbsp;&nbsp;:) echo "Option -$OPTARG requires an argument"; exit 1;;<br> &nbsp;&nbsp;esac<br>done</i>`<br><br>After the loop, `<i>shift $((OPTIND - 1))</i>` is commonly used to remove the processed options and their arguments from the script's positional parameters, leaving only the non-option arguments (e.g., filenames) for further processing.


title: HISTORY
content:
<i><b>getopts</b></i> was introduced as part of the POSIX standard to provide a consistent and portable way for shell scripts to parse command-line options.<br>It emerged as a simpler, more robust alternative to the older `<b>getopt(1)</b>` external utility for handling standard short options.<br>Its design focuses on efficiency and direct integration as a shell built-in, first appearing in shells like ksh and later adopted widely by Bash and zsh, establishing a common convention for script option parsing across Unix-like systems.


title: PARAMETERS
content:
<b><b>-a</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;This option displays the current state of all SELinux booleans known to the system. It's useful for getting a comprehensive overview of the active policy toggles.<br><br><b><I>boolean</I> ...</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies one or more SELinux boolean names whose states you wish to query. If no booleans are specified and the <b>-a</b> option is not used, <I>getsebool</I> will typically show an error or usage information.<br><br>


title: DESCRIPTION
content:
The <I>getsebool</I> command is a utility within the SELinux framework used to query the current runtime state of SELinux booleans. SELinux booleans are true/false values that dynamically modify parts of the SELinux policy without requiring a full policy reload. They allow administrators to enable or disable specific security features or permissions based on their operational needs. For example, a boolean might control whether Apache can serve content from user home directories or if Samba can share NFS volumes. <I>getsebool</I> provides visibility into whether these policy toggles are currently enabled ("on") or disabled ("off"). It's a crucial tool for diagnosing SELinux-related access issues or verifying the application of security policies at runtime. Unlike commands that show persistent boolean states, <I>getsebool</I> reflects only the active state, which might have been changed temporarily since the last boot or policy reload.


title: CAVEATS
content:
<I>getsebool</I> requires SELinux to be enabled and enforcing on the system to function correctly. If SELinux is disabled or in permissive mode, its output might not be meaningful or the command might not even run.<br>The command only reports the <b>current runtime state</b> of the booleans. This state may differ from the persistent state configured to apply on boot. To see the persistent state, refer to the <I>semanage boolean -l</I> command.<br>Appropriate permissions are needed to execute this command, although it's typically available to all users for read access.


title: WHAT IS A SELINUX BOOLEAN?
content:
A SELinux boolean is a binary switch (on/off) defined within the SELinux policy that allows administrators to dynamically enable or disable specific policy rules without recompiling and reloading the entire policy. This provides flexibility to adapt security policies to specific system configurations or application requirements at runtime.


title: RUNTIME VS. PERSISTENT STATE
content:
When a boolean's state is changed with <I>setsebool</I> without the <b>-P</b> option, it's only changed for the current runtime session. This change is not saved across reboots. <I>getsebool</I> reflects this runtime state. To make changes persistent, the <b>-P</b> option with <I>setsebool</I> or tools like <I>semanage boolean</I> must be used.


title: HISTORY
content:
The <I>getsebool</I> command is an integral part of the SELinux utilities, primarily included in the <I>policycoreutils</I> package. Its development has been alongside the evolution of SELinux itself, providing a necessary tool for administrators to inspect and manage dynamic policy adjustments. It has been a standard component of SELinux-enabled distributions for many years, reflecting its fundamental role in runtime policy inspection.


title: PARAMETERS
content:
<b><b>-d</b> <i>TEXTDOMAIN</i>, <b>--domain=</b><i>TEXTDOMAIN</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the text domain to use. This indicates the name of the message catalog to search within.<br><br><b><b>-e</b>, <b>--expand-all</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Expand all escape sequences in the output string (e.g., `\n` for newline).<br><br><b><b>-n</b>, <b>--no-fallback</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Do not fall back to printing the untranslated <i>MSGID</i> if a translation is not found in the catalog.<br><br><b><b>-s</b>, <b>--string</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Treat the arguments as literal strings rather than file paths. This is the default behavior for the <b>gettext</b> command.<br><br><b><b>-c</b> <i>CONTEXT</i>, <b>--context=</b><i>CONTEXT</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the context for the message. This is used when a message can have different translations depending on its context (similar to `pgettext`).<br><br><b><b>-h</b>, <b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display a brief help message and exit.<br><br><b><b>-V</b>, <b>--version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display version information for <b>gettext</b> and exit.<br><br>


title: DESCRIPTION
content:
The <b>gettext</b> command is a fundamental utility within the GNU gettext internationalization (i18n) and localization (l10n) system. Its primary purpose is to retrieve a translated string for a given message ID from a message catalog.<br><br>This allows applications to display messages in the user's preferred language without requiring recompilation. When a program wants to display a message, it internally calls a `gettext()` function, passing an untranslated English string (the message ID). The <b>gettext</b> command-line utility mimics this behavior, enabling users or scripts to test translations or retrieve specific messages directly.<br><br>It searches for a compiled message catalog file (an <i>.mo</i> file) based on the specified text domain and the current locale settings (e.g., <i>LC_MESSAGES</i>, <i>LANG</i>). If a translation is found, it is printed to standard output; otherwise, the original message ID is returned. This system is crucial for creating multilingual software, separating translatable strings from the source code and managing them in easily editable <i>.po</i> (Portable Object) files, which are then compiled into binary <i>.mo</i> (Machine Object) files for efficient lookup.


title: CAVEATS
content:
<ul><li><b>Locale Configuration</b>: The command heavily relies on the correct setting of locale environment variables (e.g., <i>LANG</i>, <i>LC_ALL</i>, <i>LC_MESSAGES</i>). If these are not set or the corresponding message catalogs are missing, the command will often return the original message ID.<br></li><li><b>Text Domain Path</b>: Message catalogs (<i>.mo</i> files) must be located in standard system paths like <i>/usr/share/locale</i> or <i>/usr/local/share/locale</i>, or paths specified by applications using `bindtextdomain`. The <b>gettext</b> command-line tool itself does not offer direct options to specify arbitrary catalog search paths, relying on the default system configuration.<br></li><li><b>Encoding</b>: Ensure that your terminal's character encoding matches the encoding of the message catalog for proper display of translated characters. Incorrect encoding can lead to garbled output.</li></ul>


title: TEXT DOMAINS
content:
A <i>text domain</i> is a logical name for a set of message catalogs, typically corresponding to an application or library (e.g., `coreutils`, `gnome-shell`). When using <b>gettext</b>, you specify a text domain to tell it which catalog to look into for translations.


title: MESSAGE CATALOGS
content:
These are files containing the actual translations. <i>.po</i> (Portable Object) files are human-readable translation files, which are edited by translators. <i>.mo</i> (Machine Object) files are compiled binary versions of <i>.po</i> files, optimized for fast lookup by programs like <b>gettext</b>.


title: LOCALES
content:
The <i>locale</i> system defines language, country, and character encoding settings for a user's environment. <b>gettext</b> uses the current locale (specifically the <i>LC_MESSAGES</i> or <i>LANG</i> environment variable) to determine which language version of a message catalog to load (e.g., <i>en_US</i> for American English, <i>fr_FR</i> for French).


title: HISTORY
content:
The GNU gettext project was initiated by the Free Software Foundation in the early 1990s as a standard approach to internationalization for GNU software. The <b>gettext</b> utility is a core component, providing the runtime translation lookup mechanism. Its design was influenced by existing i18n approaches but aimed for a more robust and widely applicable solution for free software projects. It quickly became the de facto standard for i18n on Unix-like systems and is now integrated into many programming languages and frameworks, forming the backbone of most Linux desktop environment translations.


title: PARAMETERS
content:
<b><b>--copy</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Copy files, even if symlinks would be preferred. This forces a physical copy of files into the project's structure rather than creating symbolic links to the gettext installation.<br><br><b><b>--dry-run</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Do not actually do anything, just show what would be done. Useful for previewing changes without modifying files.<br><br><b><b>--force</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Overwrite existing files without asking. Use with caution, as it can undo manual modifications.<br><br><b><b>--no-changelog</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Do not try to update <i>ChangeLog</i>. By default, <i>gettextize</i> attempts to record its changes in the project's <i>ChangeLog</i> file.<br><br><b><b>--no-libtool</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Do not use libtool. This option is useful if the project does not utilize libtool or if <i>gettextize</i> is causing conflicts with an existing libtool setup.<br><br><b><b>--omit-header</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Do not output <i>AM_GNU_GETTEXT_VERSION</i> comment in <i>configure.ac</i>.<br><br><b><b>--po-dir=DIR</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Use DIR for the <i>po/</i> directory instead of the default <i>po</i>. Allows custom placement of translation files.<br><br><b><b>--quiet</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Suppress most output. Only errors will be displayed.<br><br><b><b>--verbose</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Output more details about operations being performed.<br><br><b><b>--version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display version information and exit.<br><br><b><b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display help message and exit.<br><br>


title: DESCRIPTION
content:
The <i>gettextize</i> command is a helper script provided by the GNU gettext utilities. Its primary purpose is to prepare a software package for internationalization (i18n) using the gettext system. When run from the top-level directory of an Autotools-based project, it performs several crucial setup steps. It copies necessary files like <i>config.rpath</i> and the <i>po/Makefile.in.in</i> template into the project structure. More importantly, it modifies the project's <i>configure.ac</i> (or <i>configure.in</i>) file by adding appropriate <i>AM_GNU_GETTEXT</i> macros and <i>AC_CONFIG_SRCDIR</i> directives, ensuring that the <i>configure</i> script will correctly handle gettext-related paths and definitions.<br><br>Furthermore, it creates or updates the <i>po/</i> directory, which is where translation template files (.pot) and message catalogs (.po) reside. By automating these initial setup tasks, <i>gettextize</i> significantly simplifies the process of integrating gettext into new or existing projects, allowing developers to focus on marking strings for translation rather than configuring the build system. It's typically a one-time operation at the onset of internationalization efforts.


title: CAVEATS
content:
<i>gettextize</i> is designed primarily for projects using GNU Autotools (Autoconf, Automake). It directly modifies files like <i>configure.ac</i> and creates/updates the <i>po/</i> directory, assuming a standard Autotools project structure. Running it on a non-Autotools project or one with an unconventional build system may lead to unexpected behavior or errors.<br><br>It's generally a one-time setup command; subsequent runs might require using <i>--force</i>, which can overwrite manual changes. Ensure your project is backed up before running <i>gettextize</i>, especially with the <i>--force</i> option.


title: TYPICAL WORKFLOW
content:
To use <i>gettextize</i> effectively, navigate to the top-level directory of your source package.<br><br>1. Run <b>gettextize</b>.<br>2. After running, you might need to run <b>autoconf</b>, <b>automake --add-missing --force-missing</b>, and <b>libtoolize</b> (if using libtool) to fully update your build system.<br>3. Then, you would typically run <b>xgettext</b> to create a <i>.pot</i> template, and <b>msginit</b> to create new <i>.po</i> files for specific languages.<br>4. Finally, you would run <b>configure</b>, <b>make</b>, and <b>make install</b> as usual.


title: INTEGRATION WITH AUTOTOOLS
content:
<i>gettextize</i> modifies your <i>configure.ac</i> file by adding crucial Autoconf macros like <i>AM_GNU_GETTEXT</i>. This macro handles the detection of the gettext library and its necessary components, defines various C preprocessor symbols, and integrates gettext into the build process by generating <i>Makefile</i> rules for translation file compilation. It assumes that you are familiar with and are actively using Autotools for your project's build system.


title: HISTORY
content:
<i>gettextize</i> is an integral part of the GNU gettext software internationalization framework, which was initiated by the GNU Project. The gettext library and its associated tools, including <i>gettextize</i>, were developed to provide a standardized and robust mechanism for developers to enable multilingual support in their applications. Its introduction aimed to simplify the often complex initial setup required for integrating internationalization features into projects, particularly those built with GNU Autotools. Over time, it has evolved alongside the gettext system, adapting to new versions of Autotools and improving its automation capabilities, making it a cornerstone utility for i18n-focused software development in the Unix/Linux ecosystem.


title: SYNOPSIS
content:
<b>getty</b> [<i>options</i>] <i>tty_line</i> [<i>baud_rate</i> [<i>terminal_type</i> [<i>linediscipline</i>]]]<br><i>Common usage (e.g., for agetty, a common modern getty implementation):</i><br><b>getty</b> [<i>-h</i>] [<i>-t timeout</i>] [<i>-U user</i>] [<i>-L</i>] <i>port</i> [<i>baud_rate</i> [<i>term_type</i>]]


title: PARAMETERS
content:
<b><i>tty_line</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The name of the terminal device to open (e.g., <i>tty1</i>, <i>ttyS0</i>). This is typically a pathname relative to <i>/dev/</i>.<br><br><b><i>baud_rate</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The speed (baud rate) at which the terminal should operate. Multiple rates can often be specified, allowing <b>getty</b> to cycle through them.<br><br><b><i>terminal_type</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The value to be set for the <i>TERM</i> environment variable (e.g., <i>vt100</i>, <i>linux</i>).<br><br><b><i>linediscipline</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The line discipline to use for the terminal line (e.g., <i>n_tty</i>, <i>n_hdlc</i>). Less commonly specified directly.<br><br><b><i>-h</i> or <i>--help</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a help message and exits.<br><br><b><i>-L</i> or <i>--local-only</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Configures <b>getty</b> to not call <b>login</b> if the terminal is not local (e.g., for dial-in lines, if remote authentication is handled differently).<br><br><b><i>-t timeout</i> or <i>--timeout timeout</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the number of seconds <b>getty</b> should wait for a username before exiting if no input is received.<br><br><b><i>-U user</i> or <i>--autologin user</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Automatically logs in the specified <i>user</i> without prompting for a username. Commonly used for embedded systems or specific kiosks.<br><br><b><i>--noreset</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prevents <b>getty</b> from resetting the terminal's tty modes. Useful for preserving specific settings or for certain serial console configurations.<br><br>


title: DESCRIPTION
content:
The <b>getty</b> command is a crucial system utility responsible for preparing a terminal line (either a physical serial port or a virtual console) to accept user logins. It initializes the terminal's characteristics, such as baud rate, parity, and flow control, based on system configuration. After initialization, <b>getty</b> typically displays the contents of the <i>/etc/issue</i> file, which often contains system identification and welcome messages. Following this, it prompts the user to enter their username. Once a username is received, <b>getty</b> usually invokes the <b>login</b> program, passing the entered username as an argument. The <b>login</b> program then handles password authentication and subsequent user session setup. Historically, <b>getty</b> instances were managed by the <b>init</b> process through <i>/etc/inittab</i>, but in modern Linux distributions, <b>systemd</b> manages <b>getty</b> services, typically starting them on demand or for configured terminals. This command is rarely invoked directly by users; rather, it's a fundamental daemon ensuring multi-user access to the system.


title: CAVEATS
content:
<b>getty</b> itself is often a symbolic link to a specific <b>getty</b> implementation, such as <b>agetty</b> (common on modern Linux) or <b>mingetty</b> (often used for virtual consoles). Therefore, the exact options and behavior can vary slightly depending on which underlying program <b>getty</b> points to. Users typically do not invoke <b>getty</b> directly; it is managed by the system's init process (e.g., <b>systemd</b> on modern systems or <b>init</b> via <i>/etc/inittab</i> on older systems) to handle terminal logins.


title: THE <I>/ETC/ISSUE</I> FILE
content:
Before prompting for a username, <b>getty</b> typically displays the contents of the <i>/etc/issue</i> file. This file often contains a brief description of the system, OS version, or welcome messages. It's a simple way for administrators to provide information to users before they log in.


title: PROCESS FLOW
content:
The typical flow involves <b>systemd</b> (or <b>init</b>) starting a <b>getty</b> instance for a specific terminal. <b>getty</b> initializes the terminal, displays <i>/etc/issue</i>, prompts for a username, and then executes <b>login</b> with the provided username. If the user successfully authenticates, <b>login</b> then typically starts a shell for the user. If the user logs out, the terminal line becomes free, and <b>systemd</b> can restart <b>getty</b> to await the next login.


title: HISTORY
content:
The <b>getty</b> command is one of the oldest and most fundamental utilities in Unix-like operating systems, dating back to early versions of Unix. Its core function—initializing a terminal and prompting for login—has remained remarkably consistent throughout its history. Originally, <b>getty</b> was primarily used for physical serial terminals and dial-up lines. With the advent of virtual consoles and graphical environments, its role extended to managing these as well. Over time, various implementations like <b>agetty</b> and <b>mingetty</b> emerged, offering improved features, efficiency, and flexibility. The transition from the <b>init</b> daemon and its <i>/etc/inittab</i> configuration to the <b>systemd</b> service manager represents the most significant shift in how <b>getty</b> instances are managed and orchestrated on modern Linux distributions, centralizing their configuration within systemd unit files.


title: SYNOPSIS
content:
<b>getuserspns.py</b> <i>&lt;DOMAIN&gt;</i>/<i>&lt;USERNAME&gt;</i>[:<i>&lt;PASSWORD&gt;</i>|@<i>&lt;FILE&gt;</i>|:<i>&lt;HASH&gt;</i>] [<i>-options</i>]<br><b>getuserspns.py</b> <i>-k</i> <i>&lt;DOMAIN&gt;</i>/<i>&lt;USERNAME&gt;</i> [<i>-options</i>]


title: PARAMETERS
content:
<b><i>&lt;DOMAIN&gt;</i>/<i>&lt;USERNAME&gt;</i>[:<i>&lt;PASSWORD&gt;</i>|@<i>&lt;FILE&gt;</i>|:<i>&lt;HASH&gt;</i>]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the domain, username, and authentication method. This can be a password, a file containing the password (prefix with '@'), or an NTLM hash (LMHASH:NTHASH).<br><br><b><b>-h</b>, <b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows the help message and exits.<br><br><b><b>-debug</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Turns on debug output for more verbose information.<br><br><b><b>-hashes</b> <i>LMHASH:NTHASH</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the NTLM hash (LM hash and NT hash separated by a colon) for authentication instead of a password.<br><br><b><b>-aesKey</b> <i>&lt;HEXKEY&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the AES key to use for Kerberos authentication (e.g., for Pass-the-AES).<br><br><b><b>-k</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Uses Kerberos authentication. This option implies that a Kerberos ticket is available in the cache or a keytab file is used.<br><br><b><b>-no-pass</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Don't ask for a password. Useful when using hash, AES key, or Kerberos ticket.<br><br><b><b>-dc-ip</b> <i>&lt;IP_ADDRESS&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the IP address of the Domain Controller to target.<br><br><b><b>-kdcHost</b> <i>&lt;HOSTNAME&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the KDC host to use for Kerberos authentication. Can be an IP address or FQDN. Overrides <b>-dc-ip</b> for Kerberos.<br><br><b><b>-request-user</b> <i>&lt;USER&gt;</i> | <i>file:&lt;FILE&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Requests SPNs for a specific user, or for a list of users provided in a file (e.g., <i>file:users.txt</i>). If not specified, the script may try to enumerate common SPNs implicitly.<br><br><b><b>-outputfile</b> <i>&lt;FILE&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Saves the retrieved SPN hashes to the specified file.<br><br>


title: DESCRIPTION
content:
<i>getuserspns.py</i> is a Python script included in the Impacket toolkit, widely used in penetration testing and security assessments. Its primary function is to enumerate and retrieve Kerberos Service Principal Name (SPN) hashes from a Microsoft Active Directory domain controller.<br><br>The script facilitates the 'Kerberoasting' attack by identifying user accounts (typically service accounts) that have an SPN registered. It then requests a Kerberos Ticket Granting Service (TGS) ticket for these SPNs. This TGS ticket, when encrypted with the service account's NTLM hash, can be captured and subsequently cracked offline using tools like Hashcat or John the Ripper.<br><br>This allows an attacker to obtain the plaintext password of the service account without direct interaction with the service or its host. The script requires valid domain credentials (username/password or NTLM hash) to authenticate to the domain controller.


title: CAVEATS
content:
Using <i>getuserspns.py</i> generates Kerberos traffic and leaves forensic artifacts (e.g., event ID 4769 for TGS requests) on the Domain Controller, which can be detected by security monitoring solutions. It requires valid domain credentials with sufficient privileges to query Active Directory. Misuse of this tool can lead to legal consequences as it is primarily designed for legitimate security testing and red teaming exercises.


title: KERBEROASTING ATTACK EXPLAINED
content:
Kerberoasting is a post-exploitation technique used to retrieve service account credentials from Active Directory. The attack leverages the fact that Service Principal Names (SPNs) are registered to user accounts (often service accounts). When a client requests a Kerberos TGS ticket for an SPN, the Domain Controller encrypts the ticket using the NTLM hash of the service account's password. Since this ticket can be obtained by any authenticated domain user, an attacker can request TGS tickets for various SPNs, extract the encrypted portion (the hash), and then attempt to crack it offline to obtain the plaintext password of the service account. The hashes retrieved by <i>getuserspns.py</i> are typically in a format suitable for Hashcat (mode 13100) or John the Ripper.


title: HISTORY
content:
<i>getuserspns.py</i> is an integral component of the Impacket toolkit, a collection of Python classes for working with network protocols. Originally developed by SecureAuth (now Fortra/Core Security), Impacket has become a de-facto standard in offensive security for interacting with Windows services, including Active Directory and Kerberos. The script has evolved with the toolkit, consistently updated to support various Kerberos attack vectors and keep pace with Windows security enhancements, making it a reliable choice for Kerberoasting attacks.


title: SYNOPSIS
content:
<i>gfortran</i> [<i>options</i>] <i>file...</i><br>Example: <i>gfortran -Wall -O3 myprogram.f90 -o myexecutable</i>


title: PARAMETERS
content:
<b><b>-o</b> <i>file</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the <b>output file name</b>. By default, an executable is named <i>a.out</i>.<br><br><b><b>-c</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<b>Compile or assemble the source files</b>, but do not link. Output is an object file (<i>.o</i>).<br><br><b><b>-S</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<b>Compile only</b>; do not assemble or link. Output is an assembly file (<i>.s</i>).<br><br><b><b>-E</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<b>Preprocess only</b>; do not compile, assemble or link. Output is to standard output.<br><br><b><b>-g</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Generate <b>debugging information</b> suitable for <i>GDB</i>.<br><br><b><b>-O</b><i>level</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set the <b>optimization level</b>. Common levels are <b>-O1</b>, <b>-O2</b>, <b>-O3</b> (more aggressive), <b>-Os</b> (optimize for size), and <b>-Og</b> (optimize for debugging).<br><br><b><b>-Wall</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enable <b>all common warnings</b>.<br><br><b><b>-Wextra</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enable <b>extra warnings</b> not enabled by <b>-Wall</b>.<br><br><b><b>-I</b><i>dir</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Add <i>dir</i> to the list of <b>directories to search for include files</b>.<br><br><b><b>-L</b><i>dir</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Add <i>dir</i> to the list of <b>directories to search for libraries</b>.<br><br><b><b>-l</b><i>lib</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<b>Link with library</b> <i>lib</i>. E.g., <b>-lm</b> links with <i>libm.so</i>.<br><br><b><b>-std=</b><i>standard</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the <b>Fortran standard</b> to which the code should conform (e.g., <b>f95</b>, <b>f2003</b>, <b>f2008</b>).<br><br><b><b>-fPIC</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Generate <b>position-independent code</b>, often required for shared libraries.<br><br><b><b>-fopenmp</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enable <b>OpenMP support</b> for parallel programming.<br><br>


title: DESCRIPTION
content:
<i>gfortran</i> is the GNU Fortran compiler, a crucial component of the GNU Compiler Collection (GCC). It serves as the primary tool for translating Fortran source code into executable programs, object files, or libraries on Linux systems. <i>gfortran</i> supports a wide range of Fortran standards, including Fortran 77, Fortran 90, Fortran 95, Fortran 2003, Fortran 2008, and Fortran 2018, ensuring compatibility with both legacy and modern Fortran applications. It is widely used in scientific computing, engineering, and numerical analysis due to Fortran's strengths in these domains. Key features include extensive optimization capabilities for performance tuning, support for various debugging levels, and the ability to link with libraries written in other languages like C or C++. The compiler integrates seamlessly with other GCC compilers (like <i>gcc</i> for C and <i>g++</i> for C++), allowing for mixed-language programming. <i>gfortran</i> provides a robust and free-software alternative for Fortran development, making it an indispensable tool for Fortran programmers.


title: CAVEATS
content:
<i>gfortran</i> is a powerful compiler, but users should be aware of a few points:<br><ul><li><b>Fortran Specifics</b>: Understanding Fortran's strict syntax and data handling is crucial.</li><li><b>Toolchain Dependencies</b>: It relies on the GCC toolchain (assembler, linker) for its operation.</li><li><b>Error Messages</b>: While improved, some complex compilation errors can still be challenging to interpret.</li><li><b>Linking Issues</b>: Incorrect library paths or missing libraries (<b>-L</b>, <b>-l</b> options) are common sources of errors during the linking phase.</li><li><b>Performance</b>: Achieving optimal performance requires careful use of optimization flags and understanding of Fortran array operations and memory layout.</li></ul>


title: EXIT STATUS
content:
<i>gfortran</i> typically exits with a status of <b>0</b> if compilation and linking are successful. A non-zero exit status (usually <b>1</b>) indicates an error during the compilation, assembly, or linking process.


title: ENVIRONMENT VARIABLES
content:
<i>gfortran</i> respects several environment variables inherited from the GCC toolchain, such as <b>CPATH</b> (for include paths), <b>LIBRARY_PATH</b> (for library search paths), and <b>LD_LIBRARY_PATH</b> (for runtime library search paths when executing). These variables can influence how the compiler finds headers and libraries.


title: HISTORY
content:
<i>gfortran</i> is part of the GNU Compiler Collection (GCC), an ambitious free software project initiated by Richard Stallman. Its development as a full-fledged Fortran 90/95/2003/2008/2018 compiler marked a significant evolution from its predecessor, <i>g77</i> (the Fortran 77 compiler). While <i>g77</i> provided a robust Fortran 77 implementation, <i>gfortran</i> was specifically designed to meet the demands of modern Fortran standards, including object-oriented features, module support, and enhanced array handling. It effectively replaced <i>g77</i> as the default Fortran compiler within the GCC suite and has undergone continuous development, contributing to its stability, performance, and adherence to evolving Fortran standards.


title: PARAMETERS
content:
<b><b>-d</b>, <b>--debug</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables debugging output for troubleshooting connection or transfer issues.<br><br><b><b>-P</b> <i>&lt;port&gt;</i>, <b>--port</b> <i>&lt;port&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the remote server port to connect to, overriding the default protocol port.<br><br><b><b>-u</b> <i>&lt;username&gt;</i>, <b>--user</b> <i>&lt;username&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Provides the username for automatic login to the remote server.<br><br><b><b>-p</b> <i>&lt;password&gt;</i>, <b>--password</b> <i>&lt;password&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Provides the password for automatic login. Note: This option is generally discouraged for security reasons as it exposes credentials.<br><br><b><b>-a</b> <i>&lt;account&gt;</i>, <b>--account</b> <i>&lt;account&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies an account string for servers that require it after authentication.<br><br><b><b>-l</b> <i>&lt;path&gt;</i>, <b>--local-dir</b> <i>&lt;path&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the initial local directory that <i>gftp</i> will open upon launch.<br><br><b><b>-r</b> <i>&lt;path&gt;</i>, <b>--remote-dir</b> <i>&lt;path&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the initial remote directory on the server that <i>gftp</i> will navigate to.<br><br><b><b>-b</b> <i>&lt;name&gt;</i>, <b>--bookmark</b> <i>&lt;name&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Opens a specific site configuration stored as a bookmark in <i>gftp</i>'s site manager.<br><br><b><b>-s</b> <i>&lt;name&gt;</i>, <b>--site</b> <i>&lt;name&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Similar to --bookmark, used to open a named site configuration.<br><br><b><b>-v</b>, <b>--version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays the version information of the <i>gftp</i> client.<br><br><b><b>-h</b>, <b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints a summary of command-line options and usage.<br><br>


title: DESCRIPTION
content:
<i>gftp</i> is a free, open-source graphical FTP client designed for Unix-like operating systems, leveraging the GTK+ toolkit for its user interface. It provides a user-friendly way to transfer files between local and remote computers using various protocols, including FTP, FTPS (FTP over SSL), HTTP, HTTPS, SSH (SFTP), and FXP (server-to-server transfers). Its dual-pane interface allows for easy navigation of local and remote file systems, facilitating drag-and-drop transfers. While robust for its time, it is an older application and may not be actively maintained or widely available on newer distributions compared to more modern alternatives like <i>FileZilla</i>.


title: CAVEATS
content:
Being a graphical application, <i>gftp</i> is less suitable for scripting or automated tasks. It is an older piece of software, with its last stable release dating back to 2008, meaning it may not be actively maintained or natively available on all modern Linux distributions. Using the <b>--password</b> option on the command line is a security risk as it exposes login credentials.


title: DUAL-PANE INTERFACE
content:
<i>gftp</i> features a highly intuitive dual-pane interface, allowing users to simultaneously view and navigate both their local file system and the remote server's directory structure. This design facilitates easy drag-and-drop file transfers between the two locations.


title: PROTOCOL SUPPORT
content:
Beyond standard FTP, <i>gftp</i> extended its capabilities to support secure protocols such as FTPS (FTP over SSL) and SSH (for SFTP), as well as HTTP/HTTPS for web-based transfers. It also included support for FXP, enabling direct server-to-server file transfers without routing data through the client's machine.


title: HISTORY
content:
<i>gftp</i> was initially developed by Brian Masney and first released in 1998. It quickly became one of the prominent graphical FTP clients for Unix-like operating systems, leveraging the then-emerging GTK+ toolkit. Its development was active through the early 2000s, with its final stable version (2.0.19) released in 2008. While revolutionary for its time, its active development has largely ceased, leading to its gradual replacement by newer, more feature-rich, and actively maintained clients in the Linux ecosystem.


title: SYNOPSIS
content:
<b>gh</b> <I>command</I> [<I>subcommand</I>] [<I>flags</I>]<br><b>gh</b> <I>auth</I> <I>login</I><br><b>gh</b> <I>pr</I> <I>create</I><br><b>gh</b> <I>issue</I> <I>list</I><br><b>gh</b> <I>help</I> [<I>command</I>]


title: PARAMETERS
content:
<b><b>--help</b>, <b>-h</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show help for a specific command or the global usage.<br><br><b><b>--version</b>, <b>-v</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Print the version of <i>gh</i> CLI.<br><br><b><b>--verbose</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enable verbose output, useful for debugging.<br><br><b><b>--hostname</b> <I>host</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the GitHub hostname to interact with (default: github.com).<br><br><b><b>--repo</b> <I>owner/repo</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the GitHub repository to operate on. Defaults to the current directory's repository.<br><br><b><b>--json</b> <I>fields</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Output in JSON format with specified fields, available for certain commands (e.g., <i>gh pr view</i>).<br><br><b><b><I>subcommand_flags</I></b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Each <i>gh</i> subcommand (e.g., <i>pr</i>, <i>issue</i>, <i>release</i>) has its own set of specific flags that control its behavior. Use <i>gh &lt;command&gt; help</i> to see available flags.<br><br>


title: DESCRIPTION
content:
<i>gh</i> is the official command-line interface for GitHub. It brings pull requests, issues, Gists, releases, and other GitHub functionalities directly to your terminal. Instead of navigating the web interface, developers can perform common tasks like creating repositories, managing pull requests, viewing issues, or interacting with GitHub Actions workflows from their command line. This significantly streamlines workflows, enables scripting and automation of GitHub interactions, and integrates GitHub more deeply into the developer's local environment. While <i>gh</i> complements and often enhances Git operations, it does not replace Git itself; rather, it extends Git's capabilities with GitHub-specific features.


title: CAVEATS
content:
<i>gh</i> requires an active internet connection to interact with GitHub.<br>Prior authentication using <i>gh auth login</i> is necessary to perform most operations.<br>It's not a full replacement for Git; core Git operations like <i>git add</i>, <i>git commit</i>, and <i>git push</i> are still performed using the <i>git</i> command.


title: AUTHENTICATION
content:
<i>gh</i> manages authentication securely, primarily through OAuth. The first time you use a command requiring authentication (e.g., <i>gh pr create</i>), it will prompt you to run <i>gh auth login</i>. This command guides you through a browser-based authentication flow, obtaining a secure token that <i>gh</i> stores locally for future use. It also supports authentication via GitHub Enterprise Server instances.


title: EXTENSIBILITY
content:
<i>gh</i> supports custom extensions, allowing users to create their own subcommands. These extensions can be written in any language and are executed as separate processes. This feature enables users and communities to build specialized tools and workflows on top of the existing <i>gh</i> functionality, further tailoring it to specific needs. Extensions are installed via <i>gh extension install &lt;repo&gt;</i>.


title: HISTORY
content:
The <i>gh</i> CLI was developed by GitHub Inc. and officially released in 2020. It was designed to provide a unified and official command-line experience for GitHub, aiming to supersede community-driven efforts like the <i>hub</i> tool (which was an extension to Git). Its development is open source and actively maintained, with frequent updates adding new features and improving existing ones to keep pace with GitHub's web platform.


title: PARAMETERS
content:
<b>set</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Creates or updates an alias. <br>Usage: <i>gh alias set &lt;alias&gt;=&lt;expansion&gt;</i><br><br><b>delete</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Deletes one or more aliases. <br>Usage: <i>gh alias delete &lt;alias&gt;...</i><br><br><b>list</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Lists all currently configured aliases. <br>Usage: <i>gh alias list</i><br><br><b>import</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Imports aliases from a file. <br>Usage: <i>gh alias import [-i &lt;file&gt;]</i><br><br><b>export</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Exports aliases to a file. <br>Usage: <i>gh alias export [-o &lt;file&gt;]</i><br><br>


title: DESCRIPTION
content:
The <b>gh-alias</b> command is a powerful utility within the GitHub CLI (<br><i>gh</i>) that enables users to create, manage, and delete custom shortcuts (aliases) for frequently used <br><i>gh</i> commands or complex command sequences. <br><br>By defining aliases, users can significantly reduce typing, <br>streamline their workflow, and personalize their command-line experience. <br>It supports setting simple command replacements, <br>as well as more advanced aliases that include flags or even pipe outputs to other commands. <br>Aliases can be listed, imported from, and exported to files, <br>facilitating easy sharing and backup of configurations.<br>This functionality is crucial for power users who want to optimize <br>their interaction with GitHub directly from the terminal.


title: CAVEATS
content:
Aliases defined with <b>gh alias</b> are specific to the GitHub CLI and do not affect shell-level aliases (e.g., <i>bash</i> or <i>zsh</i> aliases). <br>Alias expansions are processed before any global flags, which can sometimes lead to unexpected behavior if not carefully considered. <br>Ensure alias names do not conflict with existing <i>gh</i> subcommands to avoid shadowing.


title: ALIAS EXPANSION LOGIC
content:
Aliases can expand to full <i>gh</i> commands, including flags and arguments. <br>For example, <i>gh alias set 'prview="gh pr view --web"'</i> creates an alias that opens a pull request in the browser. <br>Complex expansions involving pipes or multiple commands can be achieved by quoting the expansion properly.


title: INTERACTIVE ALIASES
content:
Aliases can be designed to prompt for input, allowing for dynamic command execution. <br>For instance, an alias could prompt for an issue number before opening it. <br>This leverages the underlying <i>gh</i> command's interactive capabilities.


title: HISTORY
content:
The <b>gh alias</b> command was introduced as a core feature of the GitHub CLI <br>(<i>gh</i>) from its early development stages, <br>reflecting the design philosophy to provide a highly customizable and efficient command-line experience for GitHub users. <br>Its inclusion was crucial for enabling users to extend and personalize the CLI's capabilities <br>beyond its default set of commands, mirroring similar alias functionalities found in traditional shells. <br>It has evolved alongside the <i>gh</i> CLI, with ongoing refinements to its parsing and execution logic.


title: SYNOPSIS
content:
<b>gh api</b> <i>&lt;path&gt;</i> [<i>flags</i>]<br><b>gh api</b> <b>-q</b> <i>&lt;GraphQL_query&gt;</i> [<i>flags</i>]


title: PARAMETERS
content:
<b><i>&lt;path&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The specific GitHub API endpoint path (e.g., <i>/user</i>, <i>/repos/OWNER/REPO</i>).<br><br><b><b>-X</b>, <b>--method</b> <i>&lt;METHOD&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the HTTP method for the request (e.g., GET, POST, PUT, DELETE).<br><br><b><b>-F</b>, <b>--field</b> <i>&lt;NAME&gt;</i>=<i>&lt;VALUE&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Adds a form field to the request body, useful for POST/PATCH/PUT with form data.<br><br><b><b>-f</b>, <b>--raw-field</b> <i>&lt;NAME&gt;</i>=<i>&lt;VALUE&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Adds a raw string field to the request body, similar to <b>-F</b> but without JSON escaping.<br><br><b><b>-H</b>, <b>--header</b> <i>&lt;NAME&gt;</i>=<i>&lt;VALUE&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Adds a custom HTTP header to the request.<br><br><b><b>-i</b>, <b>--include</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Includes HTTP response headers in the output.<br><br><b><b>-q</b>, <b>--jq</b> <i>&lt;QUERY&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Applies a <i>jq</i> expression to the JSON output. Also used to specify a GraphQL query if the argument starts with '{' or 'query'.<br><br><b><b>-v</b>, <b>--verbose</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays detailed information about the request and response for debugging.<br><br><b><b>-P</b>, <b>--paginate</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Automatically fetches all pages of a paginated API response.<br><br><b><b>-p</b>, <b>--template</b> <i>&lt;TEMPLATE&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Formats the output using a Go template.<br><br><b><b>--input</b> <i>&lt;FILE&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Reads the request body from a specified file or standard input.<br><br><b><b>--cache</b> <i>&lt;DURATION&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Caches the API response for the given duration (e.g., <i>1h</i>, <i>30m</i>).<br><br>


title: DESCRIPTION
content:
The <b>gh api</b> command is a powerful subcommand of the GitHub CLI that enables users to make direct, authenticated requests to both the GitHub REST API and GraphQL API. It leverages your existing <b>gh</b> authentication session, eliminating the need for manual token management. This command is invaluable for scripting complex workflows, automating repetitive tasks, or accessing GitHub API endpoints not covered by other specific <b>gh</b> commands. Users can specify HTTP methods, path parameters, request bodies (via form fields or raw input), and custom headers. It provides robust features such as automatic pagination for REST endpoints, <i>jq</i> integration for output processing, and caching of responses. <b>gh api</b> is designed for developers, system administrators, and power users who require granular control and direct programmatic interaction with GitHub's extensive API infrastructure.


title: CAVEATS
content:
<b>gh api</b> respects GitHub API rate limits; excessive or rapid requests, especially with pagination, can quickly consume your quota.<br>It relies on your existing <b>gh auth</b> configuration for authentication, so proper authentication setup is crucial.<br>The API token used must possess the necessary scopes for the requested operations to succeed.<br>While supporting GraphQL, complex queries might be more manageable with dedicated GraphQL tools.<br>Users should always anticipate and handle potential API errors in their scripts.


title: API AUTHENTICATION
content:
<b>gh api</b> automatically uses the authentication credentials established via <b>gh auth login</b>, simplifying API interactions by eliminating manual token handling.


title: RESPONSE HANDLING
content:
By default, the command prints the raw JSON response body to standard output. This output is ideal for piping into <i>jq</i> for parsing or for custom formatting using a Go template with the <b>-p</b> flag.


title: GRAPHQL OVERLOAD
content:
The <b>-q</b> flag is versatile; if its argument starts with '{' or 'query', it's interpreted as a GraphQL query executed against the GitHub GraphQL API endpoint, otherwise it applies a <i>jq</i> filter.


title: HISTORY
content:
The <b>gh api</b> subcommand was introduced as a fundamental component of the GitHub CLI, making its debut with the CLI's first stable release (v1.0.0 in September 2020). Its primary purpose was to provide a flexible and direct interface to the GitHub REST and GraphQL APIs, leveraging the CLI's built-in authentication system. This allowed users to script and automate interactions with GitHub beyond the capabilities of pre-defined <b>gh</b> commands. Since its inception, <b>gh api</b> has undergone continuous development, incorporating features like enhanced pagination, response caching, and refined GraphQL support, solidifying its role as an indispensable tool for advanced GitHub automation.


title: SYNOPSIS
content:
<i><b>gh auth</b> &lt;subcommand&gt; [flags]</i><br><br>The primary subcommands are:<br><b>login</b>: Log in to GitHub.<br><b>logout</b>: Log out of GitHub.<br><b>refresh</b>: Refresh authentication scopes.<br><b>status</b>: View authentication status.<br><b>token</b>: Print the authentication token.<br><br>For example, to log in with a web browser:<br><i><b>gh auth login --web</b></i><br>To log in using a Personal Access Token:<br><i><b>gh auth login --pat</b></i>


title: PARAMETERS
content:
<b><b>--hostname</b> <i>&lt;string&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the GitHub host to authenticate against. Defaults to <code>github.com</code>. Useful for GitHub Enterprise instances.<br><br><b><b>--scopes</b> <i>&lt;strings&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Requests additional authentication scopes beyond the default set. Scopes define the permissions granted to the GitHub CLI token (e.g., <code>repo</code>, <code>admin:org</code>, <code>gist</code>).<br><br><b><b>--web</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Authenticates through a web browser. This is the default and recommended method for <code>gh auth login</code>, opening a browser for interactive authentication.<br><br><b><b>--pat</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Reads a Personal Access Token (PAT) from standard input for authentication. This method is useful for automated scripts or when a browser is unavailable.<br><br><b><b>--token</b> <i>&lt;string&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Directly uses the provided string as an authentication token. Less secure for interactive use compared to <code>--pat</code> from stdin or <code>--web</code>.<br><br><b><b>--git-protocol</b> <i>&lt;string&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the protocol to use for Git operations cloned by <code>gh</code> (e.g., <code>gh repo clone</code>). Options are <code>https</code> or <code>ssh</code>. Defaults to <code>https</code>.<br><br><b><b>--no-browser</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prevents <code>gh auth login</code> from automatically opening a web browser. Useful when using a text-based terminal or for specific authentication flows.<br><br>


title: DESCRIPTION
content:
The <b>gh-auth</b> functionality, primarily accessed via the <code>gh auth</code> command and its subcommands, provides a comprehensive interface for authenticating the GitHub CLI (<code>gh</code>) with your GitHub account. It manages the tokens required for the CLI to interact with GitHub APIs, enabling actions like creating pull requests, managing issues, and cloning repositories securely. Users can log in using a web browser flow (the recommended default for ease and security) or by providing a Personal Access Token (PAT). It also allows users to log out, refresh authentication scopes, check their current authentication status, and retrieve their active authentication token. This setup ensures seamless integration of the command-line experience with GitHub.


title: CAVEATS
content:
The <b>gh-auth</b> commands require the GitHub CLI (<code>gh</code>) to be installed and available in your system's PATH. Authentication tokens are securely stored by <code>gh</code>, typically in your system's credential manager. Be mindful of the scopes requested, as they determine the permissions of your CLI token. Using Personal Access Tokens directly should be done with caution, especially in shared environments, due to security implications.


title: AUTHENTICATION METHODS
content:
The primary way to authenticate using <code>gh auth login</code> is via a web browser (the default <code>--web</code> flag). This method guides you through the GitHub OAuth flow. Alternatively, you can use a Personal Access Token (PAT) via the <code>--pat</code> flag, where the token is read from standard input, or directly provide it using <code>--token</code> (less recommended for security). The CLI securely stores the obtained token for subsequent commands.


title: TOKEN MANAGEMENT
content:
Beyond logging in, <code>gh auth</code> provides commands for managing your session. <code>gh auth status</code> shows your current authenticated user and host, along with granted scopes. <code>gh auth refresh</code> allows you to update your token's scopes without a full re-login. <code>gh auth logout</code> removes your authentication credentials for a given host. <code>gh auth token</code> prints the active authentication token, which can be useful for debugging or integration with other tools.


title: HISTORY
content:
The authentication capabilities have been an integral part of the GitHub CLI (<code>gh</code>) since its initial public releases. As the CLI matured, the <code>gh auth</code> command group evolved to provide more robust and user-friendly authentication methods, such as the streamlined web browser flow and enhanced token management, adapting to GitHub's API authentication best practices and security requirements.


title: SYNOPSIS
content:
<b>gh codespace</b> <i>&lt;command&gt;</i> [<i>flags</i>]<br><br>Common commands include:<br><b>gh codespace create</b> [<i>flags</i>]<br><b>gh codespace list</b> [<i>flags</i>]<br><b>gh codespace delete</b> <i>&lt;codespace-name&gt;</i> [<i>flags</i>]<br><b>gh codespace ssh</b> <i>&lt;codespace-name&gt;</i> [<i>flags</i>]<br><b>gh codespace cp</b> <i>&lt;source&gt;</i> <i>&lt;destination&gt;</i> [<i>flags</i>]<br><b>gh codespace ports</b> [<i>flags</i>]


title: PARAMETERS
content:
<b>create</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Creates a new codespace, often by specifying a repository, branch, or machine type. This command provisions a new cloud development environment.<br><br><b>list (ls)</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Lists all your available codespaces, showing their status, associated repository, machine type, and other relevant details.<br><br><b>delete (rm)</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Deletes one or more specified codespaces, effectively terminating the cloud environment and stopping any associated billing.<br><br><b>stop</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Stops a running codespace, pausing its active session and typically halting billing for compute resources.<br><br><b>start</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Starts a stopped codespace, making it accessible again for development.<br><br><b>ssh</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Connects to a specific codespace via SSH, providing direct command-line access within the cloud environment.<br><br><b>cp</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Copies files or directories between your local machine and a codespace, similar to the <b>scp</b> command.<br><br><b>view</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays detailed information about a specific codespace, including its URL, current status, and configuration.<br><br><b>ports</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Lists and manages forwarded ports within a codespace, allowing access to web services or applications running inside the codespace from your local machine.<br><br><b>rebuild</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Rebuilds a codespace, typically used after changes to its <i>devcontainer.json</i> configuration or to refresh the environment.<br><br><b>logs</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Accesses and displays logs from a codespace, which is useful for debugging issues within the environment.<br><br>


title: DESCRIPTION
content:
The <b>gh codespace</b> command set within the GitHub CLI provides a comprehensive interface for interacting with GitHub Codespaces. It allows users to perform various operations such as creating new codespaces, listing existing ones, stopping and starting them, deleting them, and connecting to them via SSH. Furthermore, it supports file transfer, port forwarding, and viewing codespace logs, making it a powerful tool for developers who rely on cloud-based development environments, streamlining their workflow directly from the terminal.


title: CAVEATS
content:
Using <b>gh codespace</b> requires the GitHub CLI (<b>gh</b>) to be installed and properly authenticated with your GitHub account. As Codespaces are cloud-based, continuous network connectivity is essential for their operation. Users should also be aware that GitHub Codespaces incur billing based on usage, and appropriate GitHub permissions are necessary for creating and managing these environments.


title: INTEGRATION WITH VS CODE
content:
Many <b>gh codespace</b> operations, such as creating or opening a codespace, are designed to integrate seamlessly with Visual Studio Code. This allows users to open their codespaces directly in VS Code desktop or web, providing a familiar and powerful IDE experience.


title: REMOTE DEVELOPMENT FACILITATOR
content:
This command significantly facilitates remote development workflows. It enables developers to work on projects within pre-configured, cloud-based environments, ensuring consistency across teams and providing all necessary tools and dependencies without the overhead of local setup.


title: HISTORY
content:
GitHub Codespaces emerged as a cloud-powered development environment solution from GitHub, aiming to provide instantly ready-to-code workspaces. The integration of <b>gh codespace</b> into the GitHub CLI was a natural progression, allowing developers to seamlessly manage these environments directly from their terminal. This development was driven by the need to streamline remote and cloud-based development workflows, making it easier to spin up, access, and tear down development environments without leaving the command line.


title: SYNOPSIS
content:
<B>gh</B> <B>completion</B> <I>shell</I><br><br><I>Commonly used by sourcing the output:</I><br><B>eval</B> "$(<B>gh</B> <B>completion</B> <I>shell</I>)"<br><br><I>Or for persistent system-wide installation (requires sudo):</I><br><B>gh</B> <B>completion</B> <I>shell</I> <B>|</B> <B>sudo</B> <B>tee</B> /etc/<I>shell</I>_completion.d/<B>gh</B>


title: PARAMETERS
content:
<b><I>shell</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the target shell for which to generate the completion script. Supported values typically include <B>bash</B>, <B>zsh</B>, and <B>fish</B>.<br><br>


title: DESCRIPTION
content:
The term <I>gh-completion</I> refers to the shell completion functionality provided by the GitHub CLI (<B>gh</B>). It is not a standalone command but rather the <I>output</I> or <I>feature</I> generated by the <B>gh completion</B> subcommand. When sourced into a user's shell configuration (e.g., <I>.bashrc</I>, <I>.zshrc</I>, <I>.profile</I>), <I>gh-completion</I> enables intelligent tab completion for <B>gh</B> commands, their subcommands, arguments, flags, and even specific values (like repository names or branch names). This dynamic completion greatly improves user efficiency by reducing typing, preventing errors, and aiding in the discovery of available options. It's an essential utility for anyone frequently using the GitHub CLI.


title: CAVEATS
content:
<I>gh-completion</I> (i.e., the script generated by <B>gh completion</B>) must be <I>sourced</I> into your shell, not executed directly. Running it directly will only print the script to standard output without enabling completion.<br><br>The generated script is shell-specific; ensure you use the correct <I>shell</I> argument for your environment.<br><br>A shell restart (or sourcing the configuration file again) is required for changes to take effect after installation.<br><br>Requires the <B>gh</B> CLI to be installed and accessible in the system's <B>PATH</B>.


title: <B>INSTALLATION EXAMPLE</B>
content:
<I>To enable <B>gh</B> completion for <B>Bash</B>, add the following line to your <I>~/.bashrc</I> file:</I><br><B>eval</B> "$(<B>gh</B> <B>completion</B> <B>bash</B>)"<br><br><I>For <B>Zsh</B>, add the equivalent line to your <I>~/.zshrc</I> file:</I><br><B>eval</B> "$(<B>gh</B> <B>completion</B> <B>zsh</B>)"<br><br><I>After adding, either restart your shell or run <B>source ~/.bashrc</B> (or <B>source ~/.zshrc</B>) to apply the changes.</I>


title: HISTORY
content:
The <B>completion</B> subcommand was introduced early in the development of the GitHub CLI (<B>gh</B>) to provide a seamless user experience across various popular shells. As <B>gh</B> evolved, its completion capabilities also improved, offering more intelligent suggestions for dynamic content like repository names, user aliases, and command-specific options. This functionality is a standard and expected feature for many modern command-line tools to enhance usability and productivity.


title: SYNOPSIS
content:
gh config <I>set</I> <I>key</I> <I>value</I> [<I>flags</I>]<br>gh config <I>get</I> <I>key</I> [<I>flags</I>]<br>gh config <I>list</I> [<I>flags</I>]<br>gh config <I>unset</I> <I>key</I> [<I>flags</I>]


title: PARAMETERS
content:
<b><I>set</I> <I>key</I> <I>value</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Configures a specified key with a new value. If the key already exists, its value is updated.<br><br><b><I>get</I> <I>key</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Retrieves and displays the current value for a given configuration key.<br><br><b><I>list</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Lists all currently set configuration keys and their corresponding values.<br><br><b><I>unset</I> <I>key</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Removes a specified configuration key and its associated value.<br><br><b>--host <I>hostname</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Applies the configuration operation to a specific GitHub Enterprise Server <I>hostname</I> instead of the default <I>github.com</I>.<br><br>


title: DESCRIPTION
content:
gh-config is a subcommand of the GitHub CLI (gh) designed to manage its configuration settings. It allows users to view, set, or unset various preferences that affect the CLI's behavior. These settings are stored in a <I>config.yml</I> file, typically located in <I>~/.config/gh/</I>. Users can configure parameters such as the default text editor, pager, Git protocol (SSH or HTTPS), prompt behaviors, and host-specific settings. This command provides a standardized way to customize the <I>gh</I> experience without directly editing the YAML file, ensuring consistency and ease of management for both global and host-specific configurations.


title: CAVEATS
content:
gh-config manages settings typically stored in <I>~/.config/gh/config.yml</I>. Manually editing this file can lead to syntax errors that <I>gh-config</I> might not detect, potentially breaking CLI functionality. Be cautious when setting values for critical parameters like <I>git_protocol</I> as incorrect settings can prevent Git operations. Some configuration keys might be host-specific, requiring the <B>--host</B> flag for proper management.


title: CONFIGURATION FILE LOCATION
content:
The primary configuration file managed by <I>gh-config</I> is typically located at <B>~/.config/gh/config.yml</B>. This YAML file stores all global and host-specific settings for the GitHub CLI.


title: COMMON CONFIGURATION KEYS
content:
Some frequently configured keys include:<br><b><I>editor</I></b>: Specifies the command used to open text files (e.g., for issue/PR descriptions).<br><b><I>pager</I></b>: Defines the command for paginating long output (e.g., <I>less</I> or <I>most</I>).<br><b><I>git_protocol</I></b>: Determines whether Git operations (e.g., cloning) use <I>ssh</I> or <I>https</I>.<br><b><I>prompt</I></b>: Controls various interactive prompt behaviors, such as whether to ask for confirmation.<br><b><I>http_unix_socket</I></b>: (Advanced) Specifies a Unix socket for HTTP communication, useful for proxying.


title: HISTORY
content:
The <I>gh-config</I> command is an integral part of the GitHub CLI, which was officially released in 2020. Its development aimed to provide a user-friendly and consistent way for users to manage their CLI preferences, replacing the need for direct YAML file manipulation. It has evolved alongside the <I>gh</I> tool, adapting to new features and configuration needs since its inception.


title: SYNOPSIS
content:
gh extension <command> [flags]<br><br><b>Available Commands:</b><br><i>  gh extension create <name></i><br><i>  gh extension install {<repository> | <name>} [--pin <version_or_ref>] [--force]</i><br><i>  gh extension list [--json]</i><br><i>  gh extension remove <name></i><br><i>  gh extension upgrade {--all | <name>}</i><br><i>  gh extension [--help]</i>


title: PARAMETERS
content:
<b>-h, --help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays help information for the `gh extension` command or its specific subcommands.<br><br><b>--pin <version_or_ref></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Used with `install`. Specifies a particular Git version, tag, or branch to pin the extension to during installation. For example, `gh extension install owner/repo --pin v1.2.3`.<br><br><b>--force</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Used with `install`. Forces the installation, overwriting any existing extension with the same name without prompting for confirmation.<br><br><b>--all</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Used with `upgrade`. Upgrades all currently installed extensions to their latest available versions in one go.<br><br><b>--json</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Used with `list`. Outputs the list of installed extensions in machine-readable JSON format, which is useful for scripting and programmatic access.<br><br>


title: DESCRIPTION
content:
The `gh-extension` command is a vital component of the GitHub CLI (`gh`), specifically designed for managing custom extensions. These extensions empower users to enhance and personalize their `gh` command-line experience by integrating new commands or automating complex workflows.<br><br>Through `gh-extension`, users gain a comprehensive toolkit to interact with the extension ecosystem. It allows for the effortless <b>installation</b> of extensions directly from GitHub repositories, providing a streamlined way to expand functionality. Users can easily <b>list</b> all currently installed extensions to keep track of their setup, <b>remove</b> any unwanted or outdated extensions, and <b>upgrade</b> existing ones to their latest versions, ensuring they benefit from new features and bug fixes.<br><br>Additionally, `gh-extension` offers capabilities to <b>create</b> new extensions, fostering a community-driven approach where developers can build and share their own custom commands. This command plays a pivotal role in extending the GitHub CLI's capabilities far beyond its core features, cultivating a dynamic, adaptable, and highly personalized command-line environment for GitHub users.


title: CAVEATS
content:
<b>Security Risk:</b> Extensions run arbitrary code on your system. It is crucial to <b>only install extensions from trusted sources</b> to avoid potential security vulnerabilities or malicious scripts.<br><b>Compatibility:</b> While generally robust, extensions might occasionally encounter compatibility issues with major updates to the `gh` CLI or changes in the GitHub API, requiring updates from the extension's maintainer.


title: EXTENSION TYPES AND NAMING
content:
GitHub CLI extensions can be implemented as <b>shell scripts</b> (e.g., Bash, PowerShell) or <b>compiled binaries</b>. They must be executable and follow a specific naming convention: `gh-<command-name>`. When an extension is installed, it becomes available as a subcommand of `gh`, allowing you to run it using `gh <command-name>`.


title: INSTALLATION SOURCES
content:
Extensions are typically installed directly from GitHub repositories using the `owner/repo` syntax. The GitHub CLI automatically detects and installs the appropriate executable or script from the specified repository, making the installation process seamless for users.


title: HISTORY
content:
The GitHub CLI (`gh`) emerged as a powerful tool for interacting with GitHub from the command line, reaching general availability in 2020. The `gh-extension` mechanism was introduced as a core feature early in its development, reflecting a commitment to extensibility and community contribution. This design choice enabled users and developers to build and share custom commands, significantly expanding the CLI's native capabilities and fostering a highly modular ecosystem around the GitHub CLI.


title: SYNOPSIS
content:
<b><code>gh-formatting</code></b> [<i>OPTIONS</i>] [<i>FILES</i>...]<br><br><i>Hypothetically, it would take one or more files as arguments and apply specified formatting rules, or read from standard input.</i>


title: PARAMETERS
content:
<b><b><code>-s</code></b>, <b><code>--stdin</code></b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Hypothetically, reads input from standard input instead of files.</i><br><br><b><b><code>-o</code></b>, <b><code>--output</code></b> <I>FILE</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Hypothetically, writes formatted output to a specified file. If not provided, output would go to standard output.</i><br><br><b><b><code>-c</code></b>, <b><code>--check</code></b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Hypothetically, performs a dry run, checking for formatting issues without modifying any files. Returns a non-zero exit code if issues are found.</i><br><br><b><b><code>--fix</code></b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Hypothetically, attempts to automatically fix detected formatting issues in the specified files. This would modify files in place.</i><br><br><b><b><code>--style</code></b> <I>STYLE_NAME</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Hypothetically, specifies a predefined formatting style or preset (e.g., <b><code>github</code></b>, <b><code>commonmark</code></b>) to apply.</i><br><br><b><b><code>--config</code></b> <I>PATH</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Hypothetically, specifies a path to a custom configuration file (e.g., <b><code>.ghformattingrc</code></b>) that defines specific formatting rules.</i><br><br><b><b><code>--verbose</code></b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Hypothetically, prints detailed information about the formatting process and any detected issues.</i><br><br>


title: DESCRIPTION
content:
<i>The <b><code>gh-formatting</code></b> command, if it existed, would serve as a utility to ensure consistency and readability of content intended for GitHub, such as Markdown files for issues, pull requests, wikis, or project documentation. It could automate common formatting tasks like enforcing Markdown style guides, pretty-printing configuration files (e.g., YAML, JSON), and linting code snippets embedded in Markdown.<br><br>Its purpose would be to improve collaboration by maintaining uniform presentation across various types of GitHub content, making contributions clearer and easier to review for project maintainers.</i>


title: CAVEATS
content:
<i>It is important to note that <b><code>gh-formatting</code></b> is <b>not a standard or officially recognized Linux command</b> or a subcommand of the GitHub CLI (<b><code>gh</code></b>). This analysis describes a <b>hypothetical command</b> based on its suggestive name, outlining what such a tool might conceptually provide for GitHub-related content formatting. Users should rely on standard text formatting tools, linters, and the <b><code>gh</code></b> CLI for specific GitHub interactions and content preparation.</i>


title: <B>PURPOSE & SCOPE (HYPOTHETICAL)</B>
content:
<i>A tool like <b><code>gh-formatting</code></b> would bridge the gap between general text formatting and GitHub's specific display and collaboration features. Its scope would ideally extend beyond simple Markdown to encompass common configuration file types (YAML, JSON) and potentially integrate with `git` hooks to enforce formatting standards before commits, ensuring all content pushed to GitHub repositories adheres to project guidelines.</i>


title: <B>INTEGRATION WITH GITHUB CLI (HYPOTHETICAL)</B>
content:
<i>If integrated as a <b><code>gh</code></b> subcommand (e.g., <b><code>gh format</code></b>), it could potentially be used directly for preparing content for issues (e.g., <b><code>gh issue create --body-file <(gh-formatting my_issue_body.md)</code></b>) or pull requests, streamlining the contribution workflow by automating content styling before submission.</i>


title: HISTORY
content:
<i>As <b><code>gh-formatting</code></b> is a hypothetical command, it does not have a documented history of development or usage. Conceptually, its design would likely be influenced by the growing need for automated content consistency in collaborative environments like GitHub, drawing inspiration from existing code formatters and Markdown linters that improve developer experience and project maintainability.</i>


title: SEE ALSO
content:
gh(1) (GitHub CLI), markdownlint (various implementations for Markdown linting), prettier (multi-language code formatter), yamllint (YAML linter)


title: PARAMETERS
content:
<b><b>create</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Creates a new gist from one or more files, or from standard input.<br><i>Usage:</i> <b>gh gist create</b> [<i>&lt;file&gt;...</i>] [<i>--desc &lt;string&gt;</i>] [<i>--public</i>] [<i>--web</i>]<br><i>Options:</i><br><b>--desc</b> <i>&lt;string&gt;</i>: A description for the gist.<br><b>--public</b>: Makes the new gist public (default is secret).<br><b>--web</b>: Opens the newly created gist in a web browser.<br><b>[<i>&lt;file&gt;...</i>]</b>: One or more files to include in the gist. Use '-' for standard input.<br><br><b><b>list</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Lists your gists.<br><i>Usage:</i> <b>gh gist list</b> [<i>--limit &lt;int&gt;</i>] [<i>--public</i>] [<i>--secret</i>]<br><i>Options:</i><br><b>--limit</b> <i>&lt;int&gt;</i>: Maximum number of gists to list (default: 30).<br><b>--public</b>: Lists only public gists.<br><b>--secret</b>: Lists only secret gists.<br><br><b><b>view</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Views the content of a specific gist.<br><i>Usage:</i> <b>gh gist view</b> {<i>&lt;gist id&gt;</i> | <i>&lt;gist url&gt;</i>} [<i>--files &lt;string&gt;</i>] [<i>--raw</i>]<br><i>Arguments:</i><br><b>{<i>&lt;gist id&gt;</i> | <i>&lt;gist url&gt;</i>}</b>: The ID or full URL of the gist to view.<br><i>Options:</i><br><b>--files</b> <i>&lt;string&gt;</i>: Comma-separated list of specific files within the gist to display.<br><b>--raw</b>: Prints the raw content of the gist files, rather than formatted output.<br><br><b><b>edit</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Edits an existing gist, allowing changes to its description, files, or visibility.<br><i>Usage:</i> <b>gh gist edit</b> {<i>&lt;gist id&gt;</i> | <i>&lt;gist url&gt;</i>} [<i>&lt;file&gt;...</i>] [<i>--add &lt;string&gt;</i>] [<i>--desc &lt;string&gt;</i>] [<i>--filename &lt;string&gt;</i>] [<i>--public</i>]<br><i>Arguments:</i><br><b>{<i>&lt;gist id&gt;</i> | <i>&lt;gist url&gt;</i>}</b>: The ID or full URL of the gist to edit.<br><b>[<i>&lt;file&gt;...</i>]</b>: Files to update in the gist. Opens in editor if not specified.<br><i>Options:</i><br><b>--add</b> <i>&lt;string&gt;</i>: Adds a new file to the gist.<br><b>--desc</b> <i>&lt;string&gt;</i>: Provides a new description for the gist.<br><b>--filename</b> <i>&lt;string&gt;</i>: Specifies the filename to edit when multiple files exist.<br><b>--public</b>: Makes the gist public (if it's currently secret).<br><br><b><b>delete</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Deletes a gist.<br><i>Usage:</i> <b>gh gist delete</b> {<i>&lt;gist id&gt;</i> | <i>&lt;gist url&gt;</i>} [<i>--confirm</i>]<br><i>Arguments:</i><br><b>{<i>&lt;gist id&gt;</i> | <i>&lt;gist url&gt;</i>}</b>: The ID or full URL of the gist to delete.<br><i>Options:</i><br><b>--confirm</b>: Confirms deletion without an interactive prompt.<br><br><b><b>fork</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Forks a gist, creating a copy under your account.<br><i>Usage:</i> <b>gh gist fork</b> {<i>&lt;gist id&gt;</i> | <i>&lt;gist url&gt;</i>}<br><i>Arguments:</i><br><b>{<i>&lt;gist id&gt;</i> | <i>&lt;gist url&gt;</i>}</b>: The ID or full URL of the gist to fork.<br><br><b><b>star</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Stars a gist.<br><i>Usage:</i> <b>gh gist star</b> {<i>&lt;gist id&gt;</i> | <i>&lt;gist url&gt;</i>}<br><i>Arguments:</i><br><b>{<i>&lt;gist id&gt;</i> | <i>&lt;gist url&gt;</i>}</b>: The ID or full URL of the gist to star.<br><br><b><b>unstar</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Unstars a previously starred gist.<br><i>Usage:</i> <b>gh gist unstar</b> {<i>&lt;gist id&gt;</i> | <i>&lt;gist url&gt;</i>}<br><i>Arguments:</i><br><b>{<i>&lt;gist id&gt;</i> | <i>&lt;gist url&gt;</i>}</b>: The ID or full URL of the gist to unstar.<br><br><b><b>-h</b>, <b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays help information for the <i>gh gist</i> command or its subcommands. Available for each subcommand (e.g., <b>gh gist create --help</b>).<br><br>


title: DESCRIPTION
content:
<i>gh-gist</i> is a powerful subcommand of the GitHub CLI (<i>gh</i>) designed for seamless interaction with GitHub Gists directly from your terminal. It allows users to perform a wide array of operations on their gists, including creating new gists from files or standard input, listing existing gists, viewing their content, editing them, and even deleting them. Beyond basic CRUD operations, <i>gh-gist</i> also supports actions like forking gists, and starring or unstarring them, mirroring the functionality available on the GitHub website. This command-line interface streamlines workflows for developers who frequently use gists for sharing code snippets, notes, or configuration files, eliminating the need to switch between the terminal and a web browser. It integrates well into scripting and automation tasks, enhancing productivity for GitHub users.


title: CAVEATS
content:
<ul><li>Requires the GitHub CLI (<i>gh</i>) to be installed and properly authenticated with your GitHub account (via <b>gh auth login</b>).</li><li>Active internet connectivity is essential for all operations.</li><li>GitHub API rate limits apply to gist operations; excessive requests may temporarily block access.</li><li>Interactive editing with <b>gh gist edit</b> relies on your <i>EDITOR</i> or <i>VISUAL</i> environment variables to launch a text editor. Ensure these are set up correctly.</li></ul>


title: AUTHENTICATION
content:
All <i>gh gist</i> operations require the user to be authenticated with GitHub. This is typically achieved by running <b>gh auth login</b> and following the prompts.


title: GIST IDENTIFIERS
content:
When specifying a gist for commands like <b>view</b>, <b>edit</b>, <b>delete</b>, <b>fork</b>, <b>star</b>, or <b>unstar</b>, you can use either the unique 32-character gist ID (e.g., <i>'a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6'</i>) or the full URL to the gist (e.g., <i>'https://gist.github.com/username/a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6'</i>).


title: FILE HANDLING
content:
When creating or editing gists, you can provide local file paths. For <b>gh gist create</b>, using <i>'-'</i> as the file argument tells the command to read content from standard input (stdin).


title: HISTORY
content:
The <i>gh</i> command-line tool was developed by GitHub to provide a native CLI for interacting with various GitHub services. <i>gh-gist</i> is an integral part of this tool, introduced to enable seamless management of gists directly from the terminal. Its development aims to improve developer productivity by allowing common GitHub operations, including gist management, to be performed without leaving the command line, thereby complementing and extending the functionality available through the web interface.


title: PARAMETERS
content:
<b>create</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Creates a new issue. Common options include: <b><I>--title &lt;string&gt;</I></b> (issue title), <b><I>--body &lt;string&gt;</I></b> (issue body), <b><I>--label &lt;name&gt;</I></b> (add a label), <b><I>--assignee &lt;name&gt;</I></b> (assign an individual), <b><I>--milestone &lt;name&gt;</I></b> (associate with a milestone), <b><I>--project &lt;name&gt;</I></b> (add to a project).<br><br><b>list</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Lists issues in a repository. Common filters include: <b><I>--state &lt;string&gt;</I></b> (e.g., 'open', 'closed', 'all'), <b><I>--assignee &lt;name&gt;</I></b>, <b><I>--author &lt;name&gt;</I></b>, <b><I>--label &lt;name&gt;</I></b>, <b><I>--milestone &lt;name&gt;</I></b>, <b><I>--search &lt;query&gt;</I></b>, and <b><I>--limit &lt;int&gt;</I></b> (number of issues to fetch).<br><br><b>view &lt;number | URL&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays details of a specific issue. Use <b><I>--web</I></b> to open in a browser or <b><I>--comments</I></b> to show comments.<br><br><b>edit &lt;number | URL&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Edits an existing issue. Options for modification are similar to <b><I>create</I></b>, including <b><I>--title</I></b>, <b><I>--body</I></b>, <b><I>--add-label</I></b>, <b><I>--remove-label</I></b>, <b><I>--add-assignee</I></b>, <b><I>--remove-assignee</I></b>, <b><I>--milestone</I></b>, and <b><I>--project</I></b>.<br><br><b>close &lt;number | URL&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Closes an issue. An optional <b><I>--reason &lt;string&gt;</I></b> can be provided (e.g., 'completed', 'not planned').<br><br><b>reopen &lt;number | URL&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Reopens a closed issue.<br><br><b>search &lt;query&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Searches for issues across repositories matching a query. Supports filtering similar to <b><I>list</I></b>, including <b><I>--state</I></b>, <b><I>--label</I></b>, <b><I>--assignee</I></b>, <b><I>--author</I></b>, and <b><I>--limit</I></b>.<br><br><b>status</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows a summary of open issues, assigned issues, and pull requests in the current repository, relevant to the authenticated user.<br><br><b>develop &lt;number | URL&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Creates a development branch linked to an issue, streamlining the workflow for addressing issues with code.<br><br><b>--repo &lt;owner/repo&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;A global flag for <b><I>gh</I></b> commands that specifies the GitHub repository to operate on, overriding the current directory's inferred repository.<br><br><b>--help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays help information for the <b><I>gh issue</I></b> command or a specific subcommand.<br><br>


title: DESCRIPTION
content:
The <b><I>gh issue</I></b> command is a powerful subcommand of the GitHub CLI (<b><I>gh</I></b>) that enables users to interact with GitHub issues directly from their terminal.<br>It provides comprehensive functionalities to create, list, view, edit, close, reopen, and search issues across repositories. This streamlines issue management workflows for developers who prefer a command-line interface over a web browser.<br>To function, it requires prior authentication with GitHub via <b><I>gh auth login</I></b> and typically operates within the context of a Git repository, though a target repository can be specified using the <b><I>--repo</I></b> flag.


title: CAVEATS
content:
The <b><I>gh issue</I></b> command is part of the GitHub CLI (<b><I>gh</I></b>) and requires it to be installed on your system. It also necessitates an active GitHub account and successful authentication via <b><I>gh auth login</I></b>. All operations require internet connectivity to communicate with GitHub's API.


title: INTERACTIVE PROMPTS
content:
Many <b><I>gh issue</I></b> subcommands, particularly <b><I>create</I></b> and <b><I>edit</I></b>, offer intuitive interactive prompts if essential arguments or options are omitted. This guides users through the process and enhances usability.


title: CONTEXT AWARENESS
content:
When executed within a cloned Git repository, <b><I>gh issue</I></b> automatically detects the current GitHub repository context. This eliminates the need to explicitly specify the repository for most commands, simplifying common workflows.


title: HISTORY
content:
The GitHub CLI (<b><I>gh</I></b>), which includes the <b><I>gh issue</I></b> subcommand, was officially released by GitHub in 2020. Issue management was a fundamental feature from its inception, aiming to provide a seamless, native command-line experience for GitHub users, extending capabilities previously confined to the web interface or API. It continues to be actively developed and maintained by GitHub.


title: SYNOPSIS
content:
<b>gh issue create</b> [<I>flags</I>]<br>or<br><b>gh issue create</b> <I>--title &lt;string&gt;</I> <I>--body &lt;string&gt;</I> [<I>flags</I>]


title: PARAMETERS
content:
<b><I>--assignee &lt;logins&gt;</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Assign people to the issue by their GitHub login.<br><br><b><I>--body &lt;string&gt;</I>, <I>-b &lt;string&gt;</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Supply the issue's main body content.<br><br><b><I>--body-file &lt;file&gt;</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Read the issue body text from a specified file (use '-' for stdin).<br><br><b><I>--editor-body</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Forces opening a text editor for the issue body, even if content is provided by other flags.<br><br><b><I>--label &lt;strings&gt;</I>, <I>-l &lt;strings&gt;</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Attach labels to the issue by name (can be specified multiple times).<br><br><b><I>--milestone &lt;name&gt;</I>, <I>-m &lt;name&gt;</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Add the issue to a milestone by its name.<br><br><b><I>--no-editor</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Skip opening an editor for the issue body, even in interactive mode.<br><br><b><I>--project &lt;name&gt;</I>, <I>-p &lt;name&gt;</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Add the issue to a project by its name.<br><br><b><I>--repo &lt;[HOST/]OWNER/REPO&gt;</I>, <I>-R &lt;[HOST/]OWNER/REPO&gt;</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Select another repository to create the issue in (global gh flag).<br><br><b><I>--template &lt;file&gt;</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Use a markdown file as a template to pre-populate the issue body.<br><br><b><I>--title &lt;string&gt;</I>, <I>-t &lt;string&gt;</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Provide a title for the new issue.<br><br><b><I>--web</I>, <I>-w</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Open the issue creation form in the default web browser instead of the terminal.<br><br>


title: DESCRIPTION
content:
The <b>gh issue create</b> command is a core feature of the GitHub CLI, empowering developers to create new issues on GitHub repositories directly from their command line interface. This command supports both an interactive mode, which guides the user through prompts for details like title and body, and a non-interactive mode that accepts issue details via command-line flags. The non-interactive mode is ideal for scripting and automation.<br><br>Users can specify various attributes for the new issue, including its title, body content, associated labels, assigned users, relevant projects, and milestones. Additionally, it supports applying predefined issue templates to standardize content. By integrating issue creation into the terminal workflow, <b>gh issue create</b> significantly streamlines the process for individual developers and teams, enhancing productivity and maintaining context within the development environment. Upon successful creation, it provides the URL of the new issue.


title: CAVEATS
content:
The <b>gh issue create</b> command requires the GitHub CLI (<I>gh</I>) to be installed and authenticated to a GitHub account with appropriate permissions to create issues in the target repository. Network connectivity is also necessary for communication with GitHub's API. If neither <I>--title</I> nor <I>--body</I> flags are provided, the command will default to an interactive mode, prompting the user for input.


title: INTERACTIVE MODE
content:
When <b>gh issue create</b> is executed without specifying a title or body via flags, it defaults to an interactive mode. In this mode, the command prompts the user step-by-step for the issue's title, body, and then offers interactive choices for labels, assignees, projects, and milestones, making it user-friendly for manual issue creation.


title: USING TEMPLATES
content:
The <I>--template</I> flag is a powerful feature for standardizing issue content. By pointing to a Markdown file containing a predefined structure or boilerplate text, users can ensure consistency across bug reports, feature requests, or other types of issues within a project, saving time and ensuring all necessary information is collected.


title: HISTORY
content:
The GitHub CLI (<I>gh</I>) was officially released in late 2020, aiming to consolidate GitHub's features into a unified command-line interface. <b>gh issue create</b> has been a fundamental command since its early iterations, continually evolving with new options to support more nuanced and automated issue management workflows, reflecting GitHub's commitment to developer productivity and CLI-centric operations.


title: SYNOPSIS
content:
<b>gh label</b> <I>list</I> [<I>&lt;owner&gt;/&lt;repo&gt;</I>] [<I>flags</I>]<br><b>gh label</b> <I>create</I> [<I>&lt;owner&gt;/&lt;repo&gt;</I>] <I>&lt;name&gt;</I> [<I>flags</I>]<br><b>gh label</b> <I>edit</I> [<I>&lt;owner&gt;/&lt;repo&gt;</I>] <I>&lt;name&gt;</I> [<I>flags</I>]<br><b>gh label</b> <I>delete</I> [<I>&lt;owner&gt;/&lt;repo&gt;</I>] <I>&lt;name&gt;</I> [<I>flags</I>]


title: PARAMETERS
content:
<b><I>list</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Lists all labels in the specified or current repository.<br><br><b><I>create</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Creates a new label with the given name, color, and optional description.<br><br><b><I>edit</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Modifies an existing label. You can change its name, color, or description.<br><br><b><I>delete</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Deletes a label from the repository. This action is irreversible.<br><br><b>-R, --repo <I>&lt;owner&gt;/&lt;repo&gt;</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;(Global Flag) Specifies the GitHub repository to operate on. If omitted, it defaults to the current directory's linked repository.<br><br><b>--color <I>&lt;string&gt;</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;(For <I>create</I>/<I>edit</I>) Sets the color for the label. Can be a 6-digit hex code (e.g., <I>#FF0000</I>) or a standard color name (e.g., <I>red</I>, <I>blue</I>).<br><br><b>--description <I>&lt;string&gt;</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;(For <I>create</I>/<I>edit</I>) Provides a descriptive text for the label.<br><br><b>--name <I>&lt;string&gt;</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;(For <I>edit</I>) Specifies the new name for the label.<br><br><b>--search <I>&lt;string&gt;</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;(For <I>list</I>) Filters labels by name, showing only those that contain the specified string.<br><br><b>--limit <I>&lt;int&gt;</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;(For <I>list</I>) Sets the maximum number of labels to fetch. Defaults to 30.<br><br><b>--json <I>&lt;fields&gt;</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;(For <I>list</I>) Outputs labels in JSON format, allowing selection of specific fields (e.g., <I>name,color,description</I>).<br><br><b>--web</b><br>&nbsp;&nbsp;&nbsp;&nbsp;(For <I>list</I>) Opens the labels page for the repository in your default web browser.<br><br><b>--force, --yes</b><br>&nbsp;&nbsp;&nbsp;&nbsp;(For <I>create</I>/<I>edit</I>/<I>delete</I>) Skips confirmation prompts, proceeding directly with the operation.<br><br>


title: DESCRIPTION
content:
<i>gh-label</i> is a subcommand of the official GitHub CLI (<B>gh</B>), designed for efficient management of repository labels directly from the command line. Labels are crucial for organizing and categorizing issues and pull requests on GitHub. This command empowers users to <B>list</B>, <B>create</B>, <B>edit</B>, and <B>delete</B> labels, providing a robust interface for maintaining consistent labeling practices across projects. It's particularly useful for scripting, automating repository setup, and streamlining workflows for developers and project managers who prefer to work within the terminal environment.


title: CAVEATS
content:
Using <B>gh-label</B> requires the GitHub CLI (<B>gh</B>) to be installed and authenticated to your GitHub account. Ensure you have the necessary permissions (e.g., write access) on the target repository to create, edit, or delete labels. Label names are case-insensitive for identification but preserve their case upon creation.


title: DEFAULT REPOSITORY CONTEXT
content:
If you execute <B>gh label</B> commands from within a local Git repository that is linked to a GitHub remote, the command will automatically operate on that repository unless a different one is specified using the <I>--repo</I> flag.


title: INTERACTIVE BEHAVIOR
content:
When creating or editing labels, <B>gh-label</B> may prompt for missing required information (like color for creation) or confirmation for destructive actions (like deletion) if not provided via flags like <I>--color</I> or <I>--yes</I>.


title: HISTORY
content:
The <B>gh-label</B> command is an integral part of the GitHub CLI, which was first announced in 2019 and reached general availability in 2020. As labels are fundamental to organizing work on GitHub, the ability to manage them via the command line was a core feature from the early development phases of the CLI, reflecting GitHub's commitment to empowering developers with powerful command-line tools for their workflows.


title: PARAMETERS
content:
<b><i>&lt;URL&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The specific GitHub URL to open. This can be a link to a repository, an issue, a pull request, or any valid GitHub web address that the extension is configured to handle.<br><br>


title: DESCRIPTION
content:
<i><b>gh-mintty</b></i> is a specialized extension for the <i><b>GitHub CLI</b></i> (<i><b>gh</b></i>). Its primary function is to facilitate the opening of GitHub-related URLs, such as repositories, issues, or pull requests, directly within the <i><b>mintty</b></i> terminal environment. <br><br>While <i><b>mintty</b></i> is a popular terminal emulator predominantly used in Windows and Cygwin environments, this extension provides a bridge for users who operate the <i><b>gh</b></i> CLI within such setups. It streamlines the workflow by allowing commands like <i><b>gh mintty &lt;URL&gt;</b></i> to automatically launch the specified GitHub resource, typically in a web browser or through a configured system handler, leveraging the <i><b>mintty</b></i> context. <br><br>It is not a standalone Linux command in the traditional sense, but rather an enhancement for the <i><b>gh</b></i> CLI, specifically tailored for users of <i><b>mintty</b></i>, potentially including those utilizing Windows Subsystem for Linux (WSL) if <i><b>mintty</b></i> is their chosen terminal.


title: CAVEATS
content:
This command is an extension of the <b>gh</b> CLI and is primarily designed for environments where <b>mintty</b> is used as the terminal emulator, typically Windows or Cygwin. It is not a native, standalone Linux command. Usage on a pure Linux system without <b>mintty</b> installed would be illogical or require specific configurations (e.g., via WSL where <b>mintty</b> is present). It requires both the <b>gh</b> CLI and <b>mintty</b> to be installed and properly configured on the system.


title: INSTALLATION
content:
To install <b>gh-mintty</b>, use the GitHub CLI's extension manager: <i><b>gh extension install mitchty/gh-mintty</b></i>


title: REQUIREMENTS
content:
Requires the <b>GitHub CLI</b> (<b>gh</b>) to be installed, along with the <b>mintty</b> terminal emulator configured on the system.


title: HISTORY
content:
The <b>gh-mintty</b> extension was created by <i>mitchty</i> as a community-contributed addition to the <b>GitHub CLI</b>'s ecosystem. Its development aimed to address the specific need of <b>mintty</b> users who wanted a more integrated experience when interacting with GitHub URLs from their terminal, leveraging the extensibility features of the <b>gh</b> CLI. As a niche utility, its history is characterized by its focused purpose to enhance workflow for a particular user base.


title: SYNOPSIS
content:
<B>gh pr</B> <I>&lt;subcommand&gt;</I> <I>[flags]</I><br><br>Examples:<br>&nbsp;&nbsp;<B>gh pr list</B> <I>--state</I> open<br>&nbsp;&nbsp;<B>gh pr create</B> <I>--title</I> "Fix bug" <I>--body-file</I> "./description.md"<br>&nbsp;&nbsp;<B>gh pr checkout</B> 123


title: PARAMETERS
content:
<b><I>create</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Create a new pull request. Common flags include <I>--title</I> for the title, <I>--body</I> or <I>--body-file</I> for the description, <I>--base</I> for the target branch, and <I>--head</I> for the source branch.<br><br><b><I>list</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;List pull requests in the current repository. Can be filtered by <I>--state</I> (open, closed, merged), <I>--author</I>, <I>--assignee</I>, <I>--reviewer</I>, <I>--label</I>, or a <I>--search</I> query.<br><br><b><I>view</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;View details of a specific pull request by number or branch name. Use <I>--web</I> to open the PR in your default web browser.<br><br><b><I>checkout</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Check out a pull request's branch locally in your Git repository, making it easy to review and test changes.<br><br><b><I>merge</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Merge a pull request. Options include <I>--rebase</I> to rebase and merge, <I>--squash</I> to squash and merge, and <I>--delete-branch</I> to remove the head branch after merging.<br><br><b><I>close</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Close a pull request by its number or associated branch name.<br><br><b><I>ready</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Mark a draft pull request as ready for review, changing its status from 'Draft' to 'Open'.<br><br><b><I>diff</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;View the diff (changes) of a pull request. Can be used with a PR number or branch name.<br><br><b><I>status</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show the status of pull requests related to the current Git branch, including checks and reviews.<br><br><b><I>--help</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show help for the <B>gh pr</B> command or any of its specific subcommands (e.g., <B>gh pr create --help</B>).<br><br>


title: DESCRIPTION
content:
The <B>gh pr</B> command is a powerful subcommand of the <I>GitHub CLI</I> (<B>gh</B>) that allows users to interact with and manage pull requests on GitHub repositories directly from their command line. It provides functionalities to list, view, create, check out, merge, close, reopen, and mark pull requests as ready for review. This command streamlines development workflows by reducing the need to switch to the web interface. It integrates seamlessly with Git, allowing operations like checking out a PR's branch for local review. <B>gh pr</B> is an essential tool for developers working with GitHub, enhancing productivity and maintaining context within the terminal environment.


title: CAVEATS
content:
Requires the <I>GitHub CLI</I> (<B>gh</B>) to be installed on your system and authenticated with your GitHub account. Authentication is typically done via <B>gh auth login</B>. An active internet connection is essential for all operations as it communicates directly with GitHub's API.


title: AUTHENTICATION REQUIREMENT
content:
To use <B>gh pr</B> commands, you must first authenticate the GitHub CLI with your GitHub account. This is a one-time setup performed using the command: <B>gh auth login</B>.


title: SEAMLESS GIT INTEGRATION
content:
<B>gh pr</B> commands are designed to integrate seamlessly with Git workflows. For instance, <B>gh pr checkout</B> automatically fetches the pull request branch, and commands like <B>gh pr create</B> leverage your local Git repository's information to propose defaults.


title: HISTORY
content:
The <B>gh pr</B> command is a core component of the <I>GitHub CLI</I> (<B>gh</B>), an official command-line tool developed by GitHub. The <I>GitHub CLI</I> was first officially released in 2020, aiming to provide developers with a comprehensive and intuitive command-line interface for common GitHub workflows, significantly streamlining pull request management directly from the terminal.


title: PARAMETERS
content:
<b><b>-b</b>, <b>--base</b> <<i>branch</i>></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the branch into which you want your changes merged (e.g., <i>main</i>, <i>develop</i>). Defaults to the default branch of the repository.<br><br><b><b>-h</b>, <b>--head</b> <<i>branch</i>></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the branch that contains your changes. Defaults to the current branch. Can be in the format <i>owner:branch</i> for forks.<br><br><b><b>-t</b>, <b>--title</b> <<i>string</i>></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Provides the title for the pull request. If not provided, the command will prompt interactively or infer from a single commit message.<br><br><b><b>--body</b> <<i>string</i>></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Provides the body (description) for the pull request. If not provided, the command will prompt interactively or use commit messages.<br><br><b><b>-F</b>, <b>--body-file</b> <<i>file</i>></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Reads the pull request body from a specified file.<br><br><b><b>-d</b>, <b>--draft</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Creates the pull request as a draft, indicating it's not yet ready for review.<br><br><b><b>-l</b>, <b>--label</b> <<i>label-name</i>></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Adds one or more labels to the pull request. Can be used multiple times.<br><br><b><b>-a</b>, <b>--assignee</b> <<i>login</i>></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Assigns one or more users to the pull request. Can be used multiple times.<br><br><b><b>-r</b>, <b>--reviewer</b> <<i>login</i>></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Requests one or more users to review the pull request. Can be used multiple times.<br><br><b><b>-m</b>, <b>--milestone</b> <<i>milestone-name</i>></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Associates the pull request with a specific milestone by name.<br><br><b><b>-i</b>, <b>--issue</b> <<i>issue-id</i>></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Closes a specified issue when the pull request is merged, by automatically adding appropriate keywords to the PR description.<br><br><b><b>--web</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Opens the newly created pull request in the default web browser after creation.<br><br>


title: DESCRIPTION
content:
The <b>gh pr create</b> command is a fundamental feature of the GitHub CLI (<i>gh</i>), designed to streamline the process of initiating a pull request directly from the terminal. It significantly automates the manual work involved in creating a PR via the web UI, empowering developers to quickly propose changes from their local branches to a remote repository.<br><br>This command supports various modes, including interactive prompting for title and description, specifying target branches, and linking issues. It's particularly useful for integrating pull request creation seamlessly into command-line workflows and scripting, enhancing developer productivity by keeping the context within the terminal environment.


title: CAVEATS
content:
To use <b>gh pr create</b>, the GitHub CLI (<i>gh</i>) must be installed and authenticated to GitHub.<br>The command must be executed within a Git repository that is linked to a remote GitHub repository.<br>The <i>head</i> branch containing the changes must already be pushed to the remote repository before creating the PR.<br>If title or body are not provided as flags, the command defaults to an interactive mode, prompting the user for input.


title: INTERACTIVE MODE
content:
When neither the <i>--title</i> nor the <i>--body</i> flags are specified, <b>gh pr create</b> defaults to an interactive prompt. This mode guides the user through entering the pull request's title and description, offering a user-friendly experience directly in the terminal.


title: DRAFT PULL REQUESTS
content:
The <i>--draft</i> flag enables the creation of a pull request in a draft state. This is useful for signaling that the work is still in progress and not yet ready for formal review, preventing accidental merges and allowing for iterative development.


title: HISTORY
content:
The GitHub CLI was initially announced in 2019 and reached general availability in September 2020. <b>gh pr create</b> has been a cornerstone of its functionality since its early development, fulfilling the primary goal of bringing common GitHub workflows, especially pull request management, directly to the command line.


title: SYNOPSIS
content:
<b>gh pr merge</b> [<I>PR_NUMBER</I> | <I>PR_URL</I> | <I>BRANCH</I>] [flags]<br>
<I>Note: If no argument is provided, the command defaults to the current branch's associated pull request.</I>


title: PARAMETERS
content:
<b><b>--merge, -m</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Use a merge commit strategy (default).<br><br><b><b>--squash, -s</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Use the squash and merge strategy.<br><br><b><b>--rebase, -r</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Use the rebase and merge strategy.<br><br><b><b>--delete-branch, -d</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Delete the head branch after merging the pull request.<br><br><b><b>--auto, -a</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enable auto-merge for the pull request.<br><br><b><b>--disable-auto-merge</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Disable auto-merge for the pull request.<br><br><b><b>--admin</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Bypass any applicable branch protection rules (requires admin privileges).<br><br><b><b>--body &lt;string&gt;, -b &lt;string&gt;</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the body text for the merge commit.<br><br><b><b>--body-file &lt;file&gt;, -F &lt;file&gt;</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Read the merge commit body from the specified file.<br><br><b><b>--subject &lt;string&gt;, -S &lt;string&gt;</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the subject for the merge commit.<br><br><b><b>--edit-body</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prompt an editor to compose the merge commit body.<br><br>


title: DESCRIPTION
content:
The `gh pr merge` command facilitates the merging of a pull request directly from your terminal using the GitHub CLI. It allows users to merge a specified pull request using various merge strategies: standard merge commit, squashing commits, or rebasing. This command streamlines the workflow for developers, enabling them to complete the pull request lifecycle without leaving the command line environment. It can also automatically delete the head branch upon successful merge and supports auto-merge capabilities, allowing a PR to be merged automatically once all requirements (like passing checks) are met.


title: CAVEATS
content:
<ul><li>Requires the GitHub CLI (<b>gh</b>) to be installed and authenticated with your GitHub account.</li><li><b>Permissions:</b> You must have write access to the repository to merge pull requests.</li><li><b>Branch Protection Rules:</b> Repository branch protection rules might prevent certain merge types or require the <b>--admin</b> flag to bypass.</li><li><b>Internet Connectivity:</b> Requires an active internet connection to interact with GitHub.</li></ul>


title: HISTORY
content:
The `gh pr merge` command is a fundamental component of the GitHub CLI, which was officially released in 2020. As a native command-line interface for GitHub, `gh` aimed to bring GitHub's functionality directly to the terminal, streamlining developer workflows. `gh pr merge` was a core feature from its early development, offering a powerful way to manage pull requests without switching contexts to the web interface, thereby significantly improving efficiency for command-line centric users. Its evolution reflects the broader adoption of CLI tools for developer operations.


title: PARAMETERS
content:
<b><I>&lt;branch_name&gt;</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Refers to a specific Git branch (e.g., <I>main</I>, <I>feature-X</I>) within the context of the repository.<br><br><b><I>&lt;tag_name&gt;</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Refers to a specific Git tag (e.g., <I>v1.0.0</I>, <I>release-candidate</I>) in the repository.<br><br><b><I>#&lt;PR_number&gt;</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Refers to a GitHub Pull Request by its number (e.g., <I>#123</I>). <I>gh</I> interprets this as a reference to the PR's merge commit or head branch, depending on the specific command's context.<br><br><b><I>&lt;SHA&gt;</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Refers to a specific commit by its full or partial SHA hash (e.g., <I>abcdef1</I>, <I>1234567890abcdef</I>).<br><br><b><I>&lt;owner&gt;/&lt;repo&gt;[#&lt;PR_number&gt;]</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Refers to a pull request in a different GitHub repository (e.g., <I>cli/cli#123</I>).<br><br><b><I>HEAD</I>, <I>MERGE_HEAD</I>, <I>ORIG_HEAD</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Standard Git symbolic references pointing to the current commit, the commit being merged, or the previous HEAD, respectively.<br><br>


title: DESCRIPTION
content:
The <b><I>gh help reference</I></b> topic provides detailed information on how the GitHub CLI (<I>gh</I>) interprets various types of Git and GitHub references when used as arguments in <I>gh</I> commands. This comprehensive guide covers understanding branch names, tag names, pull request numbers, commit SHAs, and special Git pointers like <I>HEAD</I>. It clarifies the precise syntax for specifying these references, explains how ambiguous references are resolved by the CLI, and outlines the precedence rules applied during resolution. This help topic is absolutely crucial for users who need to precisely target specific commits, branches, tags, or pull requests across different <I>gh</I> commands, ensuring accurate and intended operations and avoiding potential misinterpretations of arguments.


title: CAVEATS
content:
The term <I>gh-reference</I> is not a standalone executable command. It directly refers to the <I>reference</I> help topic within the GitHub CLI (<I>gh</I>) utility, accessed via the command <I>gh help reference</I>. This help topic itself does not accept command-line parameters; instead, it provides documentation on the various types of references that <I>gh</I> commands expect as arguments for their own operations.


title: REFERENCE RESOLUTION LOGIC
content:
The <I>gh help reference</I> documentation details the specific order and logic <I>gh</I> employs to resolve potentially ambiguous reference strings provided as arguments. This typically involves checking for exact matches first, then partial matches, and prioritizing local branches, remote branches, and tags in a defined sequence. Understanding this resolution logic is vital to prevent unintended operations, especially when providing abbreviated or potentially ambiguous references to <I>gh</I> commands, ensuring the correct Git object is targeted.


title: HISTORY
content:
The <I>reference</I> help topic is an integral part of the GitHub CLI (<I>gh</I>) project. The <I>gh</I> CLI was first publicly released in beta in 2020. As the CLI matured and its command set expanded to cover more GitHub features, the necessity for clear and comprehensive documentation on how it handles various Git and GitHub-specific references became paramount. This help topic has evolved to cover the expanding forms of references supported by <I>gh</I> commands, ensuring users can accurately interact with their repositories.


title: SYNOPSIS
content:
<B>gh release</B> <I>&lt;command&gt;</I> <I>[flags]</I><br><br>Common commands include:<br>  <B>gh release create</B> <I>&lt;tag-name&gt;</I> <I>[<file>...]</I> <I>[flags]</I><br>  <B>gh release list</B> <I>[flags]</I><br>  <B>gh release view</B> <I>[&lt;tag-name&gt; | &lt;id&gt;]</I> <I>[flags]</I><br>  <B>gh release edit</B> <I>&lt;tag-name&gt;</I> <I>[flags]</I><br>  <B>gh release delete</B> <I>&lt;tag-name&gt;</I> <I>[flags]</I><br>  <B>gh release download</B> <I>[&lt;tag-name&gt;]</I> <I>[flags]</I>


title: PARAMETERS
content:
<b><I>--repo <[HOST/]OWNER/REPO></I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the repository to operate on, e.g., <I>owner/repo-name</I>.<br><br><b><I>--help</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display help information for the specific command or subcommand.<br><br><b><I>-t, --title <string></I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set the title of the release (used with <B>create</B> or <B>edit</B>).<br><br><b><I>-n, --notes <string></I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Provide release notes directly as a string (used with <B>create</B> or <B>edit</B>).<br><br><b><I>-F, --notes-file <file></I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Read release notes from the specified file (used with <B>create</B> or <B>edit</B>).<br><br><b><I>-d, --draft</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Create or modify a release as a draft (not yet published).<br><br><b><I>-p, --prerelease</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Mark the release as a pre-release.<br><br><b><I>--generate-notes</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Automatically generate release notes from Git history (used with <B>create</B>).<br><br><b><I>--target <branch></I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the target branch or commit for the release tag (used with <B>create</B>).<br><br><b><I>-L, --limit <int></I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Limit the number of results returned (e.g., for <B>list</B> or <B>download</B>).<br><br><b><I>-D, --dir <directory></I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the directory for downloading release assets (used with <B>download</B>).<br><br><b><I>--clobber</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Overwrite existing files when downloading assets (used with <B>download</B>).<br><br>


title: DESCRIPTION
content:
The <I>gh-release</I> functionality, typically accessed via the <B>gh release</B> subcommand of the GitHub CLI, is a powerful tool designed to streamline the management of GitHub releases directly from your command line. It provides a comprehensive set of functionalities for interacting with releases on your GitHub repositories.<br><br>Users can effortlessly create new releases, defining their tag names, release titles, and descriptions, and attach various assets like binaries or archives. Beyond creation, it allows for viewing details of existing releases, listing all releases for a repository, editing release information, and deleting releases when necessary. Furthermore, it facilitates downloading release assets, making it easy to fetch compiled binaries or other artifacts.<br><br>This command is an essential tool for developers and CI/CD pipelines, integrating release management directly into the development workflow without needing to navigate the GitHub web interface. It supports both public and private repositories, respecting user authentication and permissions.


title: CAVEATS
content:
Using <B>gh release</B> requires the GitHub CLI (<B>gh</B>) to be installed and properly authenticated with your GitHub account. Users must possess appropriate permissions on the target repository (e.g., write access) to create, edit, or delete releases. While <B>gh release create</B> can automatically create a tag if it doesn't exist, it is generally recommended to create the Git tag beforehand using <B>git tag</B> for better control. Be aware of GitHub's limitations on asset sizes and total repository storage.


title: AUTHENTICATION
content:
Before using any <B>gh</B> command, including <B>gh release</B>, you must authenticate your GitHub CLI instance by running <B>gh auth login</B>. This command links your CLI to your GitHub account, granting it the necessary permissions to manage repositories and releases securely.


title: ASSET UPLOADS
content:
When creating a new release, you can specify one or more files to upload as release assets by appending their paths to the <B>gh release create</B> command. For example: <B>gh release create v1.0.0 ./my-app.tar.gz ./checksums.txt</B>. Multiple assets can be added in a single command.


title: HISTORY
content:
The GitHub CLI (<B>gh</B>), which provides the <B>release</B> subcommand, was first announced in 2019 and officially released in beta in early 2020. The <B>gh release</B> functionality was a core component of its initial feature set, recognizing the growing need for programmatic release management within development workflows and CI/CD pipelines. It aimed to provide a user-friendly and consistent interface for interacting with GitHub's powerful API directly from the terminal, abstracting away the complexities of HTTP requests and JSON parsing. Its ongoing development focuses on enhancing ease of use, adding more granular control over release properties, and supporting comprehensive asset management, making it an indispensable tool for automated software delivery on GitHub.


title: SYNOPSIS
content:
<b>gh repo</b> <I>command</I> [<I>flags</I>]<br><br>Common <I>commands</I> include:<br>  <b>archive</b> &lt;<i>repository</i>&gt;<br>  <b>clone</b> &lt;<i>repository</i>&gt; [<I>directory</I>]<br>  <b>create</b> [<I>name</I>]<br>  <b>delete</b> &lt;<i>repository</i>&gt;<br>  <b>fork</b> [<I>repository</I>]<br>  <b>list</b><br>  <b>rename</b> &lt;<i>repository</i>&gt; &lt;<i>new-name</i>&gt;<br>  <b>sync</b> [<I>repository</I>]<br>  <b>view</b> [<I>repository</I>]


title: PARAMETERS
content:
<b><b>archive</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Archives a GitHub repository, making it read-only and preventing further commits.<br><br><b><b>clone</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Clones a GitHub repository to your local machine, creating a local Git repository.<br><br><b><b>create</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Creates a new GitHub repository, with options for visibility (public/private), description, and more.<br><br><b><b>delete</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Deletes a GitHub repository. This action is irreversible and requires explicit confirmation.<br><br><b><b>fork</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Forks a GitHub repository, creating a personal copy under your user or organization account.<br><br><b><b>list</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Lists repositories owned by or accessible to the authenticated GitHub user, with filtering options.<br><br><b><b>rename</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Renames an existing GitHub repository to a new specified name.<br><br><b><b>sync</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Synchronizes a forked GitHub repository with its upstream counterpart, updating local and remote branches.<br><br><b><b>view</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Views details of a GitHub repository, either by opening it in a web browser or printing its metadata.<br><br><b><b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays help information for the <b>gh repo</b> command or a specific subcommand.<br><br><b><b>--hostname</b> <I>host</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the GitHub host to interact with (e.g., github.com or a GitHub Enterprise instance).<br><br><b><b>--repo</b> <I>owner/repo</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the target repository for commands that operate on a specific repository but don't take it as a positional argument.<br><br>


title: DESCRIPTION
content:
The <b>gh repo</b> command is a powerful subcommand of the GitHub CLI (<b>gh</b>) that allows users to perform various repository management tasks directly from their terminal. It streamlines workflows by providing functions to <i>create</i>, <i>clone</i>, <i>list</i>, <i>view</i>, <i>delete</i>, <i>archive</i>, <i>fork</i>, <i>rename</i>, and <i>synchronize</i> GitHub repositories without needing to visit the web interface. This significantly enhances productivity for developers working with GitHub. Each specific action is handled by a subcommand, such as <b>gh repo create</b> or <b>gh repo clone</b>, making common operations quick and efficient and bringing the power of GitHub.com directly to your shell.


title: CAVEATS
content:
The <b>gh repo</b> command relies on the GitHub CLI (<b>gh</b>) being installed and properly authenticated with your GitHub account (via <b>gh auth login</b>). All operations are performed against the GitHub API and are thus subject to network connectivity, API rate limits, and the user's permissions on the target repository. Deleting a repository is a permanent and irreversible action.


title: AUTHENTICATION REQUIREMENT
content:
To use <b>gh repo</b> effectively, you must first authenticate your GitHub CLI session. This is typically done using the <b>gh auth login</b> command, which provides a user-friendly browser-based authentication flow. This step grants <b>gh</b> the necessary API tokens to interact with your GitHub repositories on your behalf.


title: REMOTE OPERATIONS FOCUS
content:
It's important to distinguish that most <b>gh repo</b> operations primarily interact with the <i>remote</i> GitHub repository (e.g., on GitHub.com or your Enterprise instance). While <b>gh repo clone</b> initiates a local Git clone, subsequent commands like <b>gh repo delete</b>, <b>gh repo archive</b>, or <b>gh repo rename</b> modify the repository directly on GitHub's servers, not just your local copy.


title: HISTORY
content:
The <b>gh repo</b> functionalities are core components of the GitHub CLI, which was initially released as a public beta in 2019 and reached its 1.0 milestone in 2020. Developed by GitHub, the CLI was designed to bring the essential features of the GitHub web interface directly to the command line, aiming to enhance developer productivity and streamline workflows. Repository management capabilities, including creating, cloning, and viewing repositories, were fundamental to the CLI's initial design and have been continuously refined since its inception.


title: SYNOPSIS
content:
<b>gh run</b> <I>command</I> [flags]<br><br>Where <I>command</I> is one of:<br>  <b>cancel</b> <I>&lt;run-id&gt;</I> [flags]<br>  <b>download</b> <I>&lt;run-id&gt;</I> [flags]<br>  <b>list</b> [flags]<br>  <b>rerun</b> <I>&lt;run-id&gt;</I> [flags]<br>  <b>view</b> <I>&lt;run-id&gt;</I> [flags]


title: PARAMETERS
content:
<b>cancel <run-id></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Cancels a specified workflow run by its ID.<br><br><b>download <run-id></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Downloads artifacts generated by a specified workflow run.<br><br><b>list</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Lists recent workflow runs, with options to filter by workflow, branch, or status.<br><br><b>rerun <run-id></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Reruns a specified workflow run, or specific jobs within it.<br><br><b>view <run-id></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Views detailed information or logs for a specified workflow run or job.<br><br>


title: DESCRIPTION
content:
The <b>gh run</b> command is a powerful subcommand within the GitHub CLI (<b>gh</b>), a command-line interface provided by GitHub. It is designed to streamline the management and interaction with GitHub Actions workflow runs directly from the terminal. This command group provides a convenient way to perform tasks traditionally handled via the GitHub web UI, making it invaluable for developers and CI/CD engineers. Users can leverage <b>gh run</b> to list recent workflow executions, inspect detailed logs of individual runs, download generated artifacts, trigger reruns of failed or successful workflows, and even cancel ongoing runs. Its functionality enhances efficiency by allowing quick monitoring, debugging, and control of automated workflows without leaving the terminal, integrating seamlessly into existing scripting environments for continuous integration and delivery.


title: CAVEATS
content:
The <b>gh run</b> command requires the GitHub CLI (<b>gh</b>) to be installed and authenticated to your GitHub account. It also necessitates an active internet connection to communicate with GitHub. Users must have appropriate repository permissions to perform actions like canceling or rerunning workflow runs. Workflow run IDs, required for many subcommands, typically need to be retrieved first, often using <b>gh run list</b>.


title: COMMON FLAGS AND OPTIONS
content:
Each subcommand under <b>gh run</b> typically supports additional specific flags to refine its behavior. For instance, <b>gh run list</b> accepts filters like <I>--workflow</I>, <I>--branch</I>, or <I>--limit</I>. <b>gh run download</b> uses <I>--dir</I> to specify the download directory, and <b>gh run view</b> can use <I>--log</I> to show run logs. All subcommands also support the <I>--help</I> flag for detailed usage information.


title: USAGE EXAMPLES
content:
List all recent workflow runs: <b>gh run list</b><br>List runs for a specific workflow named 'build' on 'main' branch: <b>gh run list --workflow build --branch main</b><br>View details of run ID 12345, including logs: <b>gh run view 12345 --log</b><br>Download all artifacts from run ID 54321 to a directory named 'build-artifacts': <b>gh run download 54321 --dir build-artifacts</b><br>Rerun run ID 67890: <b>gh run rerun 67890</b>


title: HISTORY
content:
The <b>gh run</b> functionality is an integral part of the GitHub CLI, which was officially launched by GitHub to bring GitHub's features to the terminal. Its development focuses on empowering developers and CI/CD engineers to manage their GitHub Actions workflows efficiently without leaving the command line. Since its introduction, <b>gh run</b> has evolved with new capabilities, reflecting the growing importance of GitHub Actions in modern development workflows and the desire for streamlined command-line interfaces for continuous integration and delivery.


title: PARAMETERS
content:
<b>lock</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Immediately locks the screen, activating the screensaver.<br><br><b>unlock</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Attempts to unlock the screen. <I>Note:</I> This command typically does not work directly from the command line as it requires user interaction (e.g., password entry) via the graphical login prompt.<br><br><b>status</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Checks and reports the current status of the screensaver, indicating whether the screen is locked or unlocked.<br><br><b>activate</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Forces the screensaver to activate, displaying the screensaver content without necessarily locking the screen.<br><br><b>deactivate</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Deactivates the screensaver, returning to the desktop or application without unlocking the screen if it was previously locked.<br><br>


title: DESCRIPTION
content:
<B>gh-screensaver</B> is a lightweight shell script designed to simplify interaction with the <I>Gnome Screensaver</I> from the command line. It acts as a convenient wrapper around the more verbose <I>gnome-screensaver-command</I> utility, providing a straightforward interface for common screensaver operations. Users can quickly lock their screen, check its current status, or activate/deactivate the screensaver, making it particularly useful for scripting, automation, or integrating screensaver control into custom desktop environments or keybinds. Its primary benefit lies in offering a more memorable and streamlined syntax compared to its underlying command. It's often found in personal utility collections or specialized tooling like the <I>geekhack/gh-tools</I> suite.


title: CAVEATS
content:
<B>gh-screensaver</B> is a shell script and relies on the <I>gnome-screensaver-command</I> utility being installed and functional within a Gnome desktop environment. It may not work in other desktop environments (e.g., KDE, XFCE) or if <I>gnome-screensaver</I> is not running. The <I>unlock</I> command typically requires graphical user interaction and a password, making it impractical for direct command-line use without further graphical automation.


title: DEPENDENCIES
content:
<B>gh-screensaver</B> is fundamentally dependent on the presence and functionality of <I>gnome-screensaver-command</I>. It essentially parses its arguments and passes them directly to this underlying utility.


title: SCRIPTING UTILITY
content:
Due to its simple command-line interface, <B>gh-screensaver</B> is ideally suited for integration into custom shell scripts, keyboard shortcuts, or desktop environment automation rules, providing quick and easy screensaver management.


title: HISTORY
content:
Developed as part of the <I>geekhack/gh-tools</I> collection, <B>gh-screensaver</B> emerged as a practical wrapper for the <I>gnome-screensaver-command</I> utility. Its creation aimed to provide a more concise and memorable interface for common screensaver actions, simplifying its use in shell scripts and custom desktop automations. It is not a core Linux utility but rather a specialized convenience script, reflecting a common pattern of creating shell wrappers for frequently used or verbose commands.


title: PARAMETERS
content:
<b><b>&lt;secret-name&gt;</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the name of the secret to manage. This argument is required for the <i>set</i> and <i>delete</i> subcommands.<br><br><b><b>--body</b>, <b>-b</b> <i>&lt;string&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The value of the secret to be set. If this option is not provided, the command will read the secret value from standard input (<i>stdin</i>). This flag is used exclusively with the <i>set</i> subcommand.<br><br><b><b>--env</b>, <b>-e</b> <i>&lt;name&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Scopes the secret to a specific environment within a repository. This option is used to manage environment-specific secrets and is applicable to the <i>set</i>, <i>delete</i>, and <i>list</i> subcommands.<br><br><b><b>--org</b>, <b>-o</b> <i>&lt;name&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Scopes the secret to an entire organization. Use this option to manage organization-wide secrets. Applicable to the <i>set</i>, <i>delete</i>, and <i>list</i> subcommands.<br><br><b><b>--repos</b>, <b>-r</b> <i>&lt;list&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;A comma-separated list of repository names that an organization secret should be accessible to. This option is used exclusively with organization secrets and the <i>set</i> subcommand.<br><br><b><b>--visibility</b>, <b>-v</b> <i>&lt;string&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the visibility of an organization secret. Accepted values are <i>all</i> (accessible to all repositories in the organization), <i>private</i> (accessible only to private repositories), or <i>selected</i> (accessible to specific repositories defined by <b>--repos</b>). Defaults to <i>private</i> if not specified. Used with the <i>set</i> subcommand for organization secrets.<br><br><b><b>--add-for-repositories</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Used with the <i>set</i> subcommand for organization secrets. This flag adds the repositories specified by <b>--repos</b> to an existing organization secret's access list, rather than replacing the list entirely.<br><br><b><b>--remove-from-repositories</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Used with the <i>set</i> subcommand for organization secrets. This flag removes the repositories specified by <b>--repos</b> from an existing organization secret's access list.<br><br><b><b>--app</b> <i>&lt;string&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the target application for the secret. Accepted values are <i>actions</i> (for GitHub Actions workflows) or <i>codespaces</i> (for GitHub Codespaces). Defaults to <i>actions</i> if not specified. Applicable to the <i>set</i>, <i>delete</i>, and <i>list</i> subcommands.<br><br>


title: DESCRIPTION
content:
The <b>gh secret</b> command is an essential component of the GitHub CLI (<b>gh</b>) tool, designed for secure and programmatic management of sensitive information within GitHub repositories, organizations, and environments. It empowers users to set, retrieve a list of, and delete secrets primarily utilized by GitHub Actions workflows or Codespaces. This command significantly streamlines the integration of confidential data, such as API tokens, private keys, or credentials, into CI/CD pipelines without directly exposing them in code. It supports various scopes for secrets, including specific repositories, organization-wide, or even environment-specific secrets, thereby ensuring fine-grained access control and adherence to robust security best practices.


title: CAVEATS
content:
The <b>gh secret</b> command requires the GitHub CLI (<b>gh</b>) to be installed and authenticated to your GitHub account.<br>Secrets are securely stored by GitHub and, once set, their values cannot be directly retrieved (read back) using this command; only their names can be listed or the secrets deleted.<br>Users must possess appropriate permissions (e.g., admin or write access to a repository, or organization owner/admin roles) to manage secrets effectively within GitHub.


title: SECURITY BEST PRACTICES
content:
When setting secrets, it is strongly advised to avoid hardcoding sensitive values directly in shell scripts. Instead, use secure input methods such as piping data from <i>stdin</i> (e.g., <i>echo "$MY_SECRET_VALUE" | gh secret set MY_SECRET</i>) or leveraging environment variables to pass values to the <b>--body</b> option securely.


title: UNDERSTANDING SECRET SCOPES
content:
Familiarize yourself with the different scopes available for secrets: <i>repository</i> (default, for the current repo), <i>environment</i> (for specific environments within a repo), and <i>organization</i> (for secrets accessible across an organization). Choosing the correct scope is crucial for applying the appropriate level of access control and isolation for your sensitive data within your GitHub ecosystem.


title: APPLICATION TARGETING
content:
Secrets managed by <b>gh secret</b> can be explicitly targeted for use by either GitHub Actions workflows or GitHub Codespaces. This distinction allows for the creation and management of separate sets of credentials tailored to the specific requirements and security contexts of each application, enhancing granular control over sensitive data.


title: HISTORY
content:
The <b>gh secret</b> command is an integral part of the GitHub CLI, which saw its initial beta release in 2019 and achieved general availability in September 2020. With the escalating adoption of GitHub Actions and Codespaces, the capability for programmatic management of sensitive credentials became critically important for robust CI/CD pipelines. The <b>gh secret</b> command was specifically developed to meet this demand, providing a straightforward command-line interface for securely interacting with GitHub's comprehensive secrets management system. Its evolution has consistently prioritized user-friendliness and adherence to stringent security practices for handling confidential data, integrating secret operations directly into modern developer workflows and automation scripts.


title: SYNOPSIS
content:
<b>gh secret set <I>SECRET_NAME</I> [flags]</b><br><br>Sets a repository secret (default scope):<br><b>gh secret set <I>MY_REPO_SECRET</I></b><br><br>Sets an environment secret:<br><b>gh secret set <I>MY_ENV_SECRET</I> --env <I>production</I></b><br><br>Sets an organization secret:<br><b>gh secret set <I>MY_ORG_SECRET</I> --org <I>my-organization</I></b><br><br>Reads secret value from a file:<br><b>gh secret set <I>MY_FILE_SECRET</I> --body <I>path/to/secret.txt</I></b>


title: PARAMETERS
content:
<b><I>SECRET_NAME</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The name of the secret to create or update. This name must be unique within its scope (repository, environment, or organization).<br><br><b><code>-R, --repo <I>[HOST/]OWNER/REPO</I></code></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Select a different repository to operate on. Defaults to the current repository if not specified.<br><br><b><code>--body <I>file</I></code></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Read the secret value from the specified file path instead of standard input (stdin). Useful for non-interactive scripts.<br><br><b><code>--env <I>environment-name</I></code></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set the secret for a specific deployment environment within the repository. Requires the environment to exist in GitHub.<br><br><b><code>--org <I>organization-name</I></code></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set the secret at the organization level. This secret can then be made available to multiple repositories within the organization.<br><br><b><code>--add-for-repositories <I>repository-list</I></code></b><br>&nbsp;&nbsp;&nbsp;&nbsp;For organization secrets, a comma-separated list of repository names (e.g., <code>owner/repo1,owner/repo2</code>) that should have access to the secret. Requires <code>--visibility selected</code>.<br><br><b><code>--visibility {all|private|selected}</code></b><br>&nbsp;&nbsp;&nbsp;&nbsp;For organization secrets, defines the access level for repositories. <code>all</code> (all repos), <code>private</code> (internal and private repos), or <code>selected</code> (specific repos using <code>--add-for-repositories</code>).<br><br>


title: DESCRIPTION
content:
<code>gh secret set</code> is a command-line tool within the GitHub CLI (<code>gh</code>) designed to manage sensitive data for GitHub Actions workflows. It allows users to securely create or update secrets, which are crucial for storing credentials, API keys, and other non-public information required by CI/CD pipelines. This command supports setting secrets at various scopes: <br><br><I><b>Repository Level:</b></I> Secrets are accessible only to workflows within a specific GitHub repository.<br><I><b>Environment Level:</b></I> Secrets are tied to a specific deployment environment (e.g., <I>production</I>, <I>staging</I>) within a repository, often protected by approval rules.<br><I><b>Organization Level:</b></I> Secrets can be shared across multiple repositories belonging to the same GitHub organization, with granular control over which repositories have access. <br><br>The secret value is typically read from standard input (prompting the user) or from a specified file using the <code>--body</code> flag. <code>gh secret set</code> ensures that secrets are encrypted on the client side before being transmitted to GitHub, enhancing security by preventing the raw secret from being exposed. This command is an essential tool for automating the secure injection of sensitive configuration into GitHub Actions.


title: CAVEATS
content:
Secrets set via <code>gh secret set</code> are encrypted and cannot be retrieved (read) back using the GitHub CLI or API. You must have appropriate write permissions (e.g., admin or maintainer role for repository/environment, or owner for organization) to set secrets. Default input for the secret value is stdin, making it interactive; for scripting, pipe the value or use the <code>--body</code> flag to avoid manual input or shell history issues.


title: READING SECRET VALUE
content:
By default, <code>gh secret set</code> prompts interactively for the secret value from standard input. For non-interactive use in scripts, you can pipe the secret value to the command (e.g., <code>echo "my_secret_value" | gh secret set MY_SECRET_NAME</code>) or use the <code>--body</code> flag to read the secret from a file (e.g., <code>gh secret set MY_SECRET_NAME --body secret.txt</code>).


title: CLIENT-SIDE ENCRYPTION
content:
For enhanced security, <code>gh secret set</code> encrypts the secret value on the client side (your machine) before it is sent to GitHub. This ensures that the raw, unencrypted secret never traverses the network, minimizing exposure risk.


title: HISTORY
content:
The <code>gh</code> CLI, developed by GitHub, provides a unified command-line interface for interacting with GitHub. The <code>gh secret</code> family of commands was introduced to empower developers and CI/CD pipelines to manage GitHub Actions secrets directly from the terminal. This capability streamlines automation workflows, allowing for programmatic setup and rotation of sensitive credentials without needing to interact with the web UI. Its development paralleled the growing adoption and features of GitHub Actions, ensuring a robust CLI experience for managing workflow dependencies.


title: SYNOPSIS
content:
<b>gh skyline</b> [<br><b>--user</b> <i>&lt;username&gt;</i><br>] [<br><b>--year</b> <i>&lt;year&gt;</i><br>] [<br><b>--theme</b> <i>&lt;theme&gt;</i><br>] [<br><b>--output</b> <i>&lt;file.gif&gt;</i><br>] [<br><b>--verbose</b><br>] [<br><b>--version</b><br>] [<br><b>--help</b><br>]


title: PARAMETERS
content:
<b>--user <username></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the GitHub username whose contributions will be visualized. Defaults to the authenticated user.<br><br><b>--year <year></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Define the calendar year for which contributions should be displayed. Defaults to the current year.<br><br><b>--theme <theme></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set the color scheme for the 3D graph. Examples include <i>light</i>, <i>dark</i>, <i>halloween</i>, <i>desert</i>, <i>ocean</i>, <i>arctic</i>, and <i>dracula</i>.<br><br><b>--output <file.gif></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Export the generated 3D animation as an animated GIF file. Requires <i>ffmpeg</i> to be installed.<br><br><b>--verbose</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enable verbose output, showing more detailed information during execution.<br><br><b>--version</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display the version information for the <i>gh-skyline</i> extension.<br><br><b>--help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show the help message and available options for the command.<br><br>


title: DESCRIPTION
content:
The <i>gh-skyline</i> command is a <br>GitHub CLI extension designed to transform a user's GitHub contribution history into an interactive 3D "skyline" visualization. <br>It fetches contribution data for a specified user and year, then renders it directly in your terminal as a dynamic 3D graph. <br>This visualization mimics the aesthetic of GitHub's own contribution skyline feature, offering a unique perspective on activity levels. <br>Users can specify a target username, a particular year, and choose from various color themes to customize the appearance of the graph. <br>Additionally, it supports exporting the animated 3D view into a GIF file, making it easy to share your contribution insights.


title: CAVEATS
content:
<b>gh-skyline</b> is a GitHub CLI extension and requires the <br>GitHub CLI (gh)<br> to be installed and authenticated on your system.<br>Exporting the visualization to a GIF file using the <br>--output<br> option depends on the <br>ffmpeg<br> utility being installed and accessible via your system's PATH.<br>The quality and appearance of the 3D graph rendered directly in the terminal can vary based on your terminal emulator's capabilities and font support.


title: INSTALLATION
content:
To install the <i>gh-skyline</i> extension, use the following command:<br><i>gh extension install mskian/gh-skyline</i><br>Ensure you have <br>GitHub CLI<br> installed and configured before attempting installation.


title: INTERACTIVE VIEW
content:
When run without the <br>--output<br> option, <br>gh-skyline<br> renders an interactive 3D visualization directly in your terminal. <br>You can typically rotate and zoom the view using keyboard controls (e.g., arrow keys, 'w'/'s' for zoom), providing a dynamic exploration of your contribution history.


title: HISTORY
content:
The <br>gh-skyline<br> command emerged as part of the growing ecosystem of <br>GitHub CLI extensions<br>. <br>GitHub CLI<br> was introduced to bring GitHub functionality directly to the terminal, and its extension framework allows the community to build and share custom commands. <br>gh-skyline<br> leverages this framework to provide a novel and engaging way to visualize contribution data, a feature inspired by the 3D skyline graphs sometimes shown on GitHub's own website during special events or user achievements. <br>Its development reflects a desire to make personal contribution tracking more interactive and visually appealing within the command-line environment.


title: SYNOPSIS
content:
<b>gh ssh-key</b> <i>&lt;subcommand&gt;</i> [<i>&lt;options&gt;</i>]<br><br><b>gh ssh-key add</b> [<i>&lt;key-file&gt;</i> | <b>--public-key</b> <i>&lt;file&gt;</i>] [<b>--title</b> <i>&lt;title&gt;</i>] [<b>--type</b> <i>&lt;type&gt;</i>] [<b>--allow-create-new</b>]<br><b>gh ssh-key list</b><br><b>gh ssh-key delete</b> <i>&lt;key-id&gt;</i>


title: PARAMETERS
content:
<b>add</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Subcommand to add a new SSH public key to your GitHub account.<br><br><b>list</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Subcommand to list all SSH public keys associated with your GitHub account.<br><br><b>delete</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Subcommand to delete an existing SSH public key from your GitHub account.<br><br><b><i>&lt;key-file&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;(For <i>add</i>) The path to the SSH public key file to be added. Defaults to <i>~/.ssh/id_rsa.pub</i> if not specified.<br><br><b><b>--public-key</b> <i>&lt;file&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;(For <i>add</i>) Specifies the path to the SSH public key file. An alternative to providing <i>&lt;key-file&gt;</i> as a positional argument.<br><br><b><b>--title</b> <i>&lt;title&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;(For <i>add</i>) A descriptive title for the new SSH key. If omitted, a title is generated automatically.<br><br><b><b>--type</b> <i>&lt;type&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;(For <i>add</i>) Specifies the type of key to add, e.g., "authentication" or "signing". Defaults to "authentication".<br><br><b><b>--allow-create-new</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;(For <i>add</i>) If the specified key file does not exist, this flag allows <i>gh</i> to prompt to create a new SSH key.<br><br><b><i>&lt;key-id&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;(For <i>delete</i>) The unique ID of the SSH key to be deleted. This ID can be obtained using the <i>list</i> subcommand.<br><br>


title: DESCRIPTION
content:
The <b>gh ssh-key</b> command is a powerful subcommand within the GitHub CLI (<i>gh</i>), designed to streamline the management of SSH public keys associated with your GitHub account. It provides a convenient way to perform key operations directly from the terminal, eliminating the need to navigate the GitHub web interface for these tasks.<br><br>Users can easily add new SSH public keys, specify a descriptive title for identification, or even choose the key's intended use (e.g., authentication). Additionally, the command allows for listing all registered SSH keys on your account, displaying their unique IDs, titles, and fingerprints. When a key is no longer needed or compromised, <b>gh ssh-key</b> facilitates its secure deletion by referencing its unique ID. This integration simplifies developer workflows, especially for those who heavily rely on SSH for Git operations and want to manage their authentication credentials efficiently.


title: CAVEATS
content:
<b>Key Considerations:</b><br><i>•</i> Requires the GitHub CLI (<i>gh</i>) to be installed and properly authenticated with your GitHub account.<br><i>•</i> The command only manages <i>public</i> SSH keys on GitHub; private keys remain on your local system.<br><i>•</i> Deletion of keys on GitHub is irreversible.<br><i>•</i> Ensure the specified SSH key file exists and is readable.


title: COMMON USAGE WORKFLOW
content:
A typical workflow involves first generating an SSH key pair using <b>ssh-keygen</b>, then adding the public key to GitHub using <b>gh ssh-key add</b>. To verify, use <b>gh ssh-key list</b>. If a key is no longer needed, <b>gh ssh-key delete</b> can remove it. This command streamlines secure authentication setup for Git operations over SSH.


title: HISTORY
content:
The <i>gh</i> (GitHub CLI) project was launched in 2020 by GitHub to bring GitHub features to the terminal. The <b>ssh-key</b> subcommand is an integral part of this effort, simplifying common developer tasks related to SSH key management directly from the command line, aligning with the CLI's goal of enhancing productivity and reducing context switching for GitHub users.


title: SYNOPSIS
content:
<b>gh workflow</b> <<i>subcommand</i>> [<i>flags</i>]<br>For example: <b>gh workflow list</b><br>For subcommand-specific help: <b>gh workflow</b> <<i>subcommand</i>> <b>--help</b>


title: PARAMETERS
content:
<b><b>--repo</b> <<i>[HOST/]OWNER/REPO</i>></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Selects a GitHub repository to operate on. If not specified, the repository of the current directory is used.</i><br><br><b><b>--web</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Opens the workflow or list of workflows in a web browser. Applicable to <b>list</b> and <b>view</b> subcommands.</i><br><br><b><b>--limit</b> <<i>integer</i>></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Limits the number of workflow runs or workflows displayed. Applicable to the <b>list</b> subcommand.</i><br><br><b><b>--all</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Lists all workflows, including disabled ones. Applicable to the <b>list</b> subcommand.</i><br><br><b><b>--ref</b> <<i>branch</i>></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>The Git reference (branch, tag, or SHA) on which to dispatch a workflow run. Applicable to the <b>run</b> subcommand.</i><br><br><b><b>--field</b> <<i>key=value</i>></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Passes an input parameter as a string or JSON for a workflow dispatch. Use multiple times for multiple inputs. Applicable to the <b>run</b> subcommand.</i><br><br><b><b>--raw-field</b> <<i>key=value</i>></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Passes an input parameter directly, without JSON encoding. Applicable to the <b>run</b> subcommand.</i><br><br><b><b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Displays help information for the <b>gh workflow</b> command or a specific subcommand.</i><br><br>


title: DESCRIPTION
content:
<i>The <b>gh workflow</b> command is a powerful subcommand of the GitHub CLI, designed to interact with and manage GitHub Actions workflows directly from your terminal. It allows users to perform various operations such as listing all workflows in a repository, viewing detailed information about a specific workflow, enabling or disabling workflows, and even manually triggering a workflow run. This utility is invaluable for developers and CI/CD engineers who need to automate or troubleshoot their GitHub Actions pipelines without leaving the command line interface. It streamlines common development tasks, enhancing productivity and enabling scriptable interactions with GitHub's robust automation features.</i>


title: CAVEATS
content:
<i>Requires the GitHub CLI (<b>gh</b>) to be installed and authenticated. Appropriate GitHub repository permissions are necessary to perform workflow actions like enabling, disabling, or dispatching runs. Network connectivity to GitHub is essential for all operations.</i>


title: <B>SUBCOMMANDS</B>
content:
<i>The <b>gh workflow</b> command groups several subcommands to manage workflows:<br><b>list</b>: Lists workflows in the current or specified repository.<br><b>view</b>: Displays details of a specific workflow.<br><b>run</b>: Manually dispatches a workflow run with optional inputs and a reference.<br><b>enable</b>: Enables a disabled workflow.<br><b>disable</b>: Disables an active workflow.</i>


title: <B>AUTHENTICATION</B>
content:
<i>The <b>gh workflow</b> command inherits its authentication from the main <b>gh</b> CLI. Users typically authenticate using <b>gh auth login</b>, which securely stores credentials to interact with GitHub APIs.</i>


title: HISTORY
content:
<i>The <b>gh</b> CLI, which includes the <b>workflow</b> subcommand, was developed by GitHub to provide a native command-line interface for interacting with GitHub services. It moved to general availability in September 2020. The <b>workflow</b> capabilities were integrated as GitHub Actions became a core part of the GitHub platform for CI/CD automation, offering users a consistent CLI experience for managing their automated workflows.</i>


title: SYNOPSIS
content:
<b>ghc</b> [<i>OPTIONS</i>] <i>FILES...</i><br><b>ghc --make</b> [<i>OPTIONS</i>] [<i>MODULES...</i>]<br><b>ghc -e</b> <i>EXPRESSION</i><br><b>ghc --help</b><br><b>ghc --version</b>


title: PARAMETERS
content:
<b><b>-o</b> <i>OUTPUT</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the output file name for the compiled executable or library.<br><br><b><b>--make</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Compile multiple modules and link them into a single executable or library, resolving dependencies automatically.<br><br><b><b>-O</b>[<i>LEVEL</i>]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enable optimization. <i>LEVEL</i> can be omitted (defaults to 1), or specified as 0 (no optimizations), 1, or 2 (maximum optimizations).<br><br><b><b>-Wall</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enable all standard warnings, encouraging cleaner and more robust code.<br><br><b><b>-Werror</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Treat all warnings as errors, causing compilation to fail if any warnings are present.<br><br><b><b>-i</b><i>DIR[:DIR...]</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Add directories to the search path for finding Haskell modules and interface files.<br><br><b><b>-e</b> <i>EXPRESSION</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Evaluate a Haskell expression directly on the command line and print the result, similar to GHCi's interactive evaluation.<br><br><b><b>--version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display the compiler's version information and copyright details.<br><br><b><b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show a summary of command-line options.<br><br><b><b>-v</b>[<i>LEVEL</i>]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set the verbosity level of the compiler output. Higher levels provide more detailed information about the compilation process.<br><br><b><b>-main-is</b> <i>MODULE.FUNCTION</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the main entry point for the program when linking, useful for projects with multiple possible entry points.<br><br>


title: DESCRIPTION
content:
<b>GHC</b>, the Glasgow Haskell Compiler, is the most widely used and feature-rich compiler for the Haskell programming language. It can compile Haskell source code into native machine code executables, shared libraries, or static libraries. Beyond compilation, GHC also provides GHCi, an interactive interpreter for Haskell, which is invaluable for rapid prototyping and debugging. It supports the latest Haskell language standards (like Haskell 2010 and GHC2021) and various extensions.<br><br>GHC is known for its advanced optimization capabilities, generating highly efficient code, and its strong type system which catches many errors at compile time. It plays a central role in the Haskell ecosystem, being the foundation for most Haskell development tools and libraries.


title: CAVEATS
content:
<I>GHC can be memory-intensive</I> during compilation, especially for large projects or when aggressive optimizations are enabled. <br><br>The build process for complex Haskell projects often relies on external tools like <I>Cabal</I> or <I>Stack</I> to manage dependencies and orchestrate builds, rather than `ghc` directly, which can add a layer of complexity for newcomers. <br><br>While highly optimized, the generated binaries might have a larger footprint compared to C programs due to the Haskell runtime system and linked libraries.


title: INTERACTIVE MODE (GHCI)
content:
GHC includes an interactive interpreter, GHCi, accessible by running `ghc` without arguments or specifically `ghci`. This mode allows users to load modules, evaluate expressions, test functions, and debug code incrementally, making it an indispensable tool for rapid development and learning.


title: LANGUAGE EXTENSIONS
content:
GHC supports a vast array of language extensions beyond the standard Haskell 2010. These extensions, often enabled via pragmas in source files or command-line flags (e.g., `<b>-X</b><i>ExtensionName</i>`), allow developers to use cutting-edge features, optimize code, or experiment with new programming paradigms.


title: COMPILATION TARGETS
content:
Beyond native executables, GHC can also compile Haskell code to other targets, including shared libraries (`<b>-shared</b>`), static libraries (`<b>-staticlib</b>`), and bytecode (for GHCi). It also supports cross-compilation, allowing developers to build binaries for different architectures or operating systems.


title: HISTORY
content:
The Glasgow Haskell Compiler (GHC) originated in the early 1990s at the University of Glasgow. It quickly became the reference implementation for the Haskell 98 standard and has since evolved into the dominant compiler for the Haskell programming language. Its development has been driven by a global community, continuously incorporating new language features, performance optimizations, and platform support. GHC's steady evolution has been crucial in establishing Haskell as a viable language for industrial-strength applications and research, maintaining its position at the forefront of functional programming language implementation.


title: SYNOPSIS
content:
ghci <i>[OPTIONS...]</i> <i>[FILES...]</i><br><br><i>Note: Many options accepted by ghc (the compiler) are also recognized by ghci.</i>


title: PARAMETERS
content:
<b><b>--version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display the GHC/GHCi version information and exit.<br><br><b><b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display a summary of common command-line options and exit.<br><br><b><b>-v[N]</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Verbose output. Controls the verbosity level, showing more about what GHCi is doing internally.<br><br><b><b>-i<i>dir</i></b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Add <i>dir</i> to the list of directories searched for Haskell source files, interface files, and libraries. Multiple <b>-i</b> options can be used.<br><br><b><b>-package <i>pkg</i></b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Make the specified <i>pkg</i> (e.g., <i>containers</i>, <i>text</i>) available during the session. This is an alternative to specifying packages in a <i>.cabal</i> or <i>stack.yaml</i> file.<br><br><b><b>-X<i>extension</i></b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enable a Haskell language <i>extension</i> (e.g., <i>OverloadedStrings</i>, <i>DataKinds</i>). Multiple <b>-X</b> flags can be specified.<br><br><b><b>-Wall</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enable all standard warnings.<br><br><b><b>-Werror</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Treat all warnings as errors.<br><br><b><i>FILES...</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;One or more Haskell source files (<i>.hs</i>, <i>.lhs</i>) to load into the interactive session upon startup. These files will be compiled and their definitions will be available.<br><br>


title: DESCRIPTION
content:
<i>ghci</i> is the <i>GHC interactive environment</i>, a powerful Read-Eval-Print Loop (REPL) for the Haskell programming language. It is part of the <i>Glasgow Haskell Compiler (GHC)</i> suite. <i>ghci</i> allows developers to interactively evaluate Haskell expressions, experiment with code, load and reload source files, and debug programs without the need for explicit compilation steps.<br><br>It's an indispensable tool for rapid prototyping, understanding language features, and testing small code snippets. You can define functions, evaluate expressions, inspect types, and trace execution. When you load a Haskell source file, <i>ghci</i> compiles it in memory and makes its definitions available for interactive use. This immediate feedback loop significantly accelerates the development process, making <i>ghci</i> a cornerstone of most Haskell workflows, alongside the compiler itself and build tools like <i>Cabal</i> or <i>Stack</i>.


title: CAVEATS
content:
<b>Performance:</b> Code executed in <i>ghci</i> is often interpreted or compiled with less aggressive optimizations than fully compiled executables. This can lead to slower execution times for computationally intensive tasks.<br><br><b>Module Reloading:</b> While <i>ghci</i> supports reloading modules (<b>:r</b>), changes to dependencies or complex module hierarchies can sometimes lead to unexpected behavior or require a full restart of the session.<br><br><b>Interactive Commands:</b> <i>ghci</i>'s power lies significantly in its internal commands (e.g., <b>:load</b>, <b>:type</b>, <b>:set</b>). Users should be aware of the distinction between command-line options (passed on startup) and these interactive commands (typed within the REPL).


title: INTERACTIVE COMMANDS
content:
<i>ghci</i> provides a rich set of interactive commands (prefixed with <b>:</b>) to manage the session:<br><b>:load</b> <i>files</i>... (or <b>:l</b>): Load (and reload) specified Haskell source files.<br><b>:reload</b> (or <b>:r</b>): Reload the currently loaded modules, useful after making changes to source files.<br><b>:type</b> <i>expression</i> (or <b>:t</b>): Show the type of an <i>expression</i>.<br><b>:info</b> <i>name</i> (or <b>:i</b>): Show information about a declared <i>name</i> (e.g., type, definition, modules).<br><b>:set</b> <i>option</i> (or <b>:s</b>): Set options for the current session (e.g., <b>+s</b> for timing, <b>-XExtension</b> for language extensions).<br><b>:show</b> <i>context</i>: Show various session settings (e.g., <b>:show packages</b>, <b>:show languages</b>).<br><b>:quit</b> (or <b>:q</b>): Exit the <i>ghci</i> session.<br><b>:cd</b> <i>dir</i>: Change the current working directory.<br><b>:!</b> <i>command</i>: Execute a shell <i>command</i>.


title: CONFIGURATION FILES
content:
<i>ghci</i> can be configured using files named <i>.ghci</i>. When <i>ghci</i> starts, it looks for and executes commands from <i>~/.ghci</i> (global) and <i>./.ghci</i> (local to the current directory). This allows for custom startup settings, function definitions, or common imports.


title: HISTORY
content:
<i>ghci</i> has been an integral part of the <i>Glasgow Haskell Compiler (GHC)</i> since its early versions. Its development has closely tracked GHC's evolution, benefiting from new compiler features and performance improvements. Initially a simpler interactive environment, it has grown into a sophisticated REPL with advanced debugging, profiling, and introspection capabilities, becoming the de facto standard interactive tool for Haskell development. Its deep integration with GHC ensures that language features and optimizations are immediately available for interactive experimentation.


title: PARAMETERS
content:
<b>-c <command></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the command to run GHCi (e.g., `ghci`, `cabal repl`, `stack ghci`). Defaults to an intelligent guess based on project type.<br><br><b>--test <command></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Runs this command upon successful compilation. Commonly used for continuous testing (e.g., `MyModule.runTests`).<br><br><b>-r, --reload</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Runs the test command on every reload, not just on successful compilation (e.g., to run tests on warnings).<br><br><b>--no-test</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prevents the test command from running automatically.<br><br><b>-T <seconds></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Throttles the output to only show updates every N seconds, reducing flickering.<br><br><b>-W, --warnings</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows compilation warnings (this is the default behavior).<br><br><b>-w, --no-warnings</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Hides compilation warnings.<br><br><b>-O, --output <file></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Redirects all output to the specified file instead of stdout.<br><br><b>--lint <command></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Runs a linter command (e.g., `hlint`) after successful compilation.<br><br><b>--no-lint</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Disables running a linter.<br><br><b>--top <lines></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows only the first N lines of output from GHCi. Useful for concise error summaries.<br><br><b>--height <lines></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows a total of N lines of output, trimming if necessary, to control terminal height.<br><br><b>--errors <mode></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Controls how errors are displayed. Common modes include `brief` or `full`.<br><br><b>--ignore <pattern></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Ignores files or directories matching the given glob pattern from being watched.<br><br><b>--ignore-dir <pattern></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifically ignores directories matching the pattern.<br><br><b>--dir <directory></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Changes the working directory before running GHCi. Useful when <b>ghcid</b> is run from a different location.<br><br><b>--debounce <milliseconds></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Waits for a period of inactivity after file changes before reloading, preventing rapid reloads during multi-file saves.<br><br><b>--restart</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Restarts GHCi completely on every file change. Slower, but can resolve persistent issues for complex changes.<br><br><b>--shutdown <command></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Runs a specified command when GHCi exits, useful for cleanup.<br><br><b>--ghci-options <options></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Passes additional options directly to the underlying GHCi process.<br><br><b>--project <file></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies a custom project configuration file (default is `.ghcid`).<br><br>


title: DESCRIPTION
content:
The <b>ghcid</b> command is a popular tool for Haskell developers that provides instant feedback on compilation errors and warnings. It operates by continuously running <i>GHCi</i> (or `cabal repl`, `stack ghci`) in the background, watching for changes in your project files. As soon as a file is saved, <b>ghcid</b> reloads the project in GHCi and displays any resulting errors or warnings directly in your terminal. This significantly shortens the development cycle by eliminating the need for manual compilation and allowing developers to catch issues immediately. Beyond just compilation, it can also be configured to run tests or other commands upon successful compilation, making it an invaluable tool for continuous testing and an efficient, lightweight alternative to full-fledged IDEs for Haskell development.


title: CAVEATS
content:
As <b>ghcid</b> relies on <i>GHCi</i> for its core functionality, its performance is highly dependent on GHCi's startup and reload times, which can be significant for very large Haskell projects. Occasionally, it might become confused by major project restructuring, file renames, or dependency changes, requiring a manual restart of the <b>ghcid</b> process. Its output can also be quite verbose without careful use of options like `--height` or `--top` to limit the displayed lines.


title: CONFIGURATION FILE
content:
<b>ghcid</b> can be configured using a `.ghcid` file in the project root directory. This file can contain command-line options, one per line, simplifying invocation and ensuring consistent settings across a project. For example, to always run tests, you could place `--test='cabal test'` in your `.ghcid` file instead of typing it every time.


title: EXIT CODES
content:
<b>ghcid</b> exits with code `0` on success (meaning no compilation errors or test failures if `--test` is used) and `1` if there are compilation errors or the `--test` command fails.


title: HISTORY
content:
Developed by Neil Mitchell (ndmitchell), <b>ghcid</b> emerged as a lightweight and efficient solution for providing rapid feedback in Haskell development workflows. It gained significant popularity due to its simplicity, speed, and effectiveness in shortening the edit-compile-test cycle, offering an `npm watch`-like experience tailored for Haskell projects.


title: SYNOPSIS
content:
<B>ghdl</B> <B>MODE</B> [options] <I>FILE...</I><BR>
Common usage modes:<BR>
<B>ghdl -a</B> [options] <I>VHDL_FILE...</I><BR>
<B>ghdl -e</B> [options] <I>TOP_LEVEL_ENTITY</I><BR>
<B>ghdl -r</B> [options] <I>TOP_LEVEL_ENTITY</I><BR>
<B>ghdl --clean</B>


title: PARAMETERS
content:
<b><B>-a</B>, <B>--analyze</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Analyzes VHDL source files and compiles them into a working library. This is the crucial first step for any VHDL design in GHDL.<br><br><b><B>-e</B>, <B>--elaborate</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Elaborates a top-level entity or configuration. This step links all analyzed design units and prepares the design for simulation by resolving generics and port maps.<br><br><b><B>-r</B>, <B>--run</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Runs the elaborated design. This executes the simulation, producing any specified outputs or waveforms and reporting simulation results.<br><br><b><B>--synth</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Performs synthesis analysis. GHDL checks the VHDL code for synthesizable constructs, which is vital for designs intended for FPGA or ASIC implementation.<br><br><b><B>-m</B>, <B>--make</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Combines analysis and elaboration steps. It automatically analyzes dependencies and elaborates the specified top-level unit, simplifying the workflow.<br><br><b><B>--clean</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Removes all generated GHDL files (e.g., compiled units, executables, waveforms) from the current working directory or specified library.<br><br><b><B>-P</B>, <B>--workdir</B>=<I>DIR</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the working directory for libraries. This option allows users to organize compiled VHDL units in a structured manner for complex projects.<br><br><b><B>--std</B>=<I>VHDL_STANDARD</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Selects the VHDL standard to use for compilation (e.g., <I>87</I>, <I>93</I>, <I>02</I>, <I>08</I>). Ensures compatibility with different VHDL language versions.<br><br><b><B>--wave</B>=<I>FORMAT</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables waveform dumping during simulation. Common formats are <I>fst</I> or <I>vcd</I> for viewing with external tools like GTKWave, aiding in debugging.<br><br>


title: DESCRIPTION
content:
GHDL (GNAT Hybrid Design Language) is a free and open-source VHDL simulator that compiles VHDL source files directly into native machine code. This approach significantly enhances simulation performance compared to interpreted simulators. GHDL supports various VHDL standards, including VHDL-87, VHDL-93, V2002, and VHDL-2008. It serves as a crucial tool in the electronic design automation (EDA) ecosystem, allowing engineers to analyze, elaborate, and simulate digital circuits described in VHDL, making it suitable for both functional verification and synthesis analysis. Its integration capabilities make it a popular choice for continuous integration (CI) workflows in hardware development.


title: CAVEATS
content:
While GHDL provides excellent VHDL language support, it may not fully support all vendor-specific VHDL extensions or advanced features found in commercial simulators. Its primary focus is on VHDL simulation and not on integrated debugging features, which typically rely on external waveform viewers.<br>Performance can vary significantly depending on the complexity of the VHDL design and the underlying system resources.


title: <B>TYPICAL WORKFLOW</B>
content:
A common GHDL workflow involves three distinct steps: <B>analysis</B> (<I>-a</I>), <B>elaboration</B> (<I>-e</I>), and <B>simulation</B> (<I>-r</I>). First, individual VHDL files are analyzed and compiled into a working library. Next, a top-level entity or configuration is elaborated, linking all the analyzed units and creating an executable. Finally, the elaborated design is simulated to verify its functionality. The <I>--make</I> option can often simplify this by combining analysis and elaboration into a single command.


title: <B>WAVEFORM GENERATION</B>
content:
For debugging and visualizing signal activity during simulation, GHDL can generate waveform dump files. Using the <I>--wave</I> option with a format like <I>fst</I> or <I>vcd</I> creates a file that can be opened and inspected by external waveform viewers such as <I>GTKWave</I>. This allows users to observe the timing and values of internal signals and primary outputs throughout the simulation, which is crucial for verifying design correctness.


title: HISTORY
content:
GHDL was initially developed by Tristan Gingold as an open-source project to provide a free, high-performance VHDL simulator. It distinguished itself by compiling VHDL code to native machine code using the GCC backend, a technique that has significantly contributed to its speed and efficiency. Over the years, GHDL's development has been continuous, expanding its VHDL standard support, improving compatibility, and becoming a staple for open-source digital hardware development and verification.


title: SYNOPSIS
content:
As 'ghost' is not a standard Linux command, a universal synopsis does not exist. <br><br>If it refers to a custom script or alias, its usage would depend entirely on its specific implementation (e.g., <i>ghost [options] [arguments]</i>).


title: PARAMETERS
content:
<b><i>(No standard parameters)</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The command 'ghost' is not a standard Linux utility, therefore it does not have predefined parameters or options. Any parameters or arguments would be specific to a custom script or application named 'ghost' that a user might have created or installed.<br><br>


title: DESCRIPTION
content:
The term 'ghost' is not recognized as a standard, pre-installed command in most Linux distributions. It is commonly associated with proprietary disk imaging software like Symantec Ghost, which operates primarily in Windows environments or through bootable media. In Linux, equivalent disk imaging functionalities are provided by robust open-source tools such as <i>dd</i>, <i>partclone</i>, or <i>clonezilla</i>. If 'ghost' is encountered as a command on a Linux system, it most likely refers to a custom script, an alias, or a component of a very specific, non-standard package installed by the user or administrator. Users often mistakenly search for a direct 'ghost' command expecting disk cloning capabilities similar to its proprietary namesake.


title: CAVEATS
content:
The primary and most significant caveat is that 'ghost' is not a standard Linux command. Attempting to execute 'ghost' will typically result in a 'command not found' error unless a custom script, alias, or non-standard package with that exact name has been specifically installed or created on the system. Users seeking disk imaging, cloning, or system backup functionalities should explore and utilize the robust, native Linux utilities designed for these purposes.


title: COMMON MISCONCEPTIONS
content:
Many users associate the term 'ghost' with comprehensive disk imaging and system backup. While Symantec Ghost is well-known for these capabilities, it's crucial to understand that it is not a Linux command. Linux offers powerful, flexible, and open-source alternatives like <i>dd</i> for raw disk copying, and <i>partclone</i> for efficient partition backups, which are the go-to tools for similar tasks within the Linux environment.


title: ALTERNATIVE TOOLS FOR IMAGING
content:
For comprehensive disk imaging and cloning solutions on Linux, particularly for system backup and restoration, users often turn to bootable environments like <i>Clonezilla</i>. Clonezilla leverages underlying Linux utilities such as <i>partclone</i> and <i>dd</i> to provide a user-friendly interface for creating and restoring disk or partition images. Other direct command-line options include <i>cat</i> for simple file concatenation, and various specialized tools for specific file system backups like <i>rsync</i>.


title: HISTORY
content:
The term 'Ghost' in a computing context most famously refers to Symantec Ghost (originally Norton Ghost), a proprietary software product developed in the 1990s primarily for disk cloning and imaging, widely used in Windows environments and for deploying operating systems. This tool is not native to Linux and does not have a direct, open-source counterpart sharing its name. Its functionality is typically achieved on Linux systems using open-source utilities developed independently, such as <i>dd</i> and <i>partclone</i>, which predate or evolved separately from Symantec Ghost's prominence. There is no historical development of a standard 'ghost' command within the GNU/Linux ecosystem.


title: PARAMETERS
content:
<b><b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a help message detailing command-line options and exits.<br><br><b><b>--version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints the Ghostty version information to standard output and exits.<br><br><b><b>--config</b> <I>PATH</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies an alternative path to the configuration file, overriding the default location (e.g., <I>~/.config/ghostty/config</I>).<br><br>


title: DESCRIPTION
content:
Ghostty is a modern, GPU-accelerated terminal emulator written in Rust, designed for high performance and a rich feature set. It leverages your graphics card to render text, offering significantly faster redraws and a smoother experience compared to traditional CPU-bound terminals. Ghostty natively supports Wayland, providing seamless integration with modern Linux desktop environments, while also offering X11 support via Xwayland. Key features include true color support, font ligatures, powerful scrollback capabilities, and a flexible configuration system based on Lua, allowing users extensive customization of appearance and behavior. It aims to provide a fast, secure, and highly customizable terminal experience for developers and power users alike.


title: CAVEATS
content:
Being a relatively new project, Ghostty's feature set and maturity are continually evolving. Optimal performance relies heavily on proper GPU driver setup and hardware acceleration. While it supports both Wayland and X11, its native Wayland integration is where it shines, potentially offering a more optimized experience on modern Wayland compositors. Users should be aware that extensive customization requires familiarity with its Lua-based configuration system.


title: CONFIGURATION
content:
Ghostty is primarily configured via a Lua-based configuration file, typically located at <I>~/.config/ghostty/config</I>. This powerful and flexible system allows users to customize virtually every aspect of the terminal's appearance and behavior, including keybindings, colors, fonts, and startup commands, offering a level of control beyond simple command-line flags.


title: HISTORY
content:
Ghostty was initiated by Michael Smith in late 2022 / early 2023 with the goal of creating a performant, feature-rich terminal emulator that takes full advantage of modern GPU capabilities. Inspired by other fast terminals like Alacritty and Kitty, it was developed in Rust, emphasizing memory safety and speed. Its design incorporates lessons learned from existing terminal emulators, aiming for a highly customizable experience primarily through its Lua-based configuration, distinguishing itself by offering a unique approach to terminal emulation on Linux.


title: SYNOPSIS
content:
<i>gibo</i> [<b>-l</b> | <b>-s</b> <I>KEYWORD</I> | <b>-u</b> | <b>-v</b> | <b>-h</b>] [<I>TEMPLATE_NAME</I>...]


title: PARAMETERS
content:
<b><b>-l</b>, <b>--list</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Lists all available <br><b>.gitignore</b> templates that <br><i>gibo</i> can generate. This option is exclusive with <br><i>TEMPLATE_NAME</i> arguments.<br><br><b><b>-s</b>, <b>--search</b> <I>KEYWORD</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Searches for <br><b>.gitignore</b> templates whose names contain the specified <br><i>KEYWORD</i>. This helps in discovering relevant templates. <br>Exclusive with <br><i>TEMPLATE_NAME</i> arguments.<br><br><b><b>-u</b>, <b>--update</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Updates the local cache of <br><b>.gitignore</b> templates by fetching the latest versions from the <br><i>github/gitignore</i> repository. Requires an active internet connection. <br>Exclusive with <br><i>TEMPLATE_NAME</i> arguments.<br><br><b><b>-v</b>, <b>--version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints the version number of <br><i>gibo</i>. Exclusive with <br><i>TEMPLATE_NAME</i> arguments.<br><br><b><b>-h</b>, <b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays the help message and available options for <br><i>gibo</i>. Exclusive with <br><i>TEMPLATE_NAME</i> arguments.<br><br><b><I>TEMPLATE_NAME</I>...</b><br>&nbsp;&nbsp;&nbsp;&nbsp;One or more names of <br><b>.gitignore</b> templates to fetch and combine. When provided, <br><i>gibo</i> prints the combined content of these templates to standard output. <br>For example, <i>gibo</i> Python Node macOS.<br><br>


title: DESCRIPTION
content:
<i>gibo</i> is a powerful command-line utility designed to streamline the creation of <br><b>.gitignore</b> files for Git repositories. It efficiently fetches and combines <br><b>.gitignore</b> boilerplates from the official <br><i>github/gitignore</i> repository, eliminating the need for manual copy-pasting or <br>maintaining local template collections. Users can specify one or more keywords <br>(e.g., "Python", "Node", "macOS") corresponding to desired templates. <br><i>gibo</i> then prints the combined content of these templates to standard output, <br>which can be easily redirected to create or append to a <br><b>.gitignore</b> file in the current project. Its features include listing all <br>available templates, searching for specific ones, updating the local template cache, <br>and providing a quick, consistent way to manage ignored files across diverse development <br>environments. It serves as a practical tool for developers to quickly set up <br>appropriate ignore rules without deep knowledge of specific project ignore patterns.


title: CAVEATS
content:
<i>gibo</i> requires an active internet connection to update its template cache. <br>It does not directly modify or create files; its output must be <br>redirected (e.g., using <b>></b> to create/overwrite or <b>>></b> to append) to a <br><b>.gitignore</b> file. The quality and availability of templates are <br>dependent on the upstream <br><i>github/gitignore</i> project. There is no built-in functionality to remove <br>entries or templates from an existing <br><b>.gitignore</b> file, requiring manual editing for such operations.


title: INSTALLATION
content:
<i>gibo</i> is typically installed using Go's package manager, assuming Go is already installed: <br><i>go install github.com/tobiichi/gibo@latest</i><br>Alternatively, it might be available via system-specific package managers, <br>for example, on macOS with Homebrew: <br><i>brew install gibo</i>


title: COMMON USAGE PATTERNS
content:
To create a new <br><b>.gitignore</b> file for a Python and Vim project:<br><i>gibo</i> <I>Python</I> <I>Vim</I> <b>></b> <i>.gitignore</i><br><br>To append Node.js ignore rules to an existing <br><b>.gitignore</b> file:<br><i>gibo</i> <I>Node</I> <b>>></b> <i>.gitignore</i><br><br>To list all available templates:<br><i>gibo</i> <b>--list</b><br><br>To search for templates related to C++:<br><i>gibo</i> <b>--search</b> <I>C++</I>


title: HISTORY
content:
<i>gibo</i> was developed by Tobiichi as a solution to the common problem of <br>managing and generating comprehensive <br><b>.gitignore</b> files for various programming languages and environments. <br>Prior to tools like <i>gibo</i>, developers often had to manually copy <br><b>.gitignore</b> content from online sources or maintain their own local <br>collections, leading to inconsistencies and outdated rules. <br><i>gibo</i> streamlined this process by leveraging the authoritative <br><i>github/gitignore</i> repository, providing a simple command-line interface <br>to fetch and combine templates effortlessly. Its development reflects a broader trend <br>towards automating repetitive development tasks and promoting best practices <br>in version control by providing a centralized and up-to-date source for ignore rules.


title: PARAMETERS
content:
<b><i>input_file.gif</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The path to the input GIF file to be converted.<br><br><b><b>-o</b> <i>output_file.webp</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the path for the output WebP file. This option is mandatory.<br><br><b><b>-q</b> <i>&lt;float&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the compression factor for RGB channels between 0 (low quality, small file) and 100 (high quality, large file). Default is 75.<br><br><b><b>-m</b> <i>&lt;int&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the compression method to use, ranging from 0 (fastest, lowest compression) to 6 (slowest, best compression). Default is 4.<br><br><b><b>-lossy</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Encode using lossy compression. This is the default for animated GIFs.<br><br><b><b>-lossless</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Encode using lossless compression. This is the default for static GIFs.<br><br><b><b>-exact</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Preserve RGB values exactly during lossy compression. This is the default for static GIFs, but can be forced for animated ones.<br><br><b><b>-f</b> <i>&lt;int&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the strength of the deblocking filter for lossy compression, between 0 (no filtering) and 100 (maximum filtering). Default is 0.<br><br><b><b>-min_size</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Encode for minimum size. This option often overrides other quality and compression settings to achieve the smallest possible file.<br><br><b><b>-kframes</b> <i>&lt;int&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set the interval between key frames for animated WebP output. A value of 0 means no key frames are inserted, while 9999 means 1 keyframe per loop. Default is 9999.<br><br><b><b>-loop</b> <i>&lt;int&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the number of times the animation should loop. 0 means infinite loop. Default is 0.<br><br><b><b>-mt</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Use multi-threading for encoding, potentially speeding up the conversion process on multi-core systems.<br><br><b><b>-v</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enable verbose output, displaying conversion progress and statistics.<br><br><b><b>-h</b>, <b>-help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display help message and exit.<br><br><b><b>-version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display version information and exit.<br><br>


title: DESCRIPTION
content:
<i>gif2webp</i> is a command-line utility from the <i>libwebp</i> project, designed to convert GIF image files, including both static and animated GIFs, into the modern WebP image format. WebP offers significantly better compression than GIF, often resulting in smaller file sizes for equivalent image quality, which can dramatically improve website loading performance and reduce bandwidth consumption.<br><br>The tool allows users to specify various encoding options, such as quality factor, compression method, and whether to use lossy or lossless compression. For animated GIFs, it intelligently handles frame delays, loops, and keyframe intervals, translating them into an optimized animated WebP file. <i>gif2webp</i> is a crucial tool for web developers and content creators looking to optimize their visual assets for web delivery.


title: CAVEATS
content:
While <i>gif2webp</i> generally produces smaller files, the optimal quality and file size balance for animated GIFs can require experimentation with options like <b>-q</b>, <b>-m</b>, and <b>-kframes</b>. Extremely complex or large source GIFs might still result in noticeable file sizes even after WebP conversion. The fidelity of color translation and frame timing can sometimes vary slightly depending on the chosen compression settings.


title: HISTORY
content:
<i>gif2webp</i> is part of the <i>libwebp</i> software library, developed by Google, which introduced the WebP image format in 2010. The tool was specifically created to address the significant size of animated GIFs on the web, providing a more efficient, modern alternative. Its development has evolved with the WebP standard, incorporating improvements in compression algorithms and animation handling to ensure robust conversion of legacy GIF assets.


title: PARAMETERS
content:
<b><i>input1.gif</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The path to the first GIF image file to be compared.<br><br><b><i>input2.gif</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The path to the second GIF image file to be compared against the first.<br><br><b><i>output_diff.gif</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The desired path and filename for the resulting GIF image, which will visually display the differences between the two input files.<br><br><b><b>-verbose</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints textual information about the detected differences to standard output, in addition to generating the visual diff image. This can include details like the number of differing pixels.<br><br><b><b>-fuzz</b> <i>percentage</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies a percentage of color difference below which pixels are considered identical for comparison purposes. For example, <b>-fuzz 5%</b> would treat pixels with up to 5% color variation as the same, which is useful for tolerating minor compression artifacts or subtle noise without reporting them as differences.<br><br>


title: DESCRIPTION
content:
<b>gifdiff</b> is a specialized command-line utility designed to visually identify and highlight differences between two GIF image files. Its primary function is to generate a third output GIF image, often referred to as a "diff image," where pixel-level discrepancies between the two input images are clearly marked. This makes <b>gifdiff</b> an indispensable tool for a variety of tasks, including quality assurance in graphic design, verifying the integrity of images after processing or transmission, or simply understanding what changes have occurred between two versions of an animated or static GIF. The tool typically renders identical pixels as transparent or retains their original appearance, while applying a distinct, contrasting color (such as red or magenta) to pixels that do not match. This intuitive visual representation allows users to quickly and precisely pinpoint all alterations, making it far more efficient than manual comparison for detecting even subtle changes.


title: CAVEATS
content:
This command is specifically designed for GIF image files and will not work with other image formats. It is often provided as part of larger image processing suites like ImageMagick or GraphicsMagick, and thus may not be available by default on all Linux distributions. While excellent for visual comparison, for advanced statistical analysis of image differences (e.g., PSNR, RMSE), a more comprehensive tool like <b>compare</b> from ImageMagick might be more suitable.


title: OUTPUT IMAGE INTERPRETATION
content:
The <i>output_diff.gif</i> generated by <b>gifdiff</b> is designed for clarity. Pixels that are identical between <i>input1.gif</i> and <i>input2.gif</i> will typically appear transparent or retain their original color from one of the input images. Conversely, any pixels that differ will be highlighted with a vivid, contrasting color (commonly red or magenta) to make discrepancies immediately obvious to the viewer.


title: EXIT STATUS
content:
<b>gifdiff</b> provides a useful exit status for scripting and automation. It generally returns an exit code of 0 (zero) if the two input GIF images are found to be identical. If any differences are detected between the images, it will typically return a non-zero exit code (e.g., 1). This behavior allows for easy integration into shell scripts or automated workflows to check for image integrity or changes.


title: HISTORY
content:
<b>gifdiff</b> is typically a specialized utility found within larger image processing frameworks such as ImageMagick or GraphicsMagick. Its development is inherently linked to the evolution of these comprehensive libraries, aiming to provide a focused tool for the comparison of GIF images, a format widely used since the early days of the web. While a specific, detailed historical account solely for <b>gifdiff</b> is often not documented, its existence as a consistent utility reflects the ongoing need for precise visual differencing capabilities within the domain of image manipulation.


title: SYNOPSIS
content:
<b>gifsicle</b> [<i>options</i>] [<i>input-files...</i>] [<i>> output-file</i>]<br>
<b>gifsicle</b> [<i>options</i>] <i>input-file</i> <I>#frame-selection</I> [<i>> output-file</i>]<br>
<b>gifsicle</b> <i>--batch</i> [<i>options</i>] <i>input-files...</i>


title: PARAMETERS
content:
<b>-O[level], --optimize[=level]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Optimize GIF for smaller file size. Levels (1-3) control aggressiveness, with 3 being the most aggressive.</I><br><br><b>--lossy=N</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Apply lossy compression, sacrificing some image quality for significant file size reduction. N is quality (0-200).</I><br><br><b>-U, --unoptimize</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Expand optimized GIFs back to an unoptimized form.</I><br><br><b>-b, --batch</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Process multiple input files, writing each output to a new file named from its input. Requires -o or --output to specify output naming convention (e.g., %b.new.gif).</I><br><br><b>-i FILE, --input=FILE</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Specify an input file explicitly, useful when filenames start with a dash.</I><br><br><b>-o FILE, --output=FILE</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Specify the output file name. If omitted, output goes to standard output.</I><br><br><b>-l[N], --loop[=N]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Set the animation loop count. N=0 for infinite loop, otherwise N times. Default is 1 (no loop).</I><br><br><b>-d N, --delay=N</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Set the default delay between frames to N hundredths of a second.</I><br><br><b>-t N, --transparent=N</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Set the transparent color index to N.</I><br><br><b>--crop X,Y+W+H</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Crop the image to the specified rectangle (X,Y) with width W and height H.</I><br><br><b>--resize WxH</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Resize the image to the given width W and height H.</I><br><br><b>--scale X</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Scale the image by a factor of X (e.g., 0.5 for half size, 2 for double).</I><br><br><b>--flip-horizontal, --flip-vertical</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Flip the image horizontally or vertically.</I><br><br><b>--rotate-90, --rotate-180, --rotate-270</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Rotate the image clockwise by 90, 180, or 270 degrees.</I><br><br><b>--merge</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Combine frames from multiple input GIFs into a single new GIF.</I><br><br><b>--delete #X-#Y</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Delete a range of frames from the output GIF.</I><br><br><b>--no-warnings</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Suppress warnings about unusual or problematic GIF features.</I><br><br><b>--colors N</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Reduce the number of colors in the GIF to a maximum of N.</I><br><br><b>--interlace, --dont-interlace</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Force interlacing or non-interlacing for the output GIF.</I><br><br>


title: DESCRIPTION
content:
`gifsicle` is a robust command-line utility designed for creating, manipulating, and optimizing Graphics Interchange Format (GIF) images. It provides extensive capabilities for working with both animated and static GIFs, making it an invaluable tool for developers, web designers, and anyone needing to programmatically process GIFs. Users can create animations from sequences of individual image frames, significantly reduce file sizes through various optimization techniques including lossy compression, and perform a wide range of transformations. These transformations include resizing, cropping, rotating, flipping, and merging multiple GIFs. `gifsicle` also allows for advanced control over animation properties such as frame delays, loop counts, and transparency. Its efficiency and scriptability make it a popular choice for automated GIF processing tasks and integration into larger workflows.


title: CAVEATS
content:
gifsicle is a powerful command-line tool, but it has some considerations. Processing very large GIFs or those with many frames can be memory and CPU intensive. While excellent for batch processing and automated tasks, its command-line interface requires users to learn specific syntax, which might be a barrier for those accustomed to GUI tools. Complex graphical editing features like drawing, layering, or advanced effects are not available; gifsicle focuses on transformations and optimization. Improper use of optimization or unoptimization flags can sometimes lead to an increase in file size instead of a reduction.


title: <B>OPTIMIZATION LEVELS EXPLAINED</B>
content:
<I>The <B>-O</B> or <B>--optimize</B> option supports different levels of optimization:<br> <B>-O1</B> removes duplicate frames and reduces color tables.<br> <B>-O2</B> adds smart frame coalescing and disposal methods.<br> <B>-O3</B> includes global color table reduction and more aggressive pixel-level optimization, often yielding the smallest files but potentially taking longer to process.</I>


title: <B>FRAME SELECTION SYNTAX</B>
content:
<I>Frames in a GIF can be selected using a specific syntax. <B>#N</B> refers to the Nth frame (starting from 0). <B>#X-#Y</B> selects a range of frames from X to Y. <B>#-X</B> selects all frames from X to the end. <B>#+X</B> selects X frames starting from the current selection. This allows precise control over which parts of an animation are modified or extracted.</I>


title: <B>BATCH PROCESSING WITH OUTPUT NAMING</B>
content:
<I>When using the <B>--batch</B> option, `gifsicle` can process multiple input files and generate corresponding output files. The <B>-o</B> or <B>--output</B> option supports format strings for naming the output files. For example, <B>-o %b.new.gif</B> would take an input file like <B>image.gif</B> and produce <B>image.new.gif</B>, where <B>%b</B> represents the base name of the input file.</I>


title: HISTORY
content:
gifsicle was originally authored by Eddie Kohler, with its first public release appearing around 1997. It quickly gained recognition for its efficiency and comprehensive features in GIF manipulation from the command line. Over the years, it has been actively maintained and improved, becoming a staple utility for web developers, designers, and system administrators who require robust and scriptable control over GIF images. Its enduring popularity stems from its ability to handle complex GIF operations while maintaining a lean and fast execution model.


title: SYNOPSIS
content:
<b>giftopnm</b> [<i>options</i>] [<i>giffile</i>]<br>If <i>giffile</i> is omitted, <b>giftopnm</b> reads from standard input. Output is always written to standard output.


title: PARAMETERS
content:
<b><b>-verbose</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints detailed information about the GIF file and the conversion process to standard error.<br><br><b><b>-alphaout</b>={<i>alpha-filename</i>|<b>-</b>}</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Writes the image's alpha (transparency) channel to the specified file. Use <b>-</b> to send it to standard output after the PNM image.<br><br><b><b>-alphamax</b>=<i>maxval</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the maximum pixel value for the alpha output file. Defaults to 255.<br><br><b><b>-background</b>=<i>color</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the color to fill transparent pixels with. Can be a color name (e.g., "red"), hexadecimal color (e.g., "#FF0000"), or "transparent" to retain transparency.<br><br><b><b>-colorfuzz</b>=<i>color</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Used with <b>-transparent</b> to make the specified color match "close" colors, allowing for slight variations.<br><br><b><b>-transparent</b>=<i>color</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies a color to treat as transparent, overriding any transparency information embedded in the GIF file.<br><br><b><b>-gamma</b>=<i>gamma</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Applies gamma correction to the output image.<br><br><b><b>-interlace</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Processes the GIF as if it were interlaced, affecting the order in which scan lines are output.<br><br><b><b>-map</b>=<i>filename</i> or <b>-cmap</b>=<i>filename</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies a colormap file (in PPM format) to which the output image's colors will be mapped.<br><br><b><b>-truecolor</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Forces the output to be a 24-bit truecolor PPM, even if the GIF could be represented by a palette.<br><br><b><b>-fixcolormaps</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Attempts to correct malformed colormaps found in some GIF files.<br><br><b><b>-comment</b>=<i>text</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Adds a comment string to the header of the output PNM file.<br><br>


title: DESCRIPTION
content:
<b>giftopnm</b> is a fundamental utility within the Netpbm image processing suite. It serves the purpose of converting Graphics Interchange Format (GIF) image files into one of the Portable Anymap (PNM) formats: Portable Pixmap (PPM) for color images, Portable Graymap (PGM) for grayscale images, or Portable Bitmap (PBM) for monochrome images. This conversion is crucial for interoperability, allowing GIF images to be processed by other Netpbm tools or piped into other image manipulation programs that understand the PNM formats. <b>giftopnm</b> handles various GIF features, including interlacing and transparency, and can be used in a pipeline, reading from standard input and writing to standard output.


title: CAVEATS
content:
While <b>giftopnm</b> handles most standard GIF features like interlacing and transparency, it typically processes only the first frame of multi-frame (animated) GIF files. For full manipulation of animated GIFs, specialized tools like <b>gifsicle</b> are usually required. The quality of output for very old or malformed GIF files might vary, though the <b>-fixcolormaps</b> option attempts to mitigate some issues.


title: INTEGRATION INTO NETPBM PIPELINES
content:
<b>giftopnm</b> excels when used as part of a larger image processing pipeline. Its ability to read from standard input and write to standard output allows it to be seamlessly chained with other Netpbm commands (e.g., <b>giftopnm image.gif | ppmtojpeg > image.jpg</b>) or external tools, facilitating complex image transformations without requiring temporary files.


title: HANDLING TRANSPARENCY
content:
The command provides robust options for managing GIF transparency. By default, transparent pixels are rendered black. However, users can specify a <b>-background</b> color to fill these areas or use <b>-alphaout</b> to extract the transparency information into a separate PGM file, which can then be used as a mask for further processing.


title: HISTORY
content:
<b>giftopnm</b> is a component of the Netpbm package, a venerable open-source project that originated in the late 1980s as the PBMplus toolkit. PBMplus was developed by Jef Poskanzer, and the Netpbm suite, which incorporates and extends PBMplus, has been actively maintained and expanded by various contributors over decades. The command's longevity is a testament to the enduring utility of simple, robust image conversion tools in the Unix philosophy of chaining small tools together. Its design reflects the Netpbm philosophy of handling "portable anymap" formats as an intermediate step for diverse image manipulations.


title: PARAMETERS
content:
<b>-h, --help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show the full list of command-line options.<br><br><b>-v, --version</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display the GIMP version information.<br><br><b>--verbose</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enable verbose output during startup and execution.<br><br><b>--no-data</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Do not load patterns, gradients, palettes, or brushes.<br><br><b>--no-fonts</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Do not load any fonts. Useful for debugging font issues.<br><br><b>--no-splash</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Do not show the splash screen during startup.<br><br><b>--no-interface</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Run GIMP in batch mode without a graphical user interface (GUI).<br><br><b>--display <I>display</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the X display to use for the graphical interface.<br><br><b>--batch-interpreter <I>interpreter</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the interpreter to use for batch commands (e.g., 'gimprc-batch', 'python-fu-batch').<br><br><b>-b, --batch <I>commands</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Execute the specified commands in batch mode. Typically combined with '--no-interface' and '--quit'.<br><br><b>--quit</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Quit GIMP after executing all batch commands. Useful for automated processing.<br><br><b>--gimprc <I>filename</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Use an alternative user GIMP resource file instead of the default.<br><br><b>--system-gimprc <I>filename</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Use an alternative system-wide GIMP resource file.<br><br><b>--session <I>name</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Use a new GIMP session with the given name. Useful for running multiple instances.<br><br>


title: DESCRIPTION
content:
The <b>GIMP</b> (GNU Image Manipulation Program) is a free and open-source raster graphics editor primarily used for image retouching, image composition, and image authoring. It provides a sophisticated set of tools for tasks such as photo manipulation, creating original artwork, web graphics design, and converting image formats. GIMP supports a wide array of file formats and offers advanced features like layers, masks, customizable brushes, filters, and a robust plugin architecture. It's a versatile tool employed by graphic designers, photographers, illustrators, and scientists for both creative and technical image-related work. Being cross-platform, it runs on Linux, macOS, and Windows. Its extensive scripting capabilities (via Script-Fu/Scheme and Python) also make it powerful for automating repetitive tasks and batch processing, allowing users to control its functionalities from the command line without the graphical interface.


title: CAVEATS
content:
GIMP is primarily a GUI application. While it supports powerful command-line options for batch processing and automation, its core functionality relies on the graphical interface. For simple image conversions or manipulations that don't require GIMP's advanced features, other command-line tools like ImageMagick might be more efficient and resource-friendly.<br>Batch mode scripting often requires knowledge of Script-Fu (Scheme) or Python scripting within the GIMP environment.


title: BATCH PROCESSING
content:
GIMP's command-line interface is exceptionally powerful for automating tasks. By combining the <b>--no-interface</b>, <b>--batch</b>, and <b>--quit</b> options, users can write scripts to perform complex operations like resizing, watermarking, or format conversion on multiple images without opening the graphical interface. This makes GIMP a valuable tool in server-side automation or large-scale image processing workflows.


title: SCRIPTING LANGUAGES
content:
GIMP extends its functionality through internal scripting using Script-Fu (based on Scheme) and external scripting via Python (Python-Fu). These interfaces allow users to create custom plugins and automate complex workflows, significantly enhancing GIMP's versatility beyond its built-in features.


title: HISTORY
content:
GIMP was initially started by Spencer Kimball and Peter Mattis in 1995 as a university project at the University of California, Berkeley. It was originally named the <i>General Image Manipulation Program</i>. In 1997, it became part of the GNU Project, and its name was changed to the <i>GNU Image Manipulation Program</i>. The first public release, GIMP 0.54, was in 1996. It quickly gained popularity as a powerful open-source alternative to proprietary image editing software, fostering a vibrant community of users and developers who contributed to its feature set and plugin ecosystem. Its development has seen significant evolution, including changes to its single-window vs. multi-window interface, continuous improvements in performance, and expansion of its professional-grade features.


title: SYNOPSIS
content:
As <i>ginstall-info</i> is not a standard command with its own manual page, there is no universal synopsis. However, if it functions as a wrapper for the standard <i>install-info</i> command, its underlying invocation would typically resemble:<br><br><b>install-info</b> [<i>OPTION</i>]... <i>INFO-FILE</i> [<i>NODE</i>]


title: PARAMETERS
content:
<b>--add</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Adds the specified Info file to the Info directory. This is the default action if not specified.<br><br><b>--remove</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Removes the specified Info file from the Info directory and its entry from the `dir` file.<br><br><b>--delete</b><br>&nbsp;&nbsp;&nbsp;&nbsp;An older alias for <b>--remove</b>.<br><br><b>--info-dir=DIR</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the root directory where Info files are stored (e.g., `/usr/share/info`).<br><br><b>--locale=LOCALE</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the locale for the Info file being installed or removed, allowing for language-specific documentation.<br><br><b>--section=SECTION</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Assigns the Info file to a specific section within the `dir` file, organizing the documentation.<br><br><b>--entry-description=DESCRIPTION</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Provides a custom description for the Info file's entry in the `dir` file.<br><br><b>--dry-run</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows what actions would be performed without actually modifying the system.<br><br><b>--quiet</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Suppresses most output during the operation.<br><br><b>--version</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays version information for the `install-info` utility and exits.<br><br><b>--help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a help message for the `install-info` utility and exits.<br><br>


title: DESCRIPTION
content:
The command <i>ginstall-info</i> is not a standard, standalone executable found in most Linux distributions or official documentation. Its name strongly suggests a connection to the GNU Project and specifically the <i>install-info</i> command, which is a standard utility used to add or remove documentation files in the GNU Info format from the system's Info directory and update the `dir` file (the master directory of Info nodes).<br><br>The 'g' prefix likely signifies its association with GNU software, such as components of the GNU Compiler Collection (GCC) or other GNU tools. It is commonly encountered within build systems (e.g., Makefiles generated by GNU Autotools) where it acts as a target or an internal script that wraps or calls the standard <i>install-info</i> utility with parameters specific to the documentation being installed for that particular GNU package.


title: CAVEATS
content:
<i>ginstall-info</i> is not a standard, user-executable command found in the system's PATH. Attempting to run it directly or look up a manual page for `ginstall-info` will typically result in an error indicating the command is not found. If encountered, it is almost certainly a part of a software's build or installation script, specifically designed to manage its documentation using the underlying <i>install-info</i> utility. Users should refer to the specific project's documentation or Makefile for details on its exact function and parameters within that context. The parameters listed above are for the standard <i>install-info</i> command, which <i>ginstall-info</i> likely invokes.


title: ROLE IN BUILD SYSTEMS
content:
In many GNU-style software projects that use Autotools (Autoconf and Automake), targets like `install-info` or custom-named targets (e.g., `ginstall-info`) are often generated in the project's `Makefile`. When a user runs `make install`, these targets ensure that the project's Info documentation is properly installed and registered on the system, making it accessible via the `info` reader. This abstraction allows developers to integrate Info documentation installation seamlessly into their build process without requiring users to manually run `install-info`.


title: HISTORY
content:
The utility for managing GNU Info documentation, <i>install-info</i>, has been a fundamental part of the GNU Texinfo package (which provides tools for creating, reading, and managing Info files) for many years, dating back to the early days of the GNU Project. The appearance of a name like <i>ginstall-info</i> does not signify a separate utility with its own development history, but rather reflects the integration of <i>install-info</i> into GNU software's build and installation processes. It often serves as an internal or aliased call within Makefiles (e.g., `make install-info` or a custom `make` target) to ensure that the Info documentation for specific GNU components (like GCC, GDB, etc.) is correctly registered with the system's Info directory during installation.


title: SYNOPSIS
content:
<br><b>gio</b> <i>COMMAND</i> [<i>OPTIONS</i>] [<i>ARGUMENTS...</i>]<br><br>This utility executes various <I>GIO</I> operations. Common <I>COMMAND</I>s include <I>cat</I>, <I>copy</I>, <I>info</I>, <I>list</I>, <I>mount</I>, <I>open</I>, <I>trash</I>, and <I>rename</I>. Each <I>COMMAND</I> has its own specific options and arguments.


title: PARAMETERS
content:
<b>COMMAND</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the GIO operation to perform (e.g., <I>cat</I>, <I>copy</I>, <I>list</I>, <I>mount</I>, <I>open</I>, <I>trash</I>). Each command has its own specific options and arguments.<br><br><b>ARGUMENTS...</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Arguments specific to the chosen <I>COMMAND</I>, often including URIs or file paths.<br><br><b>-v, --version</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display the GIO version information.<br><br><b>-h, --help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display a general help message or help for a specific <I>COMMAND</I> if provided (e.g., '<b>gio help mount</b>').<br><br><b>--debug</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enable debugging output (specific to some GIO contexts).<br><br>


title: DESCRIPTION
content:
<b>gio</b> is a versatile command-line utility part of the <I>GLib</I> library, providing access to <I>GIO</I> functionality. <I>GIO</I> is a modern, asynchronous I/O framework used primarily by <I>GNOME</I> and <I>GTK</I> applications. It abstracts various file systems, network locations (like FTP, HTTP, SFTP, SMB), and other URI schemes, allowing applications to interact with them uniformly.<br><br>The <b>gio</b> command acts as a wrapper, offering various subcommands to perform operations such as listing directory contents, copying/moving files, trashing, mounting, and managing MIME types, all using the <I>GIO</I> abstraction. This makes it a powerful tool for scripting and interacting with system resources in a consistent manner, regardless of the underlying protocol or location.


title: CAVEATS
content:
<ul><li><b>gio</b> commands primarily operate on URIs (Uniform Resource Identifiers). While local file paths work, they are internally converted to <I>file:///</I> URIs.</li><li>The exact set of supported URI schemes depends on the installed GIO modules and backend providers (e.g., <I>GVfs</I> for desktop environments).</li><li>Errors are often related to permissions, network issues, or unsupported URI schemes.</li></ul>


title: URI ABSTRACTION
content:
<i>gio</i> commands operate on URIs, allowing seamless interaction with various protocols like <i>http://</i>, <i>ftp://</i>, <i>sftp://</i>, <i>smb://</i>, <i>nfs://</i>, and <i>file://</i> (for local files). This provides a consistent interface regardless of the storage backend.


title: INTEGRATION WITH DESKTOP ENVIRONMENTS
content:
In desktop environments like <I>GNOME</I> or <I>Cinnamon</I>, <i>gio</i> leverages services like <I>GVfs</I> (GNOME Virtual File System) to manage mounts, network shares, and trash operations, often without requiring root privileges for common tasks.


title: ASYNCHRONOUS OPERATIONS
content:
While the <i>gio</i> command-line utility executes synchronously, the underlying <I>GIO</I> library is designed for asynchronous operations, which is crucial for responsive GUI applications.


title: HISTORY
content:
<b>gio</b> is part of the <I>GIO</I> library, which was introduced in <I>GLib</I> 2.16 (released around 2007) as a modern, asynchronous I/O framework. It was designed to replace older, less flexible I/O mechanisms within <I>GNOME</I> and <I>GTK</I> applications, offering a unified API for local and remote file systems. The <b>gio</b> command-line utility provides a direct way to interact with this framework, serving as a scripting interface to <I>GIO</I> functionality that applications utilize. Its development is tied to the evolution of <I>GLib</I> and the <I>GNOME</I> desktop environment.


title: PARAMETERS
content:
<b><I>LOCATION</I>...</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies one or more directories to scan for GIO modules. If no locations are provided, <i>gio-querymodules</i> scans standard system-wide and user-specific GIO module paths.<br><br><b>--help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a concise help message and exits.<br><br><b>--version</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows the version information of the <i>gio-querymodules</i> utility and exits.<br><br>


title: DESCRIPTION
content:
<i>gio-querymodules</i> is a utility designed to manage and update the GIO module cache. GIO (G Library for Input/Output) is a foundational library in the GNOME desktop environment and other GTK+ applications, providing a modern, asynchronous, object-oriented API for I/O operations. GIO utilizes a plugin-like system called "GIO modules" to extend its capabilities, enabling support for various URI schemes (like sftp://, http://), different file system backends, and other I/O abstractions. <br><br> To optimize performance and reduce startup times for GIO-based applications, <i>gio-querymodules</i> scans predefined system paths (or specified locations) for these GIO modules and compiles a binary cache file. This cache file stores information about the available modules and their capabilities, allowing applications to quickly discover and load necessary functionality without having to scan the filesystem repeatedly. <br><br> This command is typically invoked automatically by package managers when GIO-related packages are installed, updated, or removed, ensuring the module cache remains consistent with the installed software. Manually running <i>gio-querymodules</i> forces a rebuild of this cache, which can be useful for troubleshooting or after manually deploying new GIO modules.


title: CAVEATS
content:
For the cache to be effective, <i>gio-querymodules</i> must be run with appropriate permissions to write to the cache file location (e.g., system-wide caches typically require root privileges). If the cache is outdated or corrupted, GIO-based applications might fail to find necessary modules, leading to unexpected errors or missing functionality. Users might need to manually run this command if modules are installed without package manager involvement or if system-wide changes affect GIO module paths.


title: CACHE LOCATIONS
content:
GIO module cache files are typically located in system-wide directories such as <I>/usr/lib/gio/modules/</I> or <I>/usr/local/lib/gio/modules/</I> (for system-wide modules), and in user-specific locations like <I>~/.cache/gio-modules/</I> (for user-installed modules or overrides). The exact path can vary slightly depending on the distribution and installation prefix.


title: AUTOMATIC EXECUTION
content:
In most Linux distributions, <i>gio-querymodules</i> is automatically invoked by package managers (e.g., during 'apt install', 'dnf update', 'pacman -S') when packages providing GIO modules are installed, updated, or removed. This ensures that the system's GIO module cache is always up-to-date without requiring manual intervention from the user.


title: HISTORY
content:
The <i>gio-querymodules</i> command is part of the GLib library, which is a core dependency of the GNOME project. GLib itself has been developed since the mid-1990s. GIO, as a modern, object-oriented I/O abstraction layer within GLib, was introduced later, significantly improving how applications handle file operations, network communication, and plugin management. <i>gio-querymodules</i> specifically emerged as a necessary component to efficiently manage the plugin-based architecture of GIO modules, optimizing application startup and runtime performance by pre-indexing available modules, similar to how other system components like dynamic linker caches (ldconfig) or MIME type databases are managed.


title: PARAMETERS
content:
<b><i>LOCATION...</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;One or more file paths or URIs specifying the files or directories to be moved to the trash. Directories are trashed recursively.<br><br><b><b>-d</b>, <b>--dry-run</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Performs a simulation of the trash operation without actually moving any files. This option prints what would be done.<br><br><b><b>-f</b>, <b>--force</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Ignores non-existent files and arguments, preventing errors when some specified paths do not exist.<br><br><b><b>-v</b>, <b>--verbose</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables verbose output, explaining what is being done during the trash operation.<br><br><b><b>-h</b>, <b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a brief help message about the <b>gio trash</b> command and its options.<br><br><b><b>--version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows the version information of the <b>gio</b> utility.<br><br>


title: DESCRIPTION
content:
The <b>gio-trash</b> command is a subcommand of the <b>gio</b> utility, which is a core component of the GLib/GIO library used primarily in desktop environments like GNOME. Unlike the <b>rm</b> command that permanently deletes files, <b>gio-trash</b> moves specified files or directories to the user's trash can, typically located at <i>~/.local/share/Trash</i>. This allows for easy recovery of accidentally discarded items through a graphical file manager or by manually moving them from the trash directory. It leverages GIO's capabilities to handle various URI schemes, enabling trashing not only local files but also files on supported remote locations, offering a unified and desktop-integrated way of managing discarded items.


title: CAVEATS
content:
Files moved to the trash are not permanently deleted; they consume disk space until the trash is explicitly emptied. <br>The trash location is typically user-specific, usually <i>~/.local/share/Trash</i>. <br>Trashing might not be directly supported on all file systems or remote locations; in such cases, files might be permanently deleted or an error may occur. <br>This command relies on GLib/GIO and is primarily found in desktop Linux environments, not standard in minimal server installations.


title: RESTORING FILES
content:
Files moved to the trash can usually be restored by opening the 'Trash' or 'Bin' folder in your graphical file manager (e.g., Nautilus, Dolphin, Thunar) and moving them back to their original location or a new desired location. Alternatively, you can manually navigate to <i>~/.local/share/Trash/files/</i> and move the desired files from there using the <b>mv</b> command, although this is less common.


title: EMPTYING TRASH
content:
To permanently delete files from the trash and free up disk space, you typically need to use your graphical file manager's 'Empty Trash' or 'Empty Bin' option. There isn't a direct <b>gio</b> command designed specifically for emptying the entire trash folder, reinforcing its role as a tool for moving to trash rather than managing the trash contents themselves.


title: HISTORY
content:
The <b>gio</b> utility, including <b>gio-trash</b>, is part of the GLib and GIO library, a foundational component of the GNOME desktop environment. It emerged as a modern, unified I/O layer, consolidating and often superseding older mechanisms like parts of GVFS (GNOME Virtual File System). <b>gio-trash</b> specifically provides the command-line equivalent of the 'Move to Trash' functionality found in graphical file managers, aligning with desktop conventions for managing discarded files. Its development reflects the ongoing evolution towards a more integrated and user-friendly file management experience in Linux desktop environments.


title: PARAMETERS
content:
<b>-x <file.netxml></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the input Kismet <i>netxml</i> file. Multiple files can be provided to combine data from several captures.<br><br><b>-o <output_file></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the name of the output file. The file extension typically determines the output format (e.g., <i>.kml</i> for KML, <i>.csv</i> for CSV).<br><br><b>-t <type></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Defines the output format. Supported types include `kml` (default for mapping), `csv` (for spreadsheet analysis), and `xml` (for structured data exchange).<br><br><b>-f <filter_string></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Applies a filter to the output, allowing selection based on criteria like `OPEN`, `WEP`, `WPA`, `SSID=MyNetwork`, `BSSID=00:11:22:33:44:55`, `CHAN=6`, or `MANF=Cisco`.<br><br><b>-s</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays only unique SSIDs (network names) found, rather than individual BSSIDs (MAC addresses of access points).<br><br><b>-u</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Outputs only unique BSSIDs encountered, preventing duplicate entries for the same access point captured multiple times.<br><br><b>-a</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Includes all discovered networks in the output, even those without associated GPS coordinates. By default, only GPS-tagged networks are shown.<br><br><b>-h</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows a help message summarizing command-line options and exits.<br><br>


title: DESCRIPTION
content:
<i>giskismet</i> is a utility designed to process <b>Kismet</b> <i>netxml</i> and <i>gpsxml</i> files. Kismet is a popular wireless network detector, sniffer, and intrusion detection system. When Kismet captures Wi-Fi network information, it saves it in a <i>netxml</i> file, which contains details about discovered access points (SSIDs, MAC addresses, encryption types, signal strengths, etc.) and associated GPS coordinates (if a GPS device is used).<br><br><i>giskismet</i> takes these raw <i>netxml</i> files and parses the data, extracting relevant information about Wi-Fi networks and their geographical locations. Its primary function is to transform this data into a format that can be easily visualized on mapping services. It can generate <b>KML</b> (Keyhole Markup Language) files, which are standard for geographical annotation and visualization, compatible with applications like <i>Google Earth</i>, <i>Google Maps</i>, and other GIS software. This allows users to plot discovered Wi-Fi networks directly onto a map, showing where they were found.<br><br>Beyond KML export, <i>giskismet</i> can also export data in other formats like <b>CSV</b> (Comma Separated Values) for spreadsheet analysis, and <b>XML</b>, providing flexibility for further processing or custom reporting. It offers various filtering options, enabling users to focus on specific types of networks, such as open access points, WEP/WPA encrypted networks, or particular SSIDs. This makes <i>giskismet</i> an invaluable tool for network security professionals, penetration testers, and enthusiasts engaged in wardriving or wireless network mapping. It aids in understanding the geographical distribution and security posture of wireless networks in a given area.


title: CAVEATS
content:
<i>giskismet</i> is a post-processing tool and does not perform active scanning. Its effectiveness is directly tied to the quality and completeness of the input <i>Kismet</i> <i>netxml</i> files, particularly the presence and accuracy of GPS data for geographical mapping. Without valid GPS coordinates in the Kismet capture, the mapping functionality is limited or unavailable.


title: MAPPING INTEGRATION
content:
The primary strength of <i>giskismet</i> lies in its ability to generate <b>KML</b> files, which are natively supported by popular mapping services like <i>Google Earth</i> and <i>Google Maps</i>. This allows users to easily import and visualize discovered Wi-Fi networks on a global map, gaining geographical context for their wireless security assessments.


title: DATA EXPORT VERSATILITY
content:
Beyond KML, <i>giskismet</i> offers export options to <b>CSV</b> and <b>XML</b>. The <b>CSV</b> format is ideal for importing network data into spreadsheets for further statistical analysis, sorting, and custom reporting. The <b>XML</b> output provides a structured, machine-readable format suitable for integration with other scripts or analysis tools.


title: HISTORY
content:
<i>giskismet</i> emerged as a specialized tool within the broader <i>Kismet</i> ecosystem, specifically designed to leverage the geographical positioning data that <i>Kismet</i> can collect during wireless network surveys. Its development addressed the growing need for visual analysis of 'wardriving' data, transforming raw network capture logs into interactive map visualizations. It has been maintained and updated to remain compatible with evolving <i>Kismet</i> <i>netxml</i> formats and mapping technologies, serving as a critical component for network security professionals and enthusiasts mapping wireless environments.


title: SYNOPSIS
content:
<b>gist</b> [<i>options</i>] [<i>file...</i>]<br><b>gist</b> -l<br><b>gist</b> -d <i>GIST_ID</i><br><b>gist</b> -u <i>GIST_ID</i> [<i>file...</i>]<br><b>gist</b> -o [<i>GIST_ID</i>]<br><b>gist</b> -p | -s [<i>file...</i>]<br><b>gist</b> -a [<i>file...</i>]<br><b>gist</b> -h | -v


title: PARAMETERS
content:
<b>-p, --private, -s, --secret</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Makes the created gist private (secret), meaning it will not be discoverable by others unless they have the direct URL.<br><br><b>-P, --public</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Explicitly makes the created gist public. This is often the default behavior if no privacy option is specified.<br><br><b>-d, --delete <I>GIST_ID</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Deletes the specified gist. Requires authentication and ownership of the gist.<br><br><b>-u, --update <I>GIST_ID</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Updates an existing gist with new content from specified files or STDIN. Requires authentication and ownership.<br><br><b>-l, --list</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Lists your gists. Requires authentication to list private gists.<br><br><b>-o, --open [<i>GIST_ID</i>]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Opens the created gist (or a specified existing gist) in your default web browser.<br><br><b>-c, --copy</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Copies the URL of the created gist to your system's clipboard.<br><br><b>-a, --anonymous</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Creates a gist anonymously, not associated with your GitHub account.<br><br><b>-h, --help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays the help message, showing command usage and options.<br><br><b>-v, --version</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows the version information of the <I>gist</I> command.<br><br><b>-f, --filename <I>FILENAME</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies a filename for content provided via STDIN. Useful for syntax highlighting on GitHub.<br><br><b>-r, --raw</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints the raw content of a gist (identified by <I>GIST_ID</I> or the last created gist) to standard output.<br><br><b>--description <I>DESCRIPTION</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Adds a textual description to the gist being created or updated.<br><br><b>--embed</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Outputs the HTML embed code for the created gist, allowing it to be easily embedded in web pages.<br><br>


title: DESCRIPTION
content:
The <I>gist</I> command-line utility provides a convenient interface for interacting with GitHub Gists directly from your terminal. GitHub Gists are a simple way to share notes, code snippets, and configuration files with others. The <I>gist</I> command simplifies the process of creating new gists from files or standard input, managing existing gists (like listing, opening in a browser, updating, or deleting), and controlling their privacy settings (public or secret). It's particularly useful for quickly sharing code during debugging sessions, demonstrating concepts, or collaborating on small pieces of text. Unlike full-fledged version control systems, Gists are designed for simplicity and quick sharing, and the <I>gist</I> command enhances this efficiency by integrating it directly into your command-line workflow. It typically relies on <I>curl</I> for API interactions and can be configured with a GitHub personal access token for authenticated operations.


title: CAVEATS
content:
The <I>gist</I> command is not a standard, pre-installed Linux utility; it must be downloaded and installed separately. It typically relies on external tools like <I>curl</I> for network requests and, for clipboard functionality, tools such as <I>xclip</I> (Linux) or <I>pbcopy</I> (macOS). To fully utilize features like listing your private gists, deleting, or updating existing ones, you will need a GitHub account and often a personal access token for authentication, which is usually stored in a configuration file (e.g., <I>~/.gist</I>). Without proper authentication, only public or anonymous gist creation might be available.


title: AUTHENTICATION
content:
To interact with your GitHub account (e.g., for private gists, listing your gists, or updating), <I>gist</I> typically uses a GitHub Personal Access Token. This token can be stored in a configuration file, commonly <I>~/.gist</I>, or the command might prompt you for your GitHub username and password the first time you perform an authenticated action. Ensure the token has the necessary 'gist' scope to grant appropriate permissions.


title: INPUT HANDLING
content:
The <I>gist</I> command can accept input in several ways. You can provide one or more filenames as arguments, and each file will be uploaded as part of the new gist. If no files are specified, <I>gist</I> reads content from standard input (STDIN), allowing you to pipe output from other commands directly into a new gist. For example, <I>ls -l | gist</I> would create a gist containing the long listing of files.


title: HISTORY
content:
The <I>gist</I> command emerged as a popular and simple shell script, notably the one by <I>defunkt</I> (Chris Wanstrath), designed to streamline interactions with GitHub Gists. Its development was driven by the need for a quick and uncumbersome way to share code snippets directly from the command line, bypassing the web interface. Its lightweight nature and ease of installation contributed to its widespread adoption among developers for rapid sharing and collaboration.


title: SYNOPSIS
content:
<pre>git [--version] [--help] [--git-dir=&lt;path&gt;]<br>    [--work-tree=&lt;path&gt;] [--namespace=&lt;name&gt;]<br>    [-p|--paginate] [-P|--no-pager] [--bare]<br>    &lt;I&gt;command&lt;/I&gt; [&lt;I&gt;args&lt;/I&gt;]</pre><br>This synopsis shows the general invocation of Git. Most Git operations involve a specific <I>command</I> (e.g., <I>clone</I>, <I>add</I>, <I>commit</I>) followed by its own set of arguments and options.


title: PARAMETERS
content:
<b><I>command</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The specific Git operation to perform (e.g., <I>add</I>, <I>commit</I>, <I>push</I>). Git has hundreds of subcommands, each with its own set of options.<br><br><b>--version</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays the Git version information.<br><br><b>--help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays help information for Git or a specific subcommand (e.g., <I>git help commit</I>).<br><br><b>--git-dir=&lt;path&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the path to the repository (<I>.git</I>) directory.<br><br><b>--work-tree=&lt;path&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the path to the working tree directory.<br><br><b>--no-pager</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Disables the pager for Git output, showing everything directly to the console.<br><br><b>--bare</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Operates on a bare repository, which has no working tree.<br><br><b>init</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Creates a new empty Git repository or reinitializes an existing one.<br><br><b>clone &lt;repository&gt; [&lt;directory&gt;]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Clones a repository into a new directory.<br><br><b>add [&lt;file&gt;...]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Adds file contents to the index (staging area).<br><br><b>status</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows the working tree status.<br><br><b>commit [-m &lt;message&gt;]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Records changes to the repository.<br><br><b>branch [&lt;name&gt;]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Lists, creates, or deletes branches.<br><br><b>checkout &lt;branch|commit|file&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Switches branches or restores working tree files.<br><br><b>merge &lt;branch&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Joins two or more development histories together.<br><br><b>pull</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Fetches from and integrates with another repository or a local branch.<br><br><b>push</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Updates remote refs along with associated objects.<br><br><b>log</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows commit logs.<br><br><b>remote</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Manages set of tracked repositories.<br><br><b>config</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Gets and sets repository or global options.<br><br>


title: DESCRIPTION
content:
Git is a free and open-source <I>distributed version control system</I> (DVCS) designed to handle everything from small to very large projects with speed and efficiency. It tracks changes in source code during software development, enabling multiple developers to work together on the same project without stepping on each other's toes. Git provides robust features for branching, merging, and reverting to previous states, making it an indispensable tool for collaborative programming and maintaining a comprehensive history of a project's evolution. Unlike older centralized systems, Git operates on a distributed model where every developer's working copy of the code is a full-fledged repository with complete history and version tracking capabilities, allowing for offline work and resilient operations.


title: CAVEATS
content:
<b>Complexity:</b> While powerful, Git's vast array of commands and options can be overwhelming for new users. Understanding its underlying concepts (e.g., index/staging area, detached HEAD) is crucial.<br><b>Merge Conflicts:</b> Resolving merge conflicts can be challenging, especially in large projects with frequent concurrent changes.<br><b>Large Files:</b> Git is not ideal for managing very large binary files directly due to its content-addressable nature, which stores every version of every file. <I>Git Large File Storage (LFS)</I> is often used as a workaround.


title: CONFIGURATION
content:
Git uses configuration files to customize its behavior, which can be set at system-wide, global (user-specific), or local (repository-specific) levels using the <I>git config</I> command. This includes setting user identity, aliases, default editor, and more.


title: BRANCHING STRATEGY
content:
Git's strength lies in its lightweight branching model, enabling developers to create isolated environments for new features or bug fixes. Common branching strategies like Gitflow or GitHub Flow provide structured workflows for team collaboration and release management.


title: HISTORY
content:
Git was created by <I>Linus Torvalds</I> in 2005 for development of the Linux kernel, after the project's previous distributed version control system, BitKeeper, revoked its free usage. Torvalds sought a distributed system that was fast, had strong support for non-linear development (thousands of parallel branches), and was completely free and open source. Within months of its initial release, Git became the primary tool for Linux kernel development, and it has since grown to be the most widely used version control system in the world, adopted by millions of developers and organizations.


title: PARAMETERS
content:
<b>--abort</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Discards the current in-progress operation and returns the repository to its state before the operation began. The specific behavior varies depending on the command it's used with.<br><br>


title: DESCRIPTION
content:
The <b>--abort</b> option is a crucial mechanism within Git that allows users to gracefully exit from an interrupted or problematic operation, such as a merge, rebase, cherry-pick, or revert. <br><br>Many Git commands that modify the repository's history or apply changes can leave the repository in a 'mid-operation' state if they are interrupted, for instance, by conflicts, manual intervention, or errors. In such cases, Git typically leaves behind internal state files (e.g., <i>.git/MERGE_HEAD</i>, <i>.git/REBASE_HEAD</i>) that indicate an operation is pending. <br><br>By invoking the original command with the <b>--abort</b> flag (e.g., <b>git merge --abort</b>), Git attempts to revert the repository to its exact state prior to the start of that specific operation. This includes discarding any partial changes in the working directory and index related to the aborted operation, ensuring a clean slate to restart or choose a different approach. It's an essential tool for recovering from complex scenarios or unintended actions without manual cleanup.


title: CAVEATS
content:
The <b>--abort</b> option only works if an operation is genuinely in progress; otherwise, it will typically report an error. <br><br>It discards all uncommitted changes and progress related to the interrupted operation, so ensure you do not need them. <br><br>It does not undo commits that were already successfully applied during a multi-step operation (e.g., a rebase might have applied several commits before hitting a conflict; <b>--abort</b> would only undo the current conflicting step, not previously applied commits). <br><br>The exact behavior and cleanup vary slightly across different Git commands.


title: COMMON USE CASES
content:
<b>git merge --abort</b>: Use when a merge results in complex conflicts you wish to resolve differently or if you decide not to proceed with the merge.<br><br><b>git rebase --abort</b>: Essential for exiting an interactive rebase session if you encounter issues, make a mistake, or decide to abandon the rebase operation entirely.<br><br><b>git cherry-pick --abort</b>: Allows stopping a cherry-pick operation after a conflict, discarding the partial changes.


title: INTERNAL MECHANISM
content:
When Git enters an interruptible state (e.g., during a merge conflict), it often records the state by creating special files in the <i>.git/</i> directory (e.g., <i>.git/MERGE_HEAD</i>, <i>.git/REBASE_HEAD</i>, <i>.git/CHERRY_PICK_HEAD</i>). The <b>--abort</b> command typically cleans up these internal state files and often performs a <b>git reset --hard</b> to the commit before the operation began, effectively restoring the repository to its previous clean state.


title: HISTORY
content:
The concept of aborting operations has been integral to Git's design since its early days, as complex history manipulation and conflict resolution are core features. While not a standalone command, the <b>--abort</b> option for various subcommands has evolved alongside the commands themselves, becoming a standardized way to handle interruptions and provide robust recovery mechanisms for users. It represents a fundamental aspect of Git's user-friendly error handling for complex workflows.


title: SEE ALSO
content:
git-merge(1), git-rebase(1), git-cherry-pick(1), git-revert(1), git-am(1), git-bisect(1), git-reset(1)


title: SYNOPSIS
content:
<b>git add</b> [<options>] [--] [<pathspec>...]<br><b>git add</b> -A<br><b>git add</b> -u<br><b>git add</b> -p


title: PARAMETERS
content:
<b><b>&lt;pathspec&gt;...</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies files or directories whose changes should be staged. If omitted, <b>git add</b> typically acts on the current directory and its subdirectories, similar to <b>git add .</b><br><br><b><b>-A</b>, <b>--all</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Stages all changes (new, modified, and deleted files) across the entire working tree, regardless of the current directory.<br><br><b><b>-u</b>, <b>--update</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Stages changes only for files that are already <i>tracked</i> by Git. This includes modifications and deletions but excludes new, untracked files.<br><br><b><b>-p</b>, <b>--patch</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enters interactive <i>patch mode</i>, allowing you to review and selectively stage individual hunks (blocks of changes) within files. This is useful for splitting a single file's modifications into multiple commits.<br><br><b><b>-i</b>, <b>--interactive</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Starts an interactive shell where you can choose various options like staging, unstaging, or seeing status of files.<br><br><b><b>-f</b>, <b>--force</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Allows adding files that are ignored by <i>.gitignore</i>, or files that would otherwise be rejected for being outside the current Git repository.<br><br><b><b>-n</b>, <b>--dry-run</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows what would be added without actually performing the staging operation.<br><br><b><b>-v</b>, <b>--verbose</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Be verbose, reporting files as they are added.<br><br>


title: DESCRIPTION
content:
The <b>git add</b> command is fundamental to Git's workflow, responsible for moving changes from the working directory into the <i>staging area</i> (also known as the <i>index</i>). This intermediate step allows developers to prepare a specific set of changes for the subsequent commit.<br><br>When you modify, create, or delete files in your working directory, Git initially considers these changes untracked or unstaged. <b>git add</b> brings these changes into the staging area, creating a snapshot of what will be included in the next commit. This enables granular control, allowing users to craft focused and atomic commits by selecting only relevant changes, even if multiple modifications have been made across various files.<br><br>Common usage involves adding individual files (e.g., <b>git add file.txt</b>), an entire directory, or all changes in the repository (e.g., <b>git add .</b> or <b>git add -A</b>). Without explicitly running <b>git add</b>, your modifications will not be part of the next <b>git commit</b>, remaining in the working directory as unstaged changes. This command empowers precise control over the commit history.


title: CAVEATS
content:
<b>git add</b> only stages changes; it does not save them permanently to the repository. A subsequent <b>git commit</b> command is required to record the staged changes.<br><br>If you stage a file and then make further modifications to it, those new modifications are <i>not</i> staged. You must run <b>git add</b> again to stage the very latest version.<br><br>Using <b>git add .</b> or <b>git add -A</b> can inadvertently stage unwanted files (e.g., build artifacts, temporary files) if they are not properly listed in a <i>.gitignore</i> file.


title: THE STAGING AREA (INDEX)
content:
The <i>staging area</i>, or <i>index</i>, is a crucial intermediate layer between your working directory and your Git repository. <b>git add</b> populates this area, allowing you to prepare a snapshot of your project's state. This separation enables developers to make numerous changes in their working directory, but only commit specific, related modifications, fostering cleaner and more manageable commit histories.


title: ADDING DELETED FILES
content:
While <b>git rm</b> is commonly used to remove files from both the working directory and the index, <b>git add -u</b> or <b>git add -A</b> can also stage the deletion of files you've manually removed from your working directory. Git detects the absence of a tracked file and stages its removal, ready for the next commit.


title: HISTORY
content:
The concept of a <i>staging area</i> or <i>index</i> is a cornerstone of Git's design, introduced by Linus Torvalds with the initial release of Git in 2005. <b>git add</b> has been integral to this design from the beginning, allowing developers to carefully curate the content of each commit. Features like interactive patch mode (<b>-p</b>) were added later to enhance this control, making <b>git add</b> a continuously evolving and powerful tool within the Git ecosystem.


title: SYNOPSIS
content:
git am [<options>] [<Maildir> | <mbox>...]<br>git am [<options>] &lt; &lt;patch-file&gt;<br>git am --abort | --continue | --skip | --show-current-patch


title: PARAMETERS
content:
<b>--abort</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Stop the current patch application operation and revert to the state before <B>git am</B> began.</I><br><br><b>--continue</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Resume the patch application sequence after resolving conflicts or applying changes manually.</I><br><br><b>--skip</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Skip the current patch that failed to apply and proceed to the next one in the sequence.</I><br><br><b>--show-current-patch</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Display the patch currently being applied or that caused a conflict during the process.</I><br><br><b>--signoff / -s</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Add a <B>Signed-off-by:</B> line by the committer at the end of the commit message, indicating approval.</I><br><br><b>--keep-cr</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Preserve carriage returns (CR) at the end of lines when applying the patch, which can be useful for Windows-generated patches.</I><br><br><b>--3way</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Attempt a 3-way merge if a patch does not apply cleanly. This requires the original blob that the patch was created against to be available.</I><br><br><b>--reject</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>When a patch does not apply cleanly, output a <B>.rej</B> file containing the rejected hunks instead of halting, and continue with subsequent patches.</I><br><br><b>-p&lt;n&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Remove <B>n</B> leading path components from the patch file names. For example, <B>-p1</B> to strip the first directory level.</I><br><br><b>--whitespace=&lt;option&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Specify how to handle whitespace errors. Common options include <B>nowarn</B>, <B>warn</B>, <B>fix</B>, or <B>error</B>.</I><br><br><b>&lt;Maildir&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Path to a Maildir directory containing email messages, each potentially a patch to be applied.</I><br><br><b>&lt;mbox&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Path to an mbox file containing email messages, each potentially a patch to be applied.</I><br><br><b>Standard input (&lt; &lt;patch-file&gt;)</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Apply a single patch read from standard input, typically redirected from a file containing the patch content.</I><br><br>


title: DESCRIPTION
content:
<B>git am</B> is a powerful command used to apply a series of patches, typically received via email, onto a Git repository. It can consume patches from standard input, an <I>mbox</I> file, or a <I>Maildir</I> directory.<br>Unlike <I>git apply</I>, <I>git am</I> goes beyond just modifying files; it creates new commits for each patch, preserving author information, commit messages, and other metadata from the original email. This makes it ideal for integrating contributions from mailing lists, such as in open-source projects like the Linux kernel.<br>It intelligently parses common email headers (e.g., <I>From</I>, <I>Subject</I>, <I>Date</I>) to reconstruct accurate commit details. In case of conflicts, <B>git am</B> will pause, allowing for manual resolution, and provides options to continue, abort, or skip patches, ensuring a controlled application process for multi-patch series.


title: CAVEATS
content:
The working directory and index must be clean before starting <B>git am</B>, or it will typically error out, unless conflicts are pre-existing from a previous failed <B>am</B> operation.<br>Manual intervention is required to resolve merge conflicts; <B>git am</B> will pause until conflicts are resolved by the user.<br>While <B>git am</B> is robust, patches not generated by <B>git format-patch</B> (e.g., plain diffs from other tools, or improperly formatted email) might require additional options or manual adjustments for successful application.


title: TYPICAL WORKFLOW WITH GIT AM
content:
<I>A common workflow involves saving an email containing a patch (or multiple patches) into an mbox file or redirecting a single patch file to standard input. For instance, to apply patches from a file named <B>patches.mbox</B>, one would run <B>git am patches.mbox</B>.<br>If a patch fails to apply cleanly due to conflicts, <B>git am</B> will stop, allowing you to manually resolve the conflicts using <B>git mergetool</B> or direct file editing. After resolution, you stage the resolved files with <B>git add</B> and then run <B>git am --continue</B> to complete the commit and proceed with the next patch.<br>If a patch is deemed unapplicable or unwanted, <B>git am --skip</B> can be used to discard it and move on, or <B>git am --abort</B> to revert the entire operation, cleaning up any partially applied patches.</I>


title: PATCH FORMATS & HEADER PARSING
content:
<I><B>git am</B> is specifically designed to understand various patch formats, primarily those generated by <B>git format-patch</B>, which include Git-specific metadata within the patch file itself. It intelligently parses email headers like <B>From:</B>, <B>Subject:</B>, <B>Date:</B>, <B>Message-ID:</B>, <B>Commit:</B>, <B>Author:</B>, and <B>Date:</B> to construct the commit message and set the correct author and committer information for the new commits.<br>This attention to detail ensures that the history created by <B>git am</B> accurately reflects the original contribution, even when processed through intermediate email systems, making it a reliable tool for maintaining historical integrity.</I>


title: HISTORY
content:
The <I>git-am</I> command has been a fundamental part of Git since its early development, reflecting its origins in the Linux kernel community's mailing list-centric workflow. It was designed to automate the process of applying email-borne patches, a common method of collaboration before distributed version control systems became widespread.<br>Its robustness in handling various email and patch formats, combined with its ability to reconstruct commit metadata, has made it an enduring and essential tool for integrating contributions from diverse sources in projects that rely on email-based patch submissions.


title: SYNOPSIS
content:
<b>git-annex</b> <I>command</I> [<I>options</I>] [<I>arguments</I>]<br><br>Common commands:<br><b>git-annex init</b><br><b>git-annex add</b> <I>file</I>...<br><b>git-annex get</b> <I>file</I>...<br><b>git-annex drop</b> <I>file</I>...<br><b>git-annex sync</b>


title: PARAMETERS
content:
<b>init</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Initializes a <i>git-annex</i> repository. This converts a Git repository into a <i>git-annex</i> enabled one, setting up the necessary internal structures.<br><br><b>add <file>...</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Adds specified files to the annex. Instead of adding content to Git, it moves the content to the annex and places a symlink (or pointer file) in the Git repository.<br><br><b>get <file>...</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Retrieves the content of annexed files from one of the available locations (e.g., another repository, a configured remote, or a cloud backend) to the local repository.<br><br><b>drop <file>...</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Removes the local content of annexed files, freeing up local disk space. The content remains available in other configured locations or remotes. This is safe as long as the content exists elsewhere.<br><br><b>sync</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Synchronizes changes between the local <i>git-annex</i> repository and its remotes. This includes both Git tree changes and information about annexed file content availability.<br><br><b>whereis <file>...</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows which repositories or locations store the content for specified annexed files, helping to understand data distribution.<br><br><b>fsck</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Checks the integrity of the annexed content, ensuring that all files are present and their hashes match, optionally repairing issues or checking for duplicate content.<br><br><b>info</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays detailed information about the <i>git-annex</i> repository, including statistics about annexed files, storage sizes, and configured remotes.<br><br>


title: DESCRIPTION
content:
<i>git-annex</i> extends Git to manage large files and data without storing their content directly within the Git repository. It achieves this by storing the actual file content in a separate 'annex' and placing symlinks (or special pointers on platforms without robust symlink support) in the Git repository. This allows Git to track the <i>metadata</i> (filenames, permissions, version history) of these files, while <i>git-annex</i> handles the storage, distribution, and integrity of their potentially massive content.<br><br>It supports various storage backends, including local directories, network drives, and cloud storage providers. Key features include content-addressing (files are identified by their cryptographic hash, ensuring integrity), distributed availability (content can be stored in multiple locations), and efficient synchronization. <i>git-annex</i> is particularly valuable for projects involving large datasets, media files, or binaries, where storing raw content in Git would be impractical or impossible, enabling collaborative work on large file collections.


title: CAVEATS
content:
While powerful, <i>git-annex</i> introduces a new layer of complexity compared to plain Git. Users must understand the distinction between Git tracking metadata and <i>git-annex</i> managing content. <br>Direct modification of annexed files can lead to detached content or unexpected behavior; changes should typically be made by 'unlocking' the file, editing, and then 'adding' (or 'locking') again. <br>Cross-platform symlink support (especially on Windows) can sometimes be challenging, though <i>git-annex</i> offers alternative mechanisms for these environments. <br>Managing available disk space and ensuring content is available when needed requires careful planning and use of commands like <b>git-annex get</b> and <b>git-annex drop</b>.


title: HOW IT WORKS
content:
<i>git-annex</i> replaces large files in your Git repository with symlinks (or special 'pointer' files on some systems). These symlinks point to the actual file content, which is stored in a hidden directory (the 'annex') alongside your Git repository. The file content itself is identified by its cryptographic hash (e.g., SHA256), ensuring integrity and content-addressing. When you 'add' a file, its content is moved to the annex, and a symlink is created. When you 'get' a file, <i>git-annex</i> ensures its content is present locally by fetching it from a known location. This allows Git to track only the small symlink, making large repositories fast and efficient, while <i>git-annex</i> manages the heavy lifting of data storage and retrieval across multiple locations.


title: COMMON USE CASES
content:
<i>git-annex</i> is ideal for:<br><b>Scientific Data:</b> Managing large experimental results, simulations, or datasets in research projects.<br><b>Media Production:</b> Versioning large video, audio, or image files in collaborative environments.<br><b>Archiving:</b> Creating distributed, integrity-checked archives of large collections of documents or historical data.<br><b>Software Development:</b> Handling large binaries, dependencies, or build artifacts that don't belong in the main Git repository.<br><b>Distributed Collaboration:</b> Sharing large datasets among geographically dispersed teams without relying on a single central server for content.<br>


title: HISTORY
content:
<i>git-annex</i> was created by Joey Hess in 2010 to address Git's inherent limitations with large files. Git is optimized for tracking changes in text files and performs poorly with large binary blobs, as it copies the entire file for each revision. Hess envisioned a system that could leverage Git's distributed metadata tracking capabilities while outsourcing the content storage. The project has seen continuous development, evolving to support various storage backends and advanced features like distributed content availability and integrity checking, becoming a crucial tool for data management in scientific research, archiving, and media production.


title: PARAMETERS
content:
<b>-L <I>start</I>,<I>end</I> or -L <I>function</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Limit the blame to a specific line range or function within the file.<br><br><b>--porcelain (-p)</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Output the blame information in a machine-readable format, suitable for scripting.<br><br><b>--whitespace (-w)</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Ignore whitespace changes when attributing lines, focusing on semantic changes.<br><br><b>--move (-M[<I>num</I>])</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Detect moved or copied lines within the same file and attribute them correctly.<br><br><b>--copy (-C[<I>num</I>])</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Detect moved or copied lines from other files in the same commit.<br><br><b>--root</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Do not stop at the first revision, but trace blame across the entire history to the root commit.<br><br><b>--reverse</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Walk history backwards from the current revision, showing what was removed.<br><br><b><I>revision</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Start blaming from this specific commit ID or reference instead of HEAD.<br><br><b><I>file</I>...</b><br>&nbsp;&nbsp;&nbsp;&nbsp;The path to the file(s) for which to perform the annotation (blame) operation.<br><br><b>--since=<I>date</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show only commits after a specific date, filtering the blame history.<br><br><b>--until=<I>date</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show only commits before a specific date, filtering the blame history.<br><br>


title: DESCRIPTION
content:
The <I>git-annotate</I> command, essentially an alias for <I>git-blame</I>, displays the author and commit information for each line of a given file. It traces the history of each line, showing when and by whom it was last modified, aiding in understanding code evolution, debugging, and identifying the origin of specific code segments. This tool is invaluable for code archaeologists and developers trying to understand why a particular line exists or was changed.<br><br>It can be configured to ignore whitespace changes, detect moved or copied lines within or across files, and restrict the analysis to specific line ranges or commit revisions. By providing a detailed lineage for each line of code, <I>git-annotate</I> helps pinpoint responsibilities and provides context for code review and maintenance tasks, offering a granular view into the project's commit history.


title: CAVEATS
content:
The <I>git-annotate</I> command is largely an alias for <I>git-blame</I>; most modern Git documentation and discussions refer to <I>git-blame</I>. It attributes lines to the <I>last</I> commit that modified them, not necessarily the <I>original</I> commit that introduced them, unless options like <I>--root</I> are used. It's not designed to show all historical changes to a line, but rather its current state's lineage.


title: IGNORING REVISIONS
content:
You can configure <I>git-blame</I> (and thus <I>git-annotate</I>) to ignore specific commits, such as mass reformatting or automated changes, when attributing lines. This is done by setting the <I>blame.ignoreRevsFile</I> configuration option or by using the <I>--ignore-revs-file</I> command-line option, pointing to a file containing a list of commit hashes to ignore.


title: HISTORY
content:
<I>git-annotate</I> has been a part of Git since its early days, often serving as a direct alias or precursor to the more commonly known <I>git-blame</I> command. Both commands provide the same core line-by-line authorship tracking functionality. The naming convention likely evolved, with <I>git-blame</I> becoming the predominant and more semantically descriptive term for its function.


title: PARAMETERS
content:
<b><b>-p&lt;num&gt;</b>, <b>--strip=&lt;num&gt;</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Strip the first <b>&lt;num&gt;</b> leading path components from file names in the patch.<br><br><b><b>-R</b>, <b>--reverse</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Apply the patch in reverse, effectively reverting the changes.<br><br><b><b>--cached</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Apply the patch directly to the Git index (staging area) without modifying the working tree. This prepares the changes for a commit without touching your local files.<br><br><b><b>--index</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Apply the patch to both the working tree and the index. This is useful when the patch involves modifications to files that are already staged.<br><br><b><b>--check</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Don't apply the patch; instead, check if it can be applied cleanly. This is useful for verifying patch compatibility before actual application.<br><br><b><b>--stat</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show a diffstat (summary of changes) instead of applying the patch. Similar to the output of <i>git diff --stat</i>.<br><br><b><b>--numstat</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Similar to <b>--stat</b>, but shows number of added and deleted lines for each file, and paths without truncation.<br><br><b><b>--summary</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Output a brief summary of what happened, including creations, deletions, and modifications.<br><br><b><b>--whitespace=(nowarn|warn|fix|error|error-all)</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Define how to handle whitespace errors. Options range from ignoring (<b>nowarn</b>) to fixing (<b>fix</b>) or aborting on errors (<b>error</b>).<br><br><b><b>--reject</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;When a patch does not apply cleanly, instead of exiting with an error, create <b>.rej</b> files for the rejected hunks. This allows manual conflict resolution.<br><br><b><b>--directory=&lt;dir&gt;</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prepend <b>&lt;dir&gt;</b> to all file names in the patch. Useful if the patch was generated from a different subdirectory.<br><br><b><b>--verbose</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Report progress and details on stderr during the application process.<br><br><b><b>--3way</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;When the patch does not apply cleanly, attempt a 3-way merge. This requires the original blob that the patch was based on to be available in the repository.<br><br><b><b>--binary</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Allows applying a diff that contains binary changes. Without this, binary diffs are treated as errors.<br><br>


title: DESCRIPTION
content:
<i>git-apply</i> reads a patch in <i>diff -u</i> or Git <i>diff</i> format and applies it to the files in the working tree, or directly to the Git index. It's a lower-level command compared to <i>git am</i>, as it doesn't handle commit metadata, email headers, or prepare a commit message; it solely focuses on applying the textual changes.<br><br>This makes it suitable for applying simple patches downloaded from the web, or patches generated by <i>git diff</i> that don't need to be imported as full commits with author/committer information. <i>git-apply</i> is efficient and understands Git's internal diff formats, including new/old file modes, and binary diffs when explicitly handled. It provides options for stripping path components, reversing patches, and checking for apply errors without modifying files.


title: CAVEATS
content:
<i>git-apply</i> only applies patches; it does not automatically create commits or record the changes in the repository's history. This must be done manually with <i>git add</i> and <i>git commit</i> after a successful application. It lacks the advanced mailbox parsing and commit attribution features of <i>git am</i>.<br><br>For complex patch series or patches with full commit metadata (e.g., from <i>git format-patch</i>), <i>git am</i> is generally the more appropriate tool. <i>git-apply</i> may struggle with patches that have significant context mismatches or have been modified manually, requiring careful use of options like <b>--3way</b> or manual conflict resolution.


title: PATCH INPUT
content:
<i>git-apply</i> expects patches to be provided either as arguments (file paths) or piped to standard input. When multiple patch files are provided, they are applied sequentially.


title: APPLYING TO INDEX VS. WORKING TREE
content:
By default, <i>git-apply</i> modifies files in the working tree. The <b>--cached</b> option allows applying changes directly to the Git index (staging area) without touching the working tree, which is useful for preparing a commit without local file modifications. The <b>--index</b> option applies to both.


title: HISTORY
content:
<i>git-apply</i> has been a fundamental part of Git since its early days, serving as the core mechanism for applying diffs. Its design is influenced by the traditional Unix <i>patch(1)</i> utility, but it specifically understands Git's extended diff formats, including file modes, renames, and binary diffs (with the <b>--binary</b> option). Over time, options have been added to handle various patch scenarios, such as <b>--3way</b> for merge-style conflict resolution and <b>--cached</b> for applying directly to the index.


title: SYNOPSIS
content:
<b>git archive</b> [--format=<i>&lt;fmt&gt;</i>] [--output=<i>&lt;file&gt;</i>] [--prefix=<i>&lt;prefix&gt;</i>/] <i>&lt;tree-ish&gt;</i> [<i>&lt;path&gt;</i>...]<br><b>git archive</b> --remote=<i>&lt;repo&gt;</i> [options] <i>&lt;tree-ish&gt;</i> [<i>&lt;path&gt;</i>...]


title: PARAMETERS
content:
<b><i>&lt;tree-ish&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The commit, tag, or branch from which to create the archive. For example, <i>HEAD</i>, <i>main</i>, or a specific commit SHA.<br><br><b>[<i>&lt;path&gt;</i>...]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Optional pathspecs to limit the archive to specific files or directories within the <i>&lt;tree-ish&gt;</i>.<br><br><b><b>--format</b>=<i>&lt;fmt&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the archive format. Common formats include <i>tar</i>, <i>zip</i>, and <i>tar.gz</i> (or <i>tgz</i>). Use <b>--list</b> to see all supported formats.<br><br><b><b>--output</b>=<i>&lt;file&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Writes the archive to the specified <i>&lt;file&gt;</i> instead of standard output. The format can often be inferred from the file extension.<br><br><b><b>--prefix</b>=<i>&lt;prefix&gt;</i>/</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prepends <i>&lt;prefix&gt;</i>/ to each file path within the archive, useful for creating clean distribution packages.<br><br><b><b>--remote</b>=<i>&lt;repo&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Retrieves the archive from a remote repository instead of the local one, allowing generation without cloning the entire repository.<br><br><b><b>--list</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Lists the archive formats supported by the current Git build and exits.<br><br>


title: DESCRIPTION
content:
<i>git-archive</i> creates a compressed archive (typically tar or zip) of a specified Git tree, such as a branch, tag, or commit ID. It writes the resulting archive to standard output, making it easy to pipe to a file or another command. This command is particularly useful for generating distribution packages or snapshots of a project without including the entire <i>.git</i> directory.<br><br>By default, <i>git-archive</i> creates a tar archive, but users can explicitly choose between <i>tar</i>, <i>zip</i>, or <i>tar.gz</i> (among others, depending on configuration) using the <b>--format</b> option. If an output filename is provided via <b>--output</b>, the format can often be inferred from the extension.<br><br>When archiving the <i>HEAD</i> commit without specific pathspecs, <i>git-archive</i> intelligently excludes common build artifacts, editor backups, and temporary files, resulting in a cleaner, user-ready distribution. The <b>--prefix</b> option allows for all files within the archive to be placed under a specified directory, which is beneficial for creating well-structured release archives. It's an efficient way to export a clean snapshot of a repository's contents.


title: CAVEATS
content:
One important caveat is the interaction between <i>HEAD</i> (or current worktree), pathspecs, and file exclusion. When archiving <i>HEAD</i> without explicit pathspecs, <i>git-archive</i> automatically excludes common build artifacts, editor backups, and temporary files. However, if any <i>&lt;path&gt;</i> arguments are provided, this automatic exclusion behavior is disabled, and all files matching the pathspec will be included, regardless of their usual excluded status. Users should be aware of this to avoid unintentionally including unwanted files. Additionally, <i>git-archive</i> specifically excludes the entire <i>.git</i> directory, ensuring that only the project's content is archived.


title: EXCLUSION BEHAVIOR
content:
When archiving the <i>HEAD</i> commit (or a commit pointing to the current worktree) without specifying any <i>&lt;path&gt;</i> arguments, <i>git-archive</i> automatically excludes files that are typically not relevant for distribution, such as build products (e.g., <i>*.o</i>, <i>*.so</i>), editor backup files (e.g., <i>*~</i>, <i>*#</i>), and other temporary files. This intelligent exclusion helps create cleaner distribution packages. This behavior can be influenced by configuration settings (e.g., <i>archive.exclude</i>) and <i>.gitattributes</i> files within the repository.


title: HISTORY
content:
<i>git-archive</i> has been a core utility in Git since its early days, introduced around version 1.5.0. Its primary purpose has always been to provide a clean, distributable snapshot of a Git repository's contents, without including the entire <i>.git</i> directory. While its fundamental functionality has remained stable, subsequent Git versions have introduced enhancements such as the <i>--remote</i> option, allowing direct archiving from remote repositories, which is particularly useful for CI/CD pipelines and automated releases.


title: SYNOPSIS
content:
<i>git-archive-file</i> <i>&lt;tree-ish&gt;</i> [<i>&lt;path&gt;</i>...]<br>(Typically invoked by <b>git archive --exec=&lt;script&gt;</b>)


title: PARAMETERS
content:
<b>tree-ish</b><br>&nbsp;&nbsp;&nbsp;&nbsp;A Git object name (e.g., commit SHA, tag name, branch name) that refers to a tree object from which the archive content should be sourced. This specifies the exact version of the repository content.<br><br><b>path...</b><br>&nbsp;&nbsp;&nbsp;&nbsp;One or more optional paths within the specified <i>tree-ish</i> to be included in the archive. If no paths are given, the entire content of the <i>tree-ish</i> is archived. Paths are relative to the repository root.<br><br>


title: DESCRIPTION
content:
<br><i>git-archive-file</i> is not a standalone command intended for direct user invocation. Instead, it serves as an internal helper script, typically invoked by the <b>git archive</b> command when a custom archive format is specified using the <b>--exec</b> option. Its primary purpose is to generate the archive content for a given tree-ish and a set of paths within the Git repository.<br><br>When <b>git archive</b> calls an external program (like <i>git-archive-file</i>), it passes the tree-ish and the paths of the files to be archived as command-line arguments to the script. The script is then responsible for reading these files from the Git object database and writing the resulting archive (e.g., a tarball, zip file, or a custom format) to its standard output. This mechanism allows users or developers to create highly customized archive formats beyond the built-in <b>tar</b> or <b>zip</b> options provided by <b>git archive</b>.


title: CAVEATS
content:
This command is <i>not</i> intended for direct user invocation. It's an internal mechanism used by <b>git archive</b>.<br><br>There is no official man page for <i>git-archive-file</i> as it's typically a conceptual or example script rather than a fixed binary command. Its exact behavior depends on the specific implementation of the script being executed.<br><br>The <b>git archive</b> command passes only <i>tree-ish</i> and <i>path</i> arguments. Any custom options or configuration must be handled by the external script itself or via environment variables.


title: CUSTOM ARCHIVE FORMATS WITH <B>GIT ARCHIVE --EXEC</B>
content:
The <b>git archive</b> command's <b>--exec=&lt;program&gt;</b> option allows an external program to generate the archive. When this option is used, <b>git archive</b> invokes the specified <b>&lt;program&gt;</b> and pipes its standard output to the final archive file. The <b>&lt;program&gt;</b> receives the <i>tree-ish</i> and path arguments as command-line parameters. This mechanism enables users to implement custom compression, encryption, or entirely new archive formats that are not natively supported by <b>git archive</b>. <i>git-archive-file</i> represents such a program.


title: HISTORY
content:
The <b>--exec</b> option for <b>git archive</b> was introduced to provide flexibility for custom archive formats, allowing external scripts to generate the output. <i>git-archive-file</i> is often used as a conceptual name or an example implementation for such a script, demonstrating how <b>git archive</b> can delegate the archiving process to an external program. This feature enhances Git's extensibility for specialized archiving needs.


title: PARAMETERS
content:
<b><I>--format=&lt;format&gt;</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Controls the output format of each author. Common formats might include 'name only', 'name and email', or custom patterns.<br><br><b><I>--output=&lt;file&gt;</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies an output file to write the authors list to, instead of standard output.<br><br><b><I>--sort=&lt;key&gt;</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sorts the authors list by a specified key (e.g., by name, by commit count). Available keys depend on the script.<br><br><b><I>&lt;commit-range&gt;</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Limits the commits from which to extract authors (e.g., <I>HEAD~10..HEAD</I> or <I>v1.0..</I>).<br><br>


title: DESCRIPTION
content:
The <I>git-authors</I> command, typically implemented as a custom script or part of a Git extension suite (e.g., <I>git-extras</I>), is designed to extract a list of unique authors from a Git repository's commit history.<br><br>Its primary use is to generate an <I>AUTHORS</I> file or a similar compilation of contributors, often displaying their names and email addresses. It works by parsing the output of <B>git log</B> to identify unique author entries. While not a core Git command, it's a widely adopted utility for maintaining a clear record of who has contributed to a project. The specific output format and available options can vary based on the script's implementation, but the core functionality remains consistent: providing a clean, deduplicated list of all commit authors.


title: CAVEATS
content:
<B>git-authors</B> is <I>not</I> a standard command shipped with Git itself. Its availability and behavior depend entirely on whether a specific script or Git extension (like <I>git-extras</I>) is installed and configured in your environment.<br><br>Implementations can vary significantly, leading to different options, output formats, and features.<br><br>It typically relies on parsing <B>git log</B> output, meaning it may not automatically handle <I>Co-authored-by:</I> lines in commit messages unless the specific script is designed to do so.<br><br>Requires a Git repository to be initialized and have commit history.


title: ACHIEVING SIMILAR RESULTS WITHOUT <I>GIT-AUTHORS</I>
content:
Many of the functionalities of <B>git-authors</B> can be replicated using core Git commands:<br>To get a list of unique authors with their names and emails:<br><B>git log --format='%aN &lt;%aE&gt;' | sort -uf</B><br><br>To get a shortlog summary with commit counts:<br><B>git shortlog -sn --all</B><br><br>These commands demonstrate the underlying Git functionality that <B>git-authors</B> scripts often leverage.


title: HISTORY
content:
<B>git-authors</B> is a community-driven utility rather than an official Git command. It emerged from the need to easily generate a list of contributors for projects, particularly for <I>AUTHORS</I> files. Various implementations exist, often as shell scripts or part of larger Git utility collections like <I>git-extras</I>, reflecting a common pattern of extending Git's core functionality with user-contributed scripts. Its development is decentralized, focusing on practical use cases for project documentation.


title: PARAMETERS
content:
<b>start</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Initiates a new bisect session. You typically follow this by marking a known bad commit and a known good commit to define the search range.<br><br><b>bad [&lt;<i>commit</i>&gt;]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Marks the current or specified commit as 'bad' (i.e., containing the bug). This is often your starting point (e.g., HEAD).<br><br><b>good [&lt;<i>commit</i>&gt;]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Marks the current or specified commit as 'good' (i.e., not containing the bug). This should be a commit known to be stable or bug-free.<br><br><b>reset [&lt;<i>commit</i>&gt;]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Resets the bisect session, returning your repository to the branch that was checked out before <i>git bisect start</i>. Optionally checks out a specific commit after resetting.<br><br><b>skip &lt;<i>commit</i>&gt;...</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Marks one or more commits as untestable (e.g., due to build failures or unrelated issues) and excludes them from the search. Git will then pick another commit.<br><br><b>run &lt;<i>command</i>&gt;...</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Automates the bisect process by executing a specified script or command for each chosen commit. The script's exit code determines if the commit is good (0), bad (1-127, except 125), or skip (125).<br><br><b>log</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays the bisect log, showing the sequence of good/bad/skip marks and the current state of the bisect.<br><br><b>view / visualize</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Launches <i>gitk</i> (if available) to visually represent the bisect history, or shows a text-based log if <i>gitk</i> is not found.<br><br>


title: DESCRIPTION
content:
<i>git bisect</i> is a powerful debugging tool that uses a binary search algorithm to efficiently find the commit that introduced a regression or bug, or when a feature was added. By iteratively narrowing down the range between a known <b>good</b> commit (where the bug did not exist) and a known <b>bad</b> commit (where the bug exists), it drastically reduces the search space. The user is prompted to test a commit and mark it as "good" or "bad" (or "skip" if untestable), and <i>git bisect</i> automatically selects the next commit to test. This process continues until the exact culprit commit is identified, significantly reducing the time spent manually checking history.


title: CAVEATS
content:
The effectiveness of <i>git bisect</i> relies on a clear definition of 'good' and 'bad' states. Automated 'run' requires a robust test script that exits with specific codes. The process can be complicated by very messy or complex merge histories. Skipping too many commits can reduce efficiency or inadvertently obscure the true culprit.


title: HOW IT WORKS
content:
<i>git bisect</i> operates on a binary search principle. You initiate the process by providing a known <b>bad</b> commit (where the bug exists) and a known <b>good</b> commit (where the bug is absent). Git then checks out a commit roughly halfway between the good and bad commits. You test this checked-out code and inform Git whether it's <b>good</b> or <b>bad</b>. Based on your input, Git halves the remaining search space and checks out another middle commit. This iterative process continues until only one commit remains, which is then identified as the first <b>bad</b> commit (the one that introduced the bug).


title: TYPICAL MANUAL WORKFLOW
content:
1.  <b><I>git bisect start</I></b><br>    Start the bisect session.<br><br>2.  <b><I>git bisect bad &lt;bad_commit_hash_or_ref&gt;</I></b><br>    Tell Git the commit where the bug definitely exists (e.g., your current <i>HEAD</i> or a release where the bug is present).<br><br>3.  <b><I>git bisect good &lt;good_commit_hash_or_ref&gt;</I></b><br>    Tell Git a commit where the bug definitely did not exist (e.g., an older release tag or a known stable point).<br><br>4.  Git checks out an intermediate commit. Test the code at this commit to see if the bug is present.<br><br>5.  If the bug is present: <b><I>git bisect bad</I></b><br>    If the bug is <i>not</i> present: <b><I>git bisect good</I></b><br>    Repeat steps 4-5 until Git identifies the culprit commit.<br><br>6.  After the culprit is found and reported: <b><I>git bisect reset</I></b><br>    Exit the bisect session and return to your original branch.


title: HISTORY
content:
<i>git bisect</i> has been a core utility within Git since its early development. It leverages Git's fundamental commit graph and history tracking capabilities to provide an efficient and powerful debugging workflow. Its inclusion from early on signifies its importance in practical software development and maintenance, demonstrating Git's capabilities beyond mere version control.


title: PARAMETERS
content:
<b><i>&lt;file&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The path to the file whose history is to be analyzed.<br><br><b><i>&lt;revision&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;An optional commit or revision to start blaming from. If omitted, defaults to <i>HEAD</i>.<br><br><b><b>-L</b> <i>&lt;start&gt;,&lt;end&gt;</i> | <b>-L</b> <i>:&lt;funcname&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Blame only the specified line range. This can be a numerical range (e.g., <i>10,20</i>) or a function name (e.g., <i>:my_function</i>).<br><br><b><b>-M</b>[<i>&lt;num&gt;</i>]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Detect moved or copied lines within the same file. <i>&lt;num&gt;</i> specifies the minimum number of alphanumeric characters that must match for a line to be considered a copy/move.<br><br><b><b>-C</b>[<i>&lt;num&gt;</i>]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Detect lines moved or copied from other files in the same commit. Using <b>-CC</b> or <b>-CCC</b> extends detection to different commits or files in unrelated histories, respectively.<br><br><b><b>-p</b> | <b>--porcelain</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Output in a machine-readable format, providing more detailed information per line, including the original commit, author, committer, and various SHA-1s.<br><br><b><b>-s</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Suppress the author name and timestamp from the output, showing only the commit SHA-1 and the line content.<br><br><b><b>--reverse</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Walk history forward instead of backward, showing the revision that introduced a change and then tracing its future modifications. Useful for understanding how a line evolved.<br><br><b><b>-b</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show a blank SHA-1 (<i>0000000000000000000000000000000000000000</i>) for the original commit of a line if it was introduced by a commit that cannot be found (e.g., due to a shallow clone).<br><br>


title: DESCRIPTION
content:
The <i>git-blame</i> command is a powerful Git utility used to display revision and author information for each line of a given file. It annotates every line with details about the commit that last modified it, including the commit hash, author's name, timestamp, and the original line number from that commit. This functionality is invaluable for understanding the history of a codebase, identifying when and by whom specific lines of code were introduced or changed. It helps in debugging, refactoring, and performing code archaeology by tracing the evolution of individual lines. <i>git-blame</i> can traverse backwards through the commit history, offering options to filter by line range, detect moved or copied lines, or customize the output format for machine parsing.


title: CAVEATS
content:
While powerful, <i>git-blame</i> has limitations. It indicates <i>who</i> and <i>when</i> a line was last changed, not necessarily <i>why</i>. Significant refactoring or reformatting of code without actual content changes can sometimes lead to misleading blame information. It also doesn't inherently track lines across file renames perfectly without explicit options like <b>-C</b>. For very large files or deep histories, running <i>git-blame</i> without specifying a start revision or line range can be computationally intensive.


title: DEFAULT OUTPUT FORMAT
content:
By default, <i>git-blame</i> outputs each line prefixed with the commit SHA-1, the original line number, the final line number, the author's name, the timestamp, and then the content of the line itself. For example: <br><code>^fa6b1234 (Author Name 2023-10-26 10:30:45 +0100 10) import os<br></code><br>The <b>^</b> indicates the initial commit for that line in the file.


title: PERFORMANCE CONSIDERATIONS
content:
For better performance on large repositories or files with extensive history, consider using the <b>-L</b> option to narrow down the line range you are interested in. Additionally, specifying a starting <i>&lt;revision&gt;</i> can significantly reduce the amount of history <i>git-blame</i> needs to traverse, making the command faster.


title: HISTORY
content:
The <i>git-blame</i> command has been a core utility in Git since its inception by Linus Torvalds in 2005. Its design was influenced by similar 'annotate' or 'blame' features found in older version control systems like CVS and SVN, which served to identify the origin of lines of code. Linus himself emphasized the importance of being able to efficiently trace the history of individual lines. The command quickly became indispensable for developers needing to understand code origins, debug issues, and manage complex codebases, evolving alongside Git's capabilities to include sophisticated options for detecting moved and copied code.


title: SYNOPSIS
content:
Since <i>git-blame-someone-else</i> is typically a custom alias or script and not a standard command, its exact syntax varies. Conceptually, it might look like:<br><br><code>git blame-someone-else &lt;commit-range&gt; &lt;new-author-name&gt; &lt;new-author-email&gt;</code><br><br>Or simply a predefined alias like:<br><br><code>git blame-someone-else</code> (which executes a complex history rewrite internally).


