# CommandSection

title: DESCRIPTION
content:
<i>The <b>git-feature</b> command is not a standard, built-in command provided by Git itself. Instead, it typically refers to a custom script or Git alias created by users or third-party tools to streamline common operations related to feature branch workflows. Its purpose is to encapsulate a series of Git commands into simpler, higher-level actions, making it easier for developers to manage feature branches from creation to integration.<br><br>Common functionalities often include starting a new feature branch, finishing a feature (merging/rebasing and deleting the branch), publishing a local feature branch to a remote, or pulling updates from a main development branch into an ongoing feature. The exact behavior, available subcommands, and options depend entirely on the specific implementation of the <b>git-feature</b> script being used.</i>


title: CAVEATS
content:
<i>The most significant caveat is that <b>git-feature</b> is <b>not a built-in Git command</b>. Its existence and behavior are entirely dependent on whether a user or system administrator has created a script or alias with this name. Therefore, if you try to use <b>git feature</b> on a system where it hasn't been set up, it will result in an error or an 'unknown command' message. Users must either create their own <b>git-feature</b> script or use a third-party workflow tool that provides such functionality.</i>


title: <I>TYPICAL IMPLEMENTATIONS</I>
content:
<i>A <b>git-feature</b> script is commonly implemented as an executable file named <b>git-feature</b> placed in a directory listed in the user's PATH, or as a Git alias defined in the <b>.gitconfig</b> file. For example, an alias could be <b>feature = '!f() { git checkout -b feature/$1 develop; }; f'</b>, which would create a basic 'start' functionality. More complex versions are shell scripts that parse subcommands and arguments.</i>


title: HISTORY
content:
<i>The concept of encapsulating complex Git workflows into simpler commands gained traction with the rise of structured branching models like 'Git Flow' (introduced by Vincent Driessen in 2010). While <b>git-flow</b> became a prominent extension, many developers sought lighter, custom scripts to fit their specific needs without adopting the full <b>git-flow</b> model. The name <b>git-feature</b> emerged as a common, intuitive choice for these bespoke scripts, reflecting their primary focus on managing individual feature branches. Its 'history' is more about the evolution of Git best practices and user-contributed tooling rather than a single, formal development timeline.</i>


title: SEE ALSO
content:
git-branch(1), git-checkout(1), git-merge(1), git-rebase(1), git-flow(1) <i>(a popular Git workflow extension)</i>


title: PARAMETERS
content:
<b><b>--strict</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Performs more rigorous checks for various repository issues, ensuring higher data integrity scrutiny.<br><br><b><b>--no-dangling</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prevents the command from reporting objects that are 'dangling' (reachable but not referenced by any branch, tag, or other reference).<br><br><b><b>--no-full</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Suppresses reporting on objects that are not reachable from any of the specified <i>object-id</i>s, implicitly disabling dangling object reports.<br><br><b><b>--connectivity-only</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Limits the check to object connectivity only, skipping content validity checks for faster verification.<br><br><b><b>object-id...</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;An optional list of specific object IDs to check. If provided, the command will only verify these objects and their ancestors.<br><br>


title: DESCRIPTION
content:
<i>git-fsck-objects</i> is a low-level Git 'plumbing' command designed to verify the connectivity and validity of objects within the Git object database. It systematically checks for corrupted, missing, or inconsistent objects, ensuring the integrity of the object graph.<br><br>Unlike the higher-level <i>git fsck</i>, it focuses exclusively on the objects themselves, ignoring references, the index, or the working tree. It is frequently invoked internally by <i>git fsck</i> but can be run independently for more specific diagnostic purposes. Detected errors and warnings are reported to standard error.


title: CAVEATS
content:
This is a low-level 'plumbing' command; for general repository integrity checks, <i>git fsck</i> is recommended as it wraps this command with broader checks.<br><br>Running this command on very large repositories can be resource-intensive and time-consuming due to the thorough nature of its integrity checks.


title: HISTORY
content:
<i>git-fsck-objects</i> has been a fundamental component of Git's architecture since its early development. It underpins Git's strong guarantees of data integrity by providing the core mechanism for verifying the object database, which is crucial for the reliability and consistency of all Git operations.


title: SYNOPSIS
content:
<pre><code>git check-ignore [<I>options</I>] &lt;path&gt;...<br>git check-ignore [<I>options</I>] --stdin</code></pre>


title: PARAMETERS
content:
<b>-q, --quiet</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Suppresses output for untracked paths. Only displays paths that are actually ignored.<br><br><b>-v, --verbose</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows verbose output, including the matching ignore pattern and the path to the <I>.gitignore</I> file (or other source) that contains the rule.<br><br><b>-n, --non-matching</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows paths that are <I>not</I> ignored. Useful for listing all paths provided, highlighting which ones are not affected by ignore rules.<br><br><b>--no-index</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Ignores the Git index when checking paths. This means it treats all paths as if they were untracked, even if they are already in the index.<br><br><b>--stdin</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Reads paths from standard input, one path per line, instead of from command-line arguments.<br><br><b>--cwd=<path></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Processes paths provided as if the current working directory were <path>. Useful when running the command from a different location within a repository.<br><br><b>--</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Separates command-line options from the list of pathnames, allowing paths that might start with a hyphen to be correctly interpreted.<br><br>


title: DESCRIPTION
content:
The term "git-ignore" colloquially refers to Git's mechanism for excluding certain files or directories from version control, primarily through <I>.gitignore</I> files. While "git-ignore" is not a direct executable command, the <I>git check-ignore</I> command is its counterpart for <I>debugging</I> and <I>verifying</I> these ignore rules.<br><br> <I>git check-ignore</I> allows users to determine if specified paths are ignored by Git's configured ignore rules. These rules are sourced from multiple places, including the project-specific <I>.gitignore</I> files, the repository-local <I>.git/info/exclude</I> file, and a global exclude file configured via <I>core.excludesFile</I>.<br><br>By providing one or more file paths, <I>git check-ignore</I> outputs which paths are ignored, and with the <I>--verbose</I> option, it can show the specific pattern and source file that caused the ignore. This command is invaluable for troubleshooting when a file either <I>is</I> or <I>is not</I> being ignored as expected.


title: CAVEATS
content:
The command "git-ignore" itself is not a direct executable. This analysis focuses on <I>git check-ignore</I>, which is the primary tool for interacting with Git's ignore mechanism.<br><br><I>git check-ignore</I> does not <I>modify</I> ignore rules; it only <I>reports</I> on them. It checks if a given path is ignored, but it won't list all ignored files in a repository without providing them explicitly.


title: <B>UNDERSTANDING GIT'S EXCLUSION HIERARCHY</B>
content:
Git applies ignore rules in a specific order of precedence, with later rules potentially overriding earlier ones: <br>1. Patterns read from the <I>core.excludesfile</I> configuration (global). <br>2. Patterns read from <I>.git/info/exclude</I> (repository-specific, not version controlled). <br>3. Patterns read from <I>.gitignore</I> files in the same directory as the path, or in parent directories. Rules in a <I>.gitignore</I> file are effective for the directory it's in and all its subdirectories. <br>


title: <B><I>.GITIGNORE</I> PATTERN SYNTAX</B>
content:
<I>.gitignore</I> files use patterns similar to shell globbing. <br>Lines starting with <I>#</I> are comments.<br>Empty lines are ignored.<br>A pattern ending with a <I>/</I> matches directories only.<br>A leading <I>/</I> anchors the pattern to the root of the <I>.gitignore</I> file's directory.<br>An exclamation mark (<I>!</I>) at the beginning of a pattern negates it, re-including a previously excluded file.<br>Asterisks (<I>*</I>) match any sequence of characters. Double asterisks (<I>**</I>) have special meaning for matching across directories.


title: HISTORY
content:
The core concept of ignoring files via <I>.gitignore</I> existed very early in Git's development. However, <I>git check-ignore</I> was introduced later, in Git version 1.7.6 (released around mid-2011), specifically to address the common user difficulty in debugging why certain files were or were not being ignored. Its introduction significantly improved the clarity and diagnosability of Git's exclusion rules.


title: PARAMETERS
content:
<b>-t <tool>, --tool=<tool></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the merge tool to use. If not specified, Git will try to launch a configured default tool or one from a predefined list.<br><br><b>-y, --no-prompt</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Do not prompt before invoking the merge tool for each file. Automatically launch the tool for all conflicted files.<br><br><b>--prompt</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prompt before invoking the merge tool for each file (default behavior).<br><br><b>--tool-help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display a list of merge tools supported by your Git installation, and exit.<br><br><b>--[no-]gui</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Use the GUI version of the merge tool if available (<code>--gui</code>), or specifically avoid GUI tools (<code>--no-gui</code>).<br><br><b>--[no-]trust-exit-code</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Trust the exit code of the merge tool to determine if the resolution was successful. If <code>--no-trust-exit-code</code>, Git will always prompt for confirmation.<br><br><b>--[no-]recurse-submodules</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Recursively resolve conflicts in submodules (<code>--recurse-submodules</code>) or not (<code>--no-recurse-submodules</code>). Defaults to what <code>merge.recurseSubmodules</code> is set to.<br><br><b><file>...</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Optional path(s) to specific conflicted file(s) to resolve. If omitted, <i>git-mergetool</i> will iterate through all conflicted files.<br><br>


title: DESCRIPTION
content:
<i>git-mergetool</i> is a convenience command that helps you resolve merge conflicts by launching an appropriate visual merge tool. When a Git merge results in conflicts, Git marks the conflicted files. Instead of manually editing these files to resolve the differences, <i>git-mergetool</i> automates the process of calling an external GUI-based or terminal-based merge tool to guide you through the resolution. It iterates through each conflicted file, presenting the conflicting versions (local, remote, and common ancestor) and allowing you to interactively choose, combine, or edit the desired outcome. After you resolve a file in the tool, <i>git-mergetool</i> often prompts you to confirm resolution and removes temporary files created by the merge tool. It relies on external tools (like KDiff3, Meld, Beyond Compare, etc.) which must be installed and configured with Git.


title: CAVEATS
content:
<i>git-mergetool</i> is a wrapper that requires external merge tools to be installed on your system. It does not perform the merge logic itself but simply orchestrates the calls to these tools. <br>Proper configuration via <code>git config</code> is often necessary to ensure Git knows how to find and use your preferred merge tools. <br>Always review changes made by the merge tool before marking a conflict as resolved and committing, as automated merges can sometimes introduce unintended regressions.


title: TYPICAL WORKFLOW
content:
1. Perform a merge: <code>git merge &lt;branch&gt;</code><br>2. If conflicts occur, Git reports them. <br>3. Launch the merge tool: <code>git mergetool</code> <br>4. Resolve conflicts interactively within the external tool for each file. <br>5. After resolving a file, save changes and close the tool. <i>git-mergetool</i> will usually remove the temporary <code>*.orig</code> file and ask if the file is resolved. <br>6. Once all files are resolved, stage the changes: <code>git add .</code> (or <code>git add &lt;conflicted_file&gt;</code>). <br>7. Complete the merge commit: <code>git commit</code>.


title: CONFIGURATION
content:
You can configure <i>git-mergetool</i> behavior using <code>git config</code>:<br><ul><li><code>git config --global merge.tool &lt;toolname&gt;</code>: Sets your default merge tool.</li><li><code>git config --global mergetool.&lt;toolname&gt;.path &lt;path/to/tool&gt;</code>: Specifies the exact path to your tool if it's not in your system's PATH.</li><li><code>git config --global mergetool.&lt;toolname&gt;.cmd '&lt;command-line-template&gt;'</code>: Defines a custom command to launch the tool, using placeholders like <code>$BASE</code>, <code>$LOCAL</code>, <code>$REMOTE</code>, <code>$MERGED</code> for the respective file paths.</li><li><code>git config --global mergetool.prompt false</code>: Automatically launches tools without prompting.</li></ul>


title: SYNOPSIS
content:
<b>git p4</b> <I>command</I> [<I>options</I>] [<I>args</I>]<br><br>Common commands:<br>&nbsp;&nbsp;&nbsp;&nbsp;<b>git p4</b> clone [<I>options</I>] <I>//depot/path</I>...<br>&nbsp;&nbsp;&nbsp;&nbsp;<b>git p4</b> sync [<I>options</I>]<br>&nbsp;&nbsp;&nbsp;&nbsp;<b>git p4</b> submit [<I>options</I>] [<I>changelist</I>...]


title: PARAMETERS
content:
<b>--help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show help message and exit.<br><br><b>--version</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show program's version number and exit.<br><br><b>--detect-branches</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Attempt to detect Perforce branches automatically during clone or sync operations.<br><br><b>--nomg</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Disable Perforce Multi-Git integration if the server supports it.<br><br><b>--sync-only</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Used with 'submit'; synchronize the Git repository but do not submit changes to Perforce.<br><br><b>--preserve-empty-commits</b><br>&nbsp;&nbsp;&nbsp;&nbsp;During 'submit', preserve Git commits that result in empty changelists in Perforce.<br><br><b>--max-changes=<N></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Limit the number of Perforce changelists to import during clone or sync.<br><br><b>--branch=<branch></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify a specific Perforce branch to track (e.g., 'main', 'release').<br><br><b>--origin=<origin></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set the name of the Git remote that tracks the Perforce history; default is 'p4'.<br><br><b>--user=<user></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the Perforce user for authentication.<br><br><b>--port=<port></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the Perforce server address (e.g., 'perforce.example.com:1666').<br><br><b>--client=<client></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the Perforce client workspace name to use for operations.<br><br><b>--import-labels</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Import Perforce labels as Git tags during clone or sync.<br><br><b>--submit-labels</b><br>&nbsp;&nbsp;&nbsp;&nbsp;When submitting, import any Git tags matching Perforce label names.<br><br><b>--dry-run</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Perform all checks and preparation for submit, but do not actually submit changes to Perforce.<br><br><b>--prepare-only</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Only prepare the Perforce changelist for submission, do not submit it. Useful for manual review.<br><br><b>--auto-submit</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Automatically submit the prepared changelist to Perforce without manual confirmation.<br><br><b>--preserve-ownership</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Attempt to preserve original Git commit author and date information when submitting to Perforce.<br><br><b>--git-authors</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Use a .git-p4-authors file to map Git commit authors to Perforce users for correct attribution.<br><br><b>--debug</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enable debug output for troubleshooting.<br><br>


title: DESCRIPTION
content:
The <b>git-p4</b> command provides a robust bridge between the Git and Perforce <I>Source Code Management</I> systems. It enables developers to leverage Git's powerful local workflow and features (like branching, merging, and fast commits) while interacting with a Perforce server for centralized version control. <br><br><b>git-p4</b> allows users to import Perforce history into a Git repository, synchronize the Git repository with new changes from Perforce, and submit Git commits back to Perforce as new changelists. This is particularly useful for teams migrating from Perforce to Git, or for those who wish to use Git's distributed nature for local development while maintaining Perforce as the canonical shared repository. <br><br>It handles the mapping of Perforce changelists to Git commits and vice versa, supporting features like branch detection, label import, and author mapping.


title: CAVEATS
content:
Perforce 'streams' are not directly supported by <b>git-p4</b> and must often be managed as standard branches or through specific client views.<br><br>Complex Perforce integrations, such as those involving exclusive locks or highly customized triggers, may not translate perfectly to the Git workflow.<br><br>Unicode path encoding and large binary files can sometimes pose challenges; ensure your Perforce client and server are configured correctly for character sets and file types.<br><br>A working Perforce command-line client (`p4`) must be installed and accessible in the system's PATH.


title: CONFIGURATION
content:
Many <b>git-p4</b> behaviors can be configured via Git's configuration system, using `git config`. For instance, `git config git-p4.user <p4user>` or `git config git-p4.port <p4port>` can set default Perforce connection parameters, avoiding the need to specify them with every command invocation. Other options like `git-p4.detectBranches` can also be persisted in the Git repository's configuration.


title: AUTHOR MAPPING
content:
To ensure correct author attribution when submitting Git commits to Perforce, <b>git-p4</b> can utilize a `.git-p4-authors` file. This file maps Git author identities (name and email) to Perforce usernames. For example, a line in this file might look like: `Jane Doe <jane.doe@example.com> = janedoe_p4`. This allows maintaining proper ownership and history in Perforce.


title: HISTORY
content:
<b>git-p4</b> is a long-standing component of the Git distribution's `contrib` directory. It was developed to provide an effective bridge for organizations using Perforce to integrate with the Git workflow, or for individual developers wanting to use Git locally against a Perforce backend. Its development has focused on robustness and compatibility, adapting to new Git and Perforce features over time, making it a reliable tool for mixed SCM environments.


title: DESCRIPTION
content:
<i>git-root</i> is a utility command commonly found in community-driven Git extensions like <i>git-extras</i>, or implemented as a custom script. Its primary function is to locate and print the absolute path of the top-level directory of the current Git repository. It serves as a convenient shorthand, often encapsulating the functionality of core Git commands like <b>git rev-parse --show-toplevel</b>. When executed within any subdirectory of a Git repository, it will output the path to the repository's root, making it useful for scripting and navigation. If not within a Git repository, it typically exits with an error. While not part of Git's core distribution, its simplicity and utility have made it a popular addition for many Git users seeking quick access to the repository's base directory.


title: CAVEATS
content:
<ul><li><i>git-root</i> is <i>not</i> a standard, built-in Git command. Its availability depends on whether it's installed via a third-party package (like <i>git-extras</i>) or a custom script.</li><li>The behavior and exact implementation of <i>git-root</i> can vary if it's a custom script.</li><li>It requires being executed within a Git repository. If not, it will typically fail and exit with a non-zero status code.</li><li>For cross-platform compatibility and official Git behavior, <b>git rev-parse --show-toplevel</b> is the recommended alternative.</li></ul>


title: ALTERNATIVE METHOD
content:
The official and most robust way to find the Git repository root using core Git is <b>git rev-parse --show-toplevel</b>. This command is always available with a standard Git installation and offers more advanced parsing options if needed. <i>git-root</i> is often merely a convenient wrapper around this.


title: USAGE EXAMPLE
content:
Imagine your current directory is <i>/home/user/myproject/src/components</i>, and <i>/home/user/myproject</i> is the root of your Git repository. <br>Running <b>git root</b> from <i>/home/user/myproject/src/components</i> would output: <br><i>/home/user/myproject</i>


title: HISTORY
content:
The concept behind <i>git-root</i> likely arose from the frequent need to quickly identify the top-level directory of a Git repository, particularly in shell scripts or when manually navigating complex project structures. While <b>git rev-parse --show-toplevel</b> provided this functionality within core Git, the desire for a simpler, dedicated command led to the creation of wrapper scripts. <i>git-root</i> gained popularity as part of community-driven collections like <i>git-extras</i>, which bundles many useful, non-core Git commands. Its development reflects a common pattern in command-line tools: abstracting complex or verbose commands into simpler, more memorable aliases for user convenience and scripting efficiency.


title: PARAMETERS
content:
<b><b>--to=<address></b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the primary recipient(s) for the emails.<br><br><b><b>--cc=<address></b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify Carbon Copy (CC) recipient(s) for the emails.<br><br><b><b>--from=<address></b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the sender's email address.<br><br><b><b>--smtp-server=<host></b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the SMTP server hostname to use for sending emails.<br><br><b><b>--smtp-port=<port></b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the port number for the SMTP server.<br><br><b><b>--smtp-user=<user></b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the username for SMTP authentication.<br><br><b><b>--smtp-pass=<password></b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the password for SMTP authentication. Caution: storing passwords directly in commands or history is not recommended.<br><br><b><b>--smtp-encryption=<type></b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the encryption type (e.g., <i>ssl</i>, <i>tls</i>, <i>starttls</i>) for SMTP communication.<br><br><b><b>--dry-run</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Don't send emails; instead, print what would be sent to standard output. Useful for testing.<br><br><b><b>--compose</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Open an editor to compose/edit the cover letter and/or message body before sending.<br><br><b><b>--cover-letter</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Generate and include a cover letter email before the patch series, providing an overall description.<br><br><b><b>--in-reply-to=<message-id></b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Make the first email in the series a reply to the given Message-ID.<br><br><b><b>--chain-reply-to</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Make each subsequent patch email a reply to the previous patch email, creating a chain of replies.<br><br><b><b>--signed-off-by</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Automatically add a 'Signed-off-by:' line to the email body if missing from the commit message.<br><br><b><I>revision-range</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The range of commits to send as patches (e.g., <i>HEAD~3..HEAD</i>, <i>v1.0..master</i>).<br><br><b><I>mbox</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Path to a mailbox file containing patches to send, typically generated by <i>git format-patch</i>.<br><br>


title: DESCRIPTION
content:
<i>git-send-email</i> is a Git porcelain command designed to send a series of commits (patches) from a Git repository as emails. It is a fundamental tool for developers contributing to projects that utilize a patch-based workflow, most notably the Linux kernel development model. <br><br>The command efficiently formats your commits into standard email messages, handling various aspects like subject lines (with patch numbers), body content, and diffs. It can automatically generate a cover letter for a series of patches and manage threading for better email client readability. <br><br>It supports direct SMTP communication, allowing users to specify server details, authentication credentials, and encryption methods. This makes it a powerful and flexible solution for submitting code contributions directly from your local Git repository without relying on web-based interfaces. Its deep integration with Git's commit history ensures that patches are correctly formatted and attributed.


title: CAVEATS
content:
Initial setup can be complex due to various SMTP and authentication configurations. <br>Sensitive information like SMTP passwords can be exposed if not handled carefully (e.g., in command history). <br>Email client compatibility for threaded messages and patch application can vary. <br>Relies on a correctly configured Git environment and system mail settings.


title: CONFIGURATION
content:
Most options for <i>git-send-email</i>, especially SMTP server details and common recipients, can be persistently configured using <i>git config</i>. For example, <i>git config --global sendemail.smtpserver smtp.example.com</i> allows you to avoid typing these options for every invocation.


title: INTERACTIVE MODE
content:
By default, <i>git-send-email</i> often operates in an interactive mode, prompting the user for confirmation before sending each email or the entire series. This provides an opportunity to review the formatted emails and ensure correctness before dispatch.


title: COVER LETTER & ANNOTATION
content:
The command provides robust support for generating a cover letter, which serves as an introduction to a series of patches. The <i>--compose</i> and <i>--annotate</i> options allow for in-depth editing and adding extra notes or explanations directly within the cover letter, crucial for large contributions.


title: HISTORY
content:
<i>git-send-email</i> is a core part of Git, developed to facilitate the traditional patch-based contribution model prevalent in many open-source projects, particularly the Linux kernel. Its design predates the widespread adoption of web-based pull request systems and remains essential for workflows that prioritize email-based code review and submission.


title: PARAMETERS
content:
<b>None</b><br>&nbsp;&nbsp;&nbsp;&nbsp;This command does not accept direct user-facing command-line parameters as it is intended to be <i>sourced</i> by other Git shell scripts, not executed directly.<br><br>


title: DESCRIPTION
content:
The `git-sh-setup` command is a shell script designed to be <i>sourced</i> by other Git-related shell scripts, rather than being executed directly. Its primary purpose is to provide a standardized set of utility functions, shell variables, and aliases commonly used across various Git shell scripts. By sourcing `git-sh-setup`, scripts can leverage a consistent environment for tasks such as error handling (e.g., `<b>git_die</b>`), path manipulation, parsing Git objects, interacting with the user's editor or pager, and handling repository-specific configurations. This centralized setup reduces code duplication, promotes consistency in behavior, and simplifies the development of new Git utilities. It ensures that all shell scripts within the Git ecosystem adhere to a common set of best practices and environmental expectations, making them more robust and maintainable.


title: CAVEATS
content:
This command is <i>not</i> meant for direct user execution. It is an internal Git utility script designed to be <b>sourced</b> by other Git-related shell scripts to establish a common environment and provide reusable functions. Attempting to run `git-sh-setup` directly from the command line will likely result in an error or unexpected behavior, as it relies on being sourced into an existing shell environment.


title: PROVIDED FUNCTIONS AND VARIABLES
content:
When `git-sh-setup` is sourced, it defines numerous functions and sets several variables that are essential for Git shell scripts. Examples of functions include `<b>git_die</b>` for consistent error handling, `<b>git_editor</b>` and `<b>git_pager</b>` for interacting with user-configured tools, and `<b>git_extract_date</b>` for parsing Git date formats. It also sets up common environment variables and ensures proper path configurations, streamlining development and ensuring consistent behavior across all Git shell scripts.


title: HISTORY
content:
The `git-sh-setup` script has been a fundamental component of Git's architecture since its early days, reflecting Git's significant reliance on shell scripting for many of its internal and user-facing commands. Its existence underscores the need for a standardized and efficient way to manage common tasks and environmental setups across a diverse set of shell scripts. Over time, it has evolved to include more utility functions and variables as Git's capabilities expanded, serving as a stable backbone for script development within the Git project. Its consistent presence highlights a design philosophy that prioritizes modularity and reusability in shell script development.


title: SYNOPSIS
content:
<i><b>git add</b></i> [<I>options</I>] [--] [<I>pathspec</I>...]<br><i><b>git add</b></i> -A | --all<br><i><b>git add</b></i> -u | --update


title: PARAMETERS
content:
<b>-A, --all</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Stage all changes from all tracked and untracked files in the working directory, including new files, modifications, and deletions.<br><br><b>-u, --update</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Stage modifications and deletions for files that are already tracked. New, untracked files are ignored.<br><br><b>-p, --patch</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Interactively select and stage specific hunks of changes within files, providing fine-grained control over what gets staged.<br><br><b>.</b><br>&nbsp;&nbsp;&nbsp;&nbsp;A common pathspec indicating to stage all changes in the current directory and its subdirectories. Similar to --all when executed from the repository root.<br><br><b><pathspec>...</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies one or more files or directories to stage. Only changes within these specified paths will be added to the index.<br><br><b>-n, --dry-run</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Perform a 'dry run'; show what would be staged without actually modifying the index or working tree.<br><br><b>-f, --force</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Allows adding files that match ignore rules defined in .gitignore or similar configurations.<br><br><b>-N, --intent-to-add</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Record only the fact that the path will be added later. The file content is not staged, but its path is marked for addition.<br><br>


title: DESCRIPTION
content:
While <i><b>git-stage</b></i> is not a standalone executable command in Git, it conceptually refers to the act of preparing changes from the working directory to be included in the next commit. This crucial step is primarily performed by the <br><i><b>git add</b></i> command.<br><br>The staging area, also known as the index, acts as a temporary buffer between your working directory and your repository. When you make modifications to files, create new files, or delete existing ones, these changes are initially in your working directory.<br><br>Using <i><b>git add</b></i> (or 'staging' them) moves these specific changes into the staging area. This allows you to meticulously craft your next commit by selecting only the relevant modifications. You can stage a subset of changes from a file, add newly created files, or mark files for deletion. Only changes present in the staging area will be recorded when you execute <i><b>git commit</b></i>. This flexibility is a core strength of Git's workflow, enabling clean, focused commits.


title: CAVEATS
content:
The command <i><b>git-stage</b></i> is not a direct executable Git command. The actual operation of staging changes is performed by <i><b>git add</b></i>.<br><br><i><b>git add</b></i> prepares changes for a commit; it does not itself create a commit. You must run <i><b>git commit</b></i> afterwards.<br><br>Be cautious with <i><b>git add .</b></i> or <i><b>git add -A</b></i>, as they stage <i>all</i> detected changes, potentially including unfinished work you didn't intend to commit.<br><br>Once changes are staged, they can be unstaged using commands like <i><b>git restore --staged &lt;file&gt;</b></i> or <i><b>git reset &lt;file&gt;</b></i>.


title: THE STAGING AREA (INDEX)
content:
The staging area, also known as the index, is a unique feature of Git that provides an intermediate buffer between your working directory and your repository. It allows you to build up a commit incrementally by selecting specific changes from various files, rather than committing all modifications at once. This enables more precise and logical commits.


title: COMMON STAGING PATTERNS
content:
To stage all changes (new, modified, deleted) in the current directory and subdirectories:<br><i><b>git add .</b></i><br><br>To stage a specific file:<br><i><b>git add &lt;filename&gt;</b></i><br><br>To stage all modified and deleted files (but not new untracked files):<br><i><b>git add -u</b></i><br><br>To interactively select parts of files to stage:<br><i><b>git add -p</b></i>


title: HISTORY
content:
The concept of staging changes is fundamental to Git's design, introduced from its inception by Linus Torvalds. The <i><b>git add</b></i> command has been a core component since the very first versions of Git, serving the purpose of populating the index (staging area) with desired changes for the next commit. Its functionality has remained largely consistent, reflecting its foundational role in Git's unique workflow.


title: SEE ALSO
content:
<i><b>git add(1)</b></i>, <i><b>git commit(1)</b></i>, <i><b>git status(1)</b></i>, <i><b>git restore(1)</b></i>, <i><b>git reset(1)</b></i>


title: SYNOPSIS
content:
<b><code>gitlab-ctl</code></b> <i>[global options]</i> <i>&lt;command&gt;</i> <i>[command options/arguments]</i><br><br>Examples:<br><i><code>gitlab-ctl reconfigure</code></i><br><i><code>gitlab-ctl status</code></i><br><i><code>gitlab-ctl start nginx</code></i>


title: PARAMETERS
content:
<b>reconfigure</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Applies configuration changes from <i>/etc/gitlab/gitlab.rb</i> and reconfigures all GitLab services.<br><br><b>start [service]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Starts all GitLab services, or a specific service like <i>nginx</i>, <i>postgresql</i>, <i>sidekiq</i>.<br><br><b>stop [service]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Stops all GitLab services, or a specific service.<br><br><b>restart [service]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Restarts all GitLab services, or a specific service.<br><br><b>status</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays the current running status of all GitLab services.<br><br><b>tail [service]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Continuously outputs log entries for all GitLab services or a specific service (e.g., <i>nginx</i>, <i>unicorn</i>).<br><br><b>console</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Opens an interactive Ruby on Rails console for the GitLab application.<br><br><b>psql</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Opens an interactive PostgreSQL console for the GitLab database.<br><br><b>redis-cli</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Opens an interactive Redis command-line interface for GitLab's Redis instance.<br><br><b>backup-etc</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Creates a backup of GitLab configuration files and directories.<br><br><b>upgrade</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Performs tasks related to GitLab upgrades, often followed by <i>reconfigure</i>.<br><br><b>--help, -h</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays general help information or help for a specific subcommand.<br><br><b>--verbose</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables verbose output during command execution, showing more details.<br><br><b>--debug</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables debug output, providing even more detailed information, useful for troubleshooting.<br><br>


title: DESCRIPTION
content:
<i><b>gitlab-ctl</b></i> is the primary command-line interface for managing a GitLab Omnibus installation. It provides a unified way to control various services like Nginx, PostgreSQL, Redis, Unicorn, and Sidekiq, which are integral components of GitLab.<br><br>This utility simplifies complex administrative tasks such as applying configuration changes, starting or stopping services, checking their status, and tailing logs. It abstracts away the underlying complexities of managing individual service processes, making GitLab administration more straightforward for system administrators. Key functions include <i><b>reconfigure</b></i> for applying changes from <i>/etc/gitlab/gitlab.rb</i>, <i><b>start</b></i>, <i><b>stop</b></i>, <i><b>restart</b></i>, <i><b>status</b></i> for service control, <i><b>tail</b></i> for log monitoring, and <i><b>console</b></i>, <i><b>psql</b></i>, <i><b>redis-cli</b></i> for advanced debugging and database interactions. <i><b>gitlab-ctl</b></i> is essential for maintaining a healthy and up-to-date GitLab instance packaged via the Omnibus installer.


title: CAVEATS
content:
<i><b>Privilege Requirement:</b></i> Most <i><b>gitlab-ctl</b></i> commands require root or sudo privileges to execute successfully due to their system-wide impact on services and configurations.<br><i><b>Omnibus Specific:</b></i> This command is designed for and primarily used with GitLab Omnibus package installations. It is generally not applicable or fully functional for source installations of GitLab.<br><i><b>Configuration Changes:</b></i> Many configuration changes made in <i>/etc/gitlab/gitlab.rb</i> will not take effect until <i><b>gitlab-ctl reconfigure</b></i> is run. Forgetting this step is a common troubleshooting point.<br><i><b>Service Disruptions:</b></i> Commands like <i><b>stop</b></i> or <i><b>restart</b></i> will temporarily disrupt GitLab services, making them unavailable to users. Plan execution during maintenance windows.


title: CONFIGURATION FILE
content:
The primary configuration file for GitLab Omnibus installations is <i>/etc/gitlab/gitlab.rb</i>. Most system-level settings and service configurations are managed through this file, with <i><b>gitlab-ctl reconfigure</b></i> applying the changes.


title: UNDERLYING TECHNOLOGY
content:
<i><b>gitlab-ctl reconfigure</b></i> executes Chef recipes. It reads the settings from <i>gitlab.rb</i> and compiles them into a Chef run list, which then configures the various services and components of GitLab.


title: LOGGING
content:
GitLab services managed by <i><b>gitlab-ctl</b></i> typically write their logs to <i>/var/log/gitlab/</i>. The <i><b>gitlab-ctl tail</b></i> command provides a convenient way to monitor these logs in real-time.


title: HISTORY
content:
The <i><b>gitlab-ctl</b></i> command emerged as a cornerstone of the GitLab Omnibus package, which was introduced to simplify the installation, configuration, and management of GitLab. Prior to Omnibus, deploying GitLab from source was a complex process requiring manual setup of various components like Nginx, PostgreSQL, Redis, and Ruby applications. <i><b>gitlab-ctl</b></i> was developed to abstract these complexities, leveraging <i>Chef Solo</i> for idempotent configuration management and providing a user-friendly interface for common administrative tasks. Its introduction significantly lowered the barrier to entry for self-hosting GitLab, making it accessible to a wider audience by providing a robust, all-in-one package with a consistent management interface.


title: SYNOPSIS
content:
Git invokes a remote helper program with the following syntax:<br><code><b><I>git-remote-<name> <repository> <URL></I></b></code><br>Where:<br><code><I><name></I></code> is the scheme from the remote URL (e.g., 'http', 'hg', 'fossil').<br><code><I><repository></I></code> is the path to the current Git repository.<br><code><I><URL></I></code> is the full remote repository URL.


title: PARAMETERS
content:
<b>capabilities</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Git asks the helper to list its supported features (e.g., <code><I>fetch</I></code>, <code><I>push</I></code>, <code><I>option</I></code>).<br><br><b>list</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Git requests a list of all references (branches, tags) and their corresponding object IDs from the remote repository.<br><br><b>option <name> <value></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Git sets an option for the helper (e.g., <code><I>option verbosity 2</I></code>).<br><br><b>fetch <sha1> <name></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Git asks the helper to fetch the object identified by <code><I><sha1></I></code>, along with its history and objects. The helper responds with a packfile.<br><br><b>push <src>:<dst></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Git instructs the helper to push the local reference <code><I><src></I></code> to the remote reference <code><I><dst></I></code>.<br><br><b>connect <service></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Git requests a connection to a specific remote service (e.g., 'git-upload-pack', 'git-receive-pack') for transport. This is primarily for native Git protocols.<br><br><b>setoption <key> <value></b><br>&nbsp;&nbsp;&nbsp;&nbsp;A newer command for setting general remote options.<br><br><b>refspec <refspec></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Used to configure fetch/push refspecs for the remote helper.<br><br><b>import-marks <file></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Instructs the helper to load marks from a file, primarily for <code><I>fast-import</I></code> like operations.<br><br><b>export-marks <file></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Instructs the helper to save marks to a file.<br><br><b>get-url</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Requests the helper to provide the canonical URL of the remote.<br><br>


title: DESCRIPTION
content:
The <b>gitremote-helpers</b> mechanism defines a standardized protocol that allows Git to interact with remote repositories using arbitrary, external helper programs.<br>This extensibility enables Git to support various non-native protocols or repository types (e.g., Mercurial, Fossil, Subversion) without needing to embed their logic directly into the Git core.<br>When Git needs to communicate with a remote whose URL starts with a custom scheme (e.g., <code><I>hg::</I></code>, <code><I>fossil::</I></code>), it invokes a corresponding helper program named <code><I>git-remote-<scheme></I></code>.<br>The helper then communicates with Git via its standard input and output, exchanging commands (from Git to helper) and responses (from helper to Git).<br>This includes operations like listing references, fetching objects, and pushing changes.<br>The protocol ensures a clean separation of concerns, allowing third-party developers to extend Git's remote capabilities.


title: CAVEATS
content:
Implementing a robust remote helper can be complex due to the need to fully understand and correctly implement the Git packfile format and reference negotiation.<br>Performance can be an issue if the helper is inefficient or involves many external process invocations.<br>Security must be considered carefully, as a malicious or buggy helper could expose sensitive data or corrupt the local repository.<br>The protocol itself can evolve, requiring helpers to be updated to support new features or adhere to changes.


title: PROTOCOL DETAILS
content:
The interaction between Git and a remote helper occurs over standard input/output.<br>Git sends commands on lines terminated by a newline, and the helper responds similarly.<br>After processing a command, the helper typically prints <code><I>ok</I></code> to indicate success or <code><I>error</I></code> followed by a message.<br>The protocol supports capabilities negotiation, allowing Git and the helper to agree on supported features.<br>For fetching, helpers are expected to stream packfiles to Git's stdout.


title: HELPER NAMING CONVENTION
content:
Remote helper programs must be named <code><I>git-remote-<scheme></I></code> and reside in Git's executable search path (e.g., <code><I>~/bin</I></code> or a directory listed in <code><I>$PATH</I></code>).<br>When Git encounters a URL like <code><I>fossil::/path/to/repo.fossil</I></code>, it attempts to execute <code><I>git-remote-fossil</I></code>.


title: HISTORY
content:
The remote helper mechanism was introduced early in Git's development to provide a flexible way to interact with various network protocols and repository types beyond Git's native capabilities.<br>It allowed Git to integrate with other version control systems (like CVS, Subversion, Mercurial) through external bridges, thereby extending its reach and interoperability without bloating the core Git codebase.<br>This design philosophy emphasizes modularity and extensibility, which are hallmarks of Git's architecture.


title: PARAMETERS
content:
<b><I>--branch &lt;string&gt;</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Specify the target branch for the merge operation.</I><br><br><b><I>--delete-source-branch</I>, <I>-d</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Delete the source branch after a successful merge.</I><br><br><b><I>--force</I>, <I>-f</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Force merge, bypassing pipeline status, conflicts, or other restrictions. Use with caution.</I><br><br><b><I>--message &lt;string&gt;</I>, <I>-m &lt;string&gt;</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Provide a custom message for the merge commit.</I><br><br><b><I>--pipeline-succeeds</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Set the merge request to merge automatically once all CI/CD pipelines successfully complete.</I><br><br><b><I>--rebase</I>, <I>-r</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Rebase the source branch onto the target branch before merging.</I><br><br><b><I>--squash</I>, <I>-s</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Squash all commits from the source branch into a single commit upon merge.</I><br><br><b><I>--squash-message &lt;string&gt;</I>, <I>-t &lt;string&gt;</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Provide a custom message for the squashed commit.</I><br><br><b><I>--title &lt;string&gt;</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Provide a custom title for the merge commit.</I><br><br><b><I>--wait</I>, <I>-w</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Wait for the merge operation to complete before exiting the command.</I><br><br>


title: DESCRIPTION
content:
The <I>glab mr merge</I> command is a core subcommand of the <I>glab</I> (GitLab CLI) tool, designed to streamline the process of merging GitLab Merge Requests (MRs) directly from your terminal. It allows developers to quickly complete a merge request without navigating to the GitLab web interface.<br><br>This command supports various options to control the merge behavior, such as rebasing before merging (<I>--rebase</I>), squashing commits (<I>--squash</I>), deleting the source branch after a successful merge (<I>--delete-source-branch</I>), and setting a custom merge commit message (<I>--message</I>). It also supports the "merge when pipeline succeeds" feature (<I>--pipeline-succeeds</I>), which is crucial for CI/CD workflows, ensuring code quality before integration. The command typically requires the MR ID or an alias (like the current branch name if it's an MR branch) as an argument.


title: CAVEATS
content:
The command requires appropriate permissions on the GitLab project to merge an MR.<br>The Merge Request must be in a mergeable state (e.g., no unaddressed discussions, no conflicts, unless <I>--force</I> is used).<br>Conflicts must typically be resolved manually through the GitLab UI or by rebasing/merging locally before attempting to merge via <I>glab</I>.<br>Using <I>--force</I> can bypass important pre-merge checks, so it should be used judiciously.


title: MERGE REQUEST ID / ALIAS
content:
The <I>&lt;MR_ID | branch&gt;</I> argument can be the numeric ID of the merge request (e.g., <I>123</I>), a full GitLab MR URL, or a reference like <I>!123</I>. If omitted, <I>glab</I> attempts to infer the MR from the current Git branch you are on, assuming it's a feature branch associated with an open MR.


title: PRE-MERGE CHECKS
content:
<I>glab mr merge</I> respects GitLab's project settings, including required approvals, successful CI/CD pipelines, and conflict status. The <I>--force</I> flag can override some of these checks, but should be used with extreme caution to avoid introducing issues into the codebase.


title: HISTORY
content:
<I>glab</I> was introduced in late 2020 as the official GitLab CLI tool, aiming to bring GitLab functionalities to the command line, similar to GitHub's <I>gh</I> CLI. The <I>mr</I> (merge request) functionalities, including the <I>merge</I> subcommand, have been foundational components since its early versions, evolving to align with new features and best practices in GitLab.


title: SYNOPSIS
content:
<b>gladtex</b> [<I>options</I>] <I>input_file</I> [<I>output_file</I>]<br><b>gladtex</b> <I>--generate</I> <I>layout_spec</I> <I>--output</I> <I>tex_snippet</I>


title: PARAMETERS
content:
<b><b>-o</b> <I>output_file</I>, <b>--output</b>=<I>output_file</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the name of the output document (e.g., .pdf, .dvi) or the generated TeX snippet file. If omitted, a default name based on the input might be used.<br><br><b><b>-g</b> <I>type</I>, <b>--graphic-type</b>=<I>type</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Defines the preferred graphic format for inclusion or generation (e.g., <I>pdf</I>, <I>eps</I>, <I>svg</I>). The command would attempt to convert inputs to this type if necessary.<br><br><b><b>-l</b> <I>preset</I>, <b>--layout-preset</b>=<I>preset</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Applies a predefined graphical layout or template. This could include settings for margins, figure placement rules, or common diagram styles.<br><br><b><b>--generate</b> <I>spec_file</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Instead of processing a document, generates TeX code or configuration based on a simplified specification file (e.g., YAML or JSON) describing graphical elements, making it easier to integrate complex graphics.<br><br><b><b>-v</b>, <b>--verbose</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Increases verbosity, displaying detailed processing steps, warnings, and debugging information during execution to help troubleshoot issues.<br><br><b><b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a help message with command usage and available options.<br><br><b><b>--version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays the version information for the gladtex utility.<br><br>


title: DESCRIPTION
content:
The command 'gladtex' is not a standard, widely recognized utility in common Linux distributions or core GNU packages. However, if one were to interpret its name – combining 'GLAD' (perhaps implying graphical operations or layout) and 'TeX' (referring to the typesetting system) – it could hypothetically be envisioned as a command-line interface designed to streamline the integration or management of complex graphical layouts within LaTeX documents.<br><br>Its purpose might be to simplify common tasks such as positioning figures, applying consistent graphical styles, or automating the conversion and inclusion of various graphic formats (like SVG, PNG, JPEG) into a TeX compilation workflow. It could potentially abstract away some of the complexities of packages like TikZ or PSTricks, providing a higher-level syntax for graphical elements, or manage external graphic assets for a project, aiming to enhance productivity for document creators.


title: CAVEATS
content:
<b>Important Note:</b> The 'gladtex' command is <b>not a standard Linux utility</b> found in common distributions (like Debian, Ubuntu, Fedora, Arch Linux) or widely recognized open-source projects. The analysis above is <i>hypothetical</i>, based on a plausible interpretation of its name ('glad' often associated with graphics or layout, and 'tex' for LaTeX/TeX typesetting). This information describes how such a command <i>might</i> function if it were developed with a focus on graphical layout and LaTeX integration. Users looking for similar functionality should explore existing LaTeX packages (e.g., TikZ, PSTricks, graphicx, float) or general-purpose document generation and image processing tools.


title: HYPOTHETICAL DESIGN PRINCIPLES
content:
If 'gladtex' were a real utility, its design might emphasize:<br><b>Abstraction:</b> Providing a higher-level syntax for graphical elements, shielding users from verbose LaTeX package code.<br><b>Integration:</b> Seamlessly working with common image formats and external graphic design tools.<br><b>Automation:</b> Automating tasks like image conversion, scaling, and precise positioning within a document.<br><b>Consistency:</b> Enabling easy application of consistent graphical styles across a document or project for unified aesthetics.


title: HISTORY
content:
As 'gladtex' is not a standard command, there is no documented public history of its development or widespread usage. If it were to exist, its conceptual history would likely stem from the persistent need to simplify the often complex process of creating and managing graphics within LaTeX documents. Its design philosophy might prioritize ease-of-use for common graphical tasks, aiming to reduce manual LaTeX code for complex layouts and bridge the gap between graphical design tools and text-based typesetting systems.


title: PARAMETERS
content:
<b><i>--target=FILE</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the output file name. The file extension often determines the output type (e.g., <i>.c</i> for C source, <i>.h</i> for C header, <i>.gresource</i> for binary).<br><br><b><i>--sourcedir=DIR</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the base directory from which relative paths in the <i>.gresource.xml</i> file are resolved. This is crucial for locating the actual resource files.<br><br><b><i>--generate-header</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Instructs the command to generate a C header file (<i>.h</i>), typically containing declarations for accessing the compiled resources.<br><br><b><i>--generate-source</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Instructs the command to generate a C source file (<i>.c</i>) containing the compiled resource data and initialization functions.<br><br><b><i>--generate-gresource</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Instructs the command to generate a binary <i>.gresource</i> file, which can be loaded at runtime without being compiled into the application's executable.<br><br><b><i>--dependency-file=FILE</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Generates a file listing the dependencies of the compiled resources, useful for integration with build systems like Make.<br><br><b><i>--c-name=NAME</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the C identifier name for the generated resource variable, used when generating C source or header files.<br><br><b><i>--internal</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Makes the generated declarations internal (static) to the C source file, preventing symbol clashes if the resource is part of a library.<br><br><b><i>--external-data</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Causes data larger than 1MB to be stored externally in separate files rather than embedded directly. Useful for very large resources.<br><br><b><i>--disable-external-data</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Disables the external data feature, embedding all data directly regardless of size.<br><br><b><i>--compress</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Compresses resource data using zlib. This is the default behavior in modern GLib versions (since 2.70).<br><br><b><i>--disable-compress</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Disables resource data compression.<br><br><b><i>--compression-level=LEVEL</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the zlib compression level (0-9, default 9).<br><br><b><i>--compression-type=TYPE</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the compression algorithm (e.g., 'none', 'lz4', 'zlib').<br><br><b><i>--version</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays the version information of <b>glib-compile-resources</b>.<br><br><b><i>--help</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows a summary of command-line options.<br><br>


title: DESCRIPTION
content:
The <b>glib-compile-resources</b> command is a utility provided by the GLib library, primarily used in the development of GTK+ and other GLib-based applications. Its core function is to take an XML description of application resources (such as images, UI definitions, CSS files, icons, or any other data) along with the actual resource files, and compile them into a C source file or a binary GResource file.<br><br>This process allows developers to bundle all necessary application assets directly into the executable, eliminating the need for separate resource files at runtime. This simplifies deployment, ensures resources are always available, and can improve startup performance by reducing file system lookups. The generated C source file can then be compiled and linked into the application's executable, where resources can be accessed programmatically using GLib's GResource API. Alternatively, a <i>.gresource</i> binary file can be generated and loaded at runtime. It's an essential tool for creating self-contained and easily distributable GLib applications.


title: CAVEATS
content:
<ul><li><b>Build System Integration:</b> While powerful, <b>glib-compile-resources</b> is typically integrated into build systems like Meson or Autotools rather than run manually by developers. Incorrect build script setup can lead to issues.</li><li><b>XML Structure:</b> The command relies heavily on a correctly formatted <i>.gresource.xml</i> file. Errors in this XML can lead to compilation failures.</li><li><b>Path Resolution:</b> Careful use of the <i>--sourcedir</i> option and relative paths in the XML is necessary to ensure all resources are found correctly.</li><li><b>Large Resources:</b> For very large resources, consider using <i>--external-data</i> to avoid excessive memory usage or long compilation times when embedding directly.</li></ul>


title: GRESOURCE XML FILE STRUCTURE
content:
The input to <b>glib-compile-resources</b> is typically an XML file (e.g., <i>myresources.gresource.xml</i>) that describes the resources. It defines one or more <i>&lt;gresource&gt;</i> bundles, each with a <i>prefix</i> attribute (e.g., <i>/org/example/app/ui/</i>) under which resources are accessed. Within each bundle, individual resource files are listed using <i>&lt;file&gt;</i> tags. The path in the <i>&lt;file&gt;</i> tag is relative to the <i>--sourcedir</i>. Resources can also specify attributes like <i>compressed="true"</i>. This structured XML allows the command to know which files to include and how they should be exposed within the application.


title: INTEGRATION WITH BUILD SYSTEMS
content:
In most modern GLib/GTK+ projects, <b>glib-compile-resources</b> is not run manually. Instead, it's integrated into the project's build system. Tools like <i>Meson</i> or <i>Autotools</i> have built-in support or modules to automatically invoke <b>glib-compile-resources</b> during the build process. This ensures that resources are compiled and linked correctly, and dependencies are managed, simplifying the build workflow for developers.


title: HISTORY
content:
The <b>glib-compile-resources</b> utility, and the GResource system it supports, was introduced with GLib 2.32, released in March 2012. Before this, developers often resorted to custom methods or external tools to embed resources into applications. The GResource system provided a standardized, efficient, and integrated way for GLib/GTK+ applications to manage and access their bundled assets, improving deployment simplicity and runtime performance. Its development reflects GLib's ongoing effort to provide comprehensive tooling for application development on Linux and other platforms.


title: SYNOPSIS
content:
<b>glxinfo</b> [<i>options</i>]<br><br>Examples:<br><code>glxinfo</code><br><code>glxinfo -i</code><br><code>glxinfo -B -D -E -F</code><br><code>glxinfo --display :1.0</code>


title: PARAMETERS
content:
<b>-i, --info</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints detailed GLX and OpenGL information. This is often the default behavior when no options are specified.<br><br><b>-v, --verbose</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints verbose information, including version details for GLX and OpenGL libraries.<br><br><b>-b</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints boolean capabilities of the GLX visual and OpenGL context.<br><br><b>-l</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints verbose GLX limits and capabilities.<br><br><b>-B</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints information about GLX Framebuffer Configurations (FBConfigs), including pixel format details.<br><br><b>-D</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints detailed GLX protocol information, useful for low-level debugging.<br><br><b>-E</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints a list and details of supported GLX extensions.<br><br><b>-F</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints a list and details of supported OpenGL extensions.<br><br><b>-I</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints information about the OpenGL implementation, such as vendor, renderer, and version strings.<br><br><b>-L</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints information about OpenGL limits, such as maximum texture sizes and viewport dimensions.<br><br><b>-M</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints information about OpenGL matrices and transformations.<br><br><b>-O</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints information about OpenGL objects (e.g., textures, shaders, buffers).<br><br><b>-P</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints information about OpenGL pixel formats.<br><br><b>-R</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints information about OpenGL rendering capabilities and modes.<br><br><b>-S</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints information about the current OpenGL state.<br><br><b>-V</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints information about OpenGL vertex arrays.<br><br><b>-W</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints information about OpenGL windows and visual configurations.<br><br><b>-X</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints information about OpenGL transforms.<br><br><b>-Z</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints information about OpenGL Z-buffer (depth buffer).<br><br><b>--display &lt;display&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the X server display to connect to, e.g., <code>:0.0</code> or <code>localhost:1.0</code>.<br><br>


title: DESCRIPTION
content:
<i>glxinfo</i> is a command-line utility used to display comprehensive information about the GLX (OpenGL Extension to the X Window System) server extension, the installed OpenGL libraries, and the rendering capabilities of the graphics hardware. It provides crucial details such as whether direct rendering is enabled, the OpenGL vendor, renderer, version, and a full list of supported GLX and OpenGL extensions. This tool is indispensable for users and developers to diagnose graphics driver issues, verify hardware acceleration, and ensure that the correct OpenGL environment is configured for demanding applications. Its output helps identify bottlenecks or misconfigurations in the graphics stack, making it a primary diagnostic tool for X Window System OpenGL environments.


title: CAVEATS
content:
<i>glxinfo</i> requires an X server to be running and correctly configured with GLX. Its output can be very extensive, sometimes hundreds of lines, making it challenging to parse manually. Key information like 'Direct rendering: Yes' is crucial for confirming hardware acceleration. If direct rendering is 'No', it indicates that software rendering is in use, often due to missing or misconfigured graphics drivers. The command's utility is limited by the availability of an X display and proper graphics stack setup.


title: INTERPRETING KEY OUTPUT
content:
When running <i>glxinfo</i>, look for the following lines to quickly assess your graphics setup:<br><ul><li><b>"Direct rendering: Yes"</b>: Confirms that hardware acceleration is active. If it says "No", your system is likely using software rendering.</li><li><b>"OpenGL vendor string"</b>: Identifies the GPU manufacturer (e.g., NVIDIA Corporation, Intel, AMD).</li><li><b>"OpenGL renderer string"</b>: Specifies the exact GPU model or driver in use (e.g., GeForce RTX 3080/PCIe/SSE2, Mesa Intel(R) HD Graphics 620).</li><li><b>"OpenGL version string"</b>: Shows the supported OpenGL API version (e.g., 4.6 (Core Profile) Mesa 23.1.9).</li><li><b>"GLX extensions"</b> and <b>"OpenGL extensions"</b>: Lists the various features and capabilities supported by your GLX and OpenGL implementation.</li></ul>


title: DEBUGGING GRAPHICS ISSUES
content:
<i>glxinfo</i> is an invaluable first step in debugging graphics-related problems. If applications are slow, crashing, or failing to render correctly, running <i>glxinfo</i> can reveal if hardware acceleration is missing or if an outdated/incorrect driver is loaded. It helps verify that the system's OpenGL capabilities match the requirements of the application. For multi-GPU systems (e.g., NVIDIA Optimus or AMD switchable graphics), <i>glxinfo</i> can be used with environment variables like <code>__GLX_VENDOR_LIBRARY_NAME</code> or <code>DRI_PRIME=1</code> to determine which GPU is active for rendering.


title: HISTORY
content:
<i>glxinfo</i> is part of the <I>mesa-demos</I> or similar OpenGL utility packages, reflecting its role as a diagnostic tool for the Mesa 3D Graphics Library. GLX, the OpenGL Extension to the X Window System, was developed to integrate OpenGL's 3D rendering capabilities with the 2D X Window System, allowing OpenGL applications to render directly to X windows. <i>glxinfo</i> has been a fundamental tool since the early days of OpenGL on Linux/UNIX-like systems, evolving alongside OpenGL and GLX to provide insights into the graphics hardware and software stack, ensuring compatibility and optimal performance for graphics-intensive applications.


title: SYNOPSIS
content:
gnmic [GLOBAL_OPTIONS] set [SET_OPTIONS] [PATH_OR_FILE_ARGUMENTS]<br><br><b>Examples:</b><br><i>gnmic --target <I>device-ip:port</I> --username <I>user</I> --password <I>pass</I> set --update /system/motd-banner="Welcome" --encoding JSON<br><i>gnmic --config <I>config.yaml</I> set --replace /system/name="new-router-name" --file <I>config_payload.json</I><br><i>gnmic set --delete /interfaces/interface[name=ethernet0/1]/config/description


title: PARAMETERS
content:
<b>--update <path>[=<value>]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Adds or modifies a configuration element at the specified <I>path</I>. If <I>value</I> is provided, it sets the value; otherwise, it requires a subsequent <I>--value</I> flag or a file-based input. Can be used multiple times.<br><br><b>--replace <path>[=<value>]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Atomically replaces the configuration at the specified <I>path</I> with new content. If <I>value</I> is provided, it sets the value; otherwise, it requires a subsequent <I>--value</I> flag or a file-based input. Can be used multiple times.<br><br><b>--delete <path></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Removes the configuration element or subtree at the specified <I>path</I>. Can be used multiple times.<br><br><b>--value <value></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the value for the preceding <I>--update</I> or <I>--replace</I> operation. This is useful for simple key-value sets.<br><br><b>--file <path></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Reads a gNMI SetRequest payload from the specified file. The file typically contains JSON or YAML representing the update, replace, or delete operations.<br><br><b>--encoding <type></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the gNMI encoding type for the request (e.g., <I>JSON</I>, <I>PROTO</I>, <I>ASCII</I>, <I>BYTES</I>). Defaults to <I>JSON</I> if not specified.<br><br><b>--dry-run</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints the generated gNMI SetRequest without actually sending it to the target. Useful for debugging and verification.<br><br><b>--skip-verify</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Skips schema verification before sending the request. Use with caution as it might lead to malformed requests.<br><br><b>--no-sync</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Do not wait for a gNMI SyncResponse, even if the target supports it. This makes the operation non-blocking.<br><br><b>--qos <value></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the Differentiated Services Code Point (DSCP) for the gNMI request, influencing network prioritization.<br><br><b>--target <address></b><br>&nbsp;&nbsp;&nbsp;&nbsp;(Global) Specifies the gNMI target address and port (e.g., <I>192.168.1.1:50051</I>). This is a mandatory global option for most operations.<br><br><b>--username <name></b><br>&nbsp;&nbsp;&nbsp;&nbsp;(Global) Username for authenticating with the gNMI target.<br><br><b>--password <pass></b><br>&nbsp;&nbsp;&nbsp;&nbsp;(Global) Password for authenticating with the gNMI target.<br><br><b>--tls-ca <file></b><br>&nbsp;&nbsp;&nbsp;&nbsp;(Global) Path to the CA certificate file for TLS validation.<br><br><b>--tls-cert <file></b><br>&nbsp;&nbsp;&nbsp;&nbsp;(Global) Path to the client certificate file for mutual TLS authentication.<br><br><b>--tls-key <file></b><br>&nbsp;&nbsp;&nbsp;&nbsp;(Global) Path to the client private key file for mutual TLS authentication.<br><br>


title: DESCRIPTION
content:
<i>gnmic-set</i> is a crucial subcommand of the <I>gnmic</I> CLI client, designed to interact with network devices using the gNMI (gRPC Network Management Interface) protocol. It specifically implements the gNMI Set RPC, enabling users to programmatically modify configuration and state on compliant network elements.<br><br>The command supports three primary operations: <b>update</b>, <b>replace</b>, and <b>delete</b>. <b>Update</b> adds or modifies a configuration element at a specified path. <b>Replace</b> atomically replaces all configuration under a given path with new content, effectively performing a full overwrite. <b>Delete</b> removes a configuration element or subtree. These operations can be supplied as individual path-value pairs directly on the command line or as a structured gNMI SetRequest payload provided in JSON or YAML format via a file.<br><br><i>gnmic-set</i> is widely used in network automation scripts, CI/CD pipelines, and for ad-hoc configuration changes, offering a powerful, standardized, and vendor-agnostic way to manage network infrastructure. It leverages <i>gnmic</i>'s global options for target connectivity, authentication, and secure communication (TLS).


title: CAVEATS
content:
<ul><li><b>Target Support:</b> The target device must be gNMI-enabled and support the specific paths and data models being manipulated.</li><li><b>Permissions:</b> The authenticated user must have appropriate write permissions on the target device for the requested paths.</li><li><b>Schema Adherence:</b> All modification requests must conform to the target's YANG schema; malformed requests will be rejected by the device.</li><li><b>Atomicity:</b> While a single gNMI Set RPC can contain multiple operations (update, replace, delete), the target's behavior regarding atomicity (all or nothing) for these combined operations can vary by vendor implementation.</li></ul>


title: UNDERSTANDING SET OPERATIONS
content:
The gNMI <I>Set</I> RPC, implemented by <I>gnmic-set</I>, supports distinct modification types:<br><ul><li><b>Update:</b> Merges new configuration into existing configuration. If a leaf exists, its value is changed; if not, it's created. Non-specified leaves or containers remain untouched.</li><li><b>Replace:</b> Overwrites the existing configuration at a given path entirely. Any configuration elements under that path not specified in the replace payload will be removed. This is often used for atomic full configuration pushes.</li><li><b>Delete:</b> Removes the configuration subtree or leaf at the specified path. If the path does not exist, the operation typically succeeds without error.</li></ul>


title: INPUT FORMATS
content:
<I>gnmic-set</I> offers flexibility in how the SetRequest payload is provided:<br><ul><li><b>Command-line Arguments:</b> For simple operations, paths and values can be directly specified using <I>--update</I>, <I>--replace</I>, <I>--delete</I>, and <I>--value</I> flags.</li><li><b>File Input:</b> For complex or large configurations, the <I>--file</I> flag allows reading the gNMI SetRequest from a JSON or YAML file. This file directly represents the `update`, `replace`, and `delete` fields within the gNMI SetRequest protobuf message.</li></ul>


title: HISTORY
content:
The <I>gnmic</I> project, including its <I>set</I> subcommand, emerged as a vital tool within the OpenConfig and gNMI ecosystem. As network devices increasingly adopted gNMI for programmatic interaction, a robust command-line client was necessary to facilitate direct configuration management. <I>gnmic-set</I> was a core component from early versions, designed to provide a standardized, scriptable, and human-readable interface for modifying network state. Its development paralleled the growth of network automation and the shift from traditional CLI-based management to API-driven approaches, positioning <I>gnmic-set</I> as a cornerstone for modern network programmability.


title: PARAMETERS
content:
<b><I>FILE</I>...</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify one or more log files to open directly upon launching the application. If no files are specified, the application opens with its default log sources.<br><br><b>--display=<I>DISPLAY</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;X display to use. This is a standard GTK/GNOME application option for specifying the X server to connect to.<br><br><b>--version</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Output version information and exit.<br><br><b>--help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show help options and exit, providing a brief overview of command-line arguments.<br><br>


title: DESCRIPTION
content:
The <b>gnome-system-log</b> command launches a graphical utility for viewing various system logs on GNOME desktop environments. It provides a user-friendly interface to browse, filter, and search through log files such as syslog, kernel messages, authentication logs, and more. Key features include real-time log updates, color-coded entries for easier readability, and the ability to filter logs by severity level or keyword. It aggregates logs from traditional <i>/var/log</i> files and, on modern systems, integrates with <i>systemd-journald</i> to display journal entries. This tool is invaluable for troubleshooting system issues, monitoring system health, and reviewing security events without needing to parse raw text files in the terminal.


title: CAVEATS
content:
<b>gnome-system-log</b> is a graphical application and therefore requires a running X server and a GNOME desktop environment to function. It is not suitable for use on headless servers or in minimal command-line-only environments. While it can display logs from <i>/var/log</i>, its full functionality and seamless integration are best experienced within a GNOME session.


title: GUI FEATURES
content:
Beyond basic viewing, <b>gnome-system-log</b> offers features like automatic refreshing of logs, a search bar for finding specific entries, and filtering capabilities based on log type (e.g., kernel, system, authentication) or severity (e.g., error, warning, info). It also provides a graphical representation of log activity over time for quick analysis.


title: LOG SOURCES
content:
The application typically reads logs from common locations like <i>/var/log/syslog</i>, <i>/var/log/auth.log</i>, <i>/var/log/kern.log</i>, and other files found in the <i>/var/log</i> directory. On modern systems, it also connects to the <i>systemd-journald</i> service to retrieve and display structured journal entries, offering a consolidated view of system events.


title: HISTORY
content:
<b>gnome-system-log</b> has been a long-standing component of the GNOME desktop environment, providing a user-friendly interface for system log management. It evolved alongside GNOME's development, adapting to changes in logging infrastructure, such as the transition from traditional syslog to <i>systemd-journald</i>. Its primary goal has always been to make system troubleshooting and monitoring accessible to a wider audience, reducing the reliance on command-line tools for basic log inspection.


title: PARAMETERS
content:
<b><b>-x</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Starts <i>Gnuchess</i> in <b>Xboard</b> (Chess Engine Communication Protocol) mode, typically used when run by the Xboard GUI.<br><br><b><b>-u</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Starts <i>Gnuchess</i> in <b>UCI</b> (Universal Chess Interface) mode, allowing it to communicate with UCI-compatible chess GUIs.<br><br><b><b>-b</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Activates batch mode, where <i>Gnuchess</i> runs non-interactively, processing input from a file or standard input without human interaction. Useful for scripting.<br><br><b><b>-h</b>, <b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a comprehensive help message with all available command-line options and their descriptions.<br><br><b><b>-v</b>, <b>--version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints the version information of the <i>Gnuchess</i> program and exits.<br><br><b><b>-d</b> <i>&lt;depth&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the maximum search depth for the engine, limiting how many moves ahead the engine calculates. For example, <b>-d 8</b> limits the search to 8 plies.<br><br><b><b>-m</b> <i>&lt;minutes&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the maximum time per move in minutes. For example, <b>-m 5</b> gives the engine 5 minutes per move.<br><br><b><b>--hash-size</b> <i>&lt;MB&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the size of the transposition hash table in megabytes. A larger hash table can improve performance for deeper searches.<br><br><b><b>--fen</b> <i>&lt;FEN string&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Initializes the chess board with a specific position defined by a Forsyth-Edwards Notation (FEN) string.<br><br><b><b>--opening-book</b> <i>&lt;file&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Loads a specific opening book file, which <i>Gnuchess</i> uses to choose moves during the opening phase of the game.<br><br><b><b>--threads</b> <i>&lt;num&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the number of CPU threads the engine should use for its search. Useful for multi-core processors to speed up analysis.<br><br>


title: DESCRIPTION
content:
<i>Gnuchess</i> is a robust, free software chess program developed as part of the <i>GNU Project</i>. It provides a powerful chess engine capable of playing against human opponents, analyzing chess positions, and serving as a backend for graphical user interfaces (GUIs).<br><br>While it can be used interactively directly from the command line, its primary strength lies in its support for standard chess engine protocols like <b>Xboard</b> (also known as Chess Engine Communication Protocol) and <b>UCI</b> (Universal Chess Interface). This allows <i>Gnuchess</i> to be integrated seamlessly with popular chess GUIs such as <i>Xboard</i>, <i>Arena</i>, or <i>Scid vs. PC</i>, providing a rich visual experience.<br><br>Users can configure various aspects of the engine's play, including search depth, time limits, hash table size, and opening book usage, making it a versatile tool for both casual play and serious chess study.


title: CAVEATS
content:
While <i>Gnuchess</i> is a powerful engine, its direct command-line interface can be challenging for beginners. For a visual and user-friendly experience, it is highly recommended to use <i>Gnuchess</i> in conjunction with a graphical chess interface that supports <b>Xboard</b> or <b>UCI</b> protocols. Performance can vary significantly based on system resources and configured hash table size.


title: INTERACTIVE MODE COMMANDS
content:
When run without <b>-x</b> or <b>-u</b>, <i>Gnuchess</i> operates in interactive mode. Users can type commands directly into the terminal to control the game. Key commands include:<br><ul><li><b>move e2e4</b>: Make a move (e.g., pawn from e2 to e4).</li><li><b>new</b>: Start a new game.</li><li><b>undo</b>: Undo the last move.</li><li><b>redo</b>: Redo an undone move.</li><li><b>resign</b>: Resign the game.</li><li><b>analyze</b>: Enter analysis mode.</li><li><b>set</b> <i>&lt;option&gt;</i> <i>&lt;value&gt;</i>: Set engine options (e.g., <b>set depth 10</b>).</li><li><b>show options</b>: Display current engine settings.</li><li><b>quit</b>: Exit <i>Gnuchess</i>.</li></ul>


title: USING WITH GUIS (XBOARD/UCI)
content:
<i>Gnuchess</i> is most commonly used as an engine for graphical user interfaces. For <b>Xboard</b>, you typically start <i>Xboard</i> and then specify <i>Gnuchess</i> as an engine (e.g., <b>xboard -fcp gnuchess</b>). For <b>UCI</b> clients like <i>Arena</i> or <i>Scid vs. PC</i>, you would add <i>Gnuchess</i> as a new engine, pointing to its executable path and selecting the UCI protocol. This integration provides features like board visualization, move lists, and advanced analysis tools.


title: HISTORY
content:
<i>Gnuchess</i> is one of the oldest and most enduring free software chess programs, with its origins tracing back to <b>1984</b> when it was created by <b>Stuart Cracraft</b>. It quickly became an integral part of the <i>GNU Project</i>, embodying the principles of free and open-source software.<br><br>Over the decades, <i>Gnuchess</i> has undergone continuous development, adapting to new computing paradigms and integrating advanced chess algorithms. Its evolution has included support for standard protocols like <b>Xboard</b> and <b>UCI</b>, enabling its widespread use with various graphical interfaces and participation in computer chess tournaments. It remains a foundational component for many chess enthusiasts and developers within the Linux and free software communities.


title: SYNOPSIS
content:
<I>go test</I> [<i>build flags</i>] [<i>packages</i>] [<i>test flags</i>]<br><br><b>build flags</b>: These flags control how the test binary is built, e.g., <I>-mod=vendor</I> to use vendored modules.<br><b>packages</b>: Specifies the packages to test. Examples: . (current package), ./... (current package and all subpackages), or specific package paths like github.com/my/pkg. If omitted, the current directory's package is tested.<br><b>test flags</b>: These flags control the execution of the test binary itself, e.g., <I>-v</I> for verbose output.


title: PARAMETERS
content:
<b>-v</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Verbose output: print the names of test functions as they are executed and report test failures in full.<br><br><b>-run <regex></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Run only those tests and examples whose names match the regular expression. This flag applies to <I>TestXxx</I> and <I>ExampleXxx</I> functions.<br><br><b>-count <n></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Run each test and benchmark <I>n</I> times. If <I>n=0</I>, no caching is used.<br><br><b>-cover</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enable code coverage analysis. When set, <b>go test</b> will print a summary of the code coverage.<br><br><b>-coverprofile <file></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Write a coverage profile to the specified file. This file can then be used with <I>go tool cover</I> to generate reports.<br><br><b>-race</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enable data race detection. When a data race is detected, <b>go test</b> will report it.<br><br><b>-bench <regex></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Run benchmarks matching the regular expression. This flag applies to <I>BenchmarkXxx</I> functions.<br><br><b>-benchtime <duration></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Run each benchmark for a duration (e.g., <I>1s</I>, <I>100ms</I>). Default is <I>1s</I>.<br><br><b>-cpu <list></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Comma-separated list of GOMAXPROCS values for which to run benchmarks. (e.g., <I>1,2,4</I>).<br><br><b>-json</b><br>&nbsp;&nbsp;&nbsp;&nbsp;(Go 1.15+) Output test results in JSON format, suitable for machine parsing. This replaces the default textual output.<br><br><b>-args</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Pass all subsequent arguments directly to the test binary, after which <b>go test</b> processing ceases. Useful for custom test arguments.<br><br><b>-timeout <duration></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Fail a test if it takes longer than the specified duration (e.g., <I>30s</I>, <I>2m</I>).<br><br><b>-short</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Instructs tests to run in 'short' mode. Tests can use <I>testing.Short()</I> to skip long-running parts.<br><br><b>-parallel <n></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Run at most <I>n</I> test functions in parallel. By default, <I>n</I> is set to GOMAXPROCS.<br><br>


title: DESCRIPTION
content:
The <b>go test</b> command automates the execution of tests for Go packages.<br><br>It works by compiling the source files of a package, along with any files named <I>_test.go</I> that contain test functions, benchmark functions, and example functions. The compiled test binary is then executed. Functions named <I>TestXxx</I> (where <I>Xxx</I> is an alphanumeric string starting with an uppercase letter) are considered test functions. Similarly, <I>BenchmarkXxx</I> are benchmark functions and <I>ExampleXxx</I> are example functions.<br><br><b>go test</b> provides a comprehensive framework for unit, integration, and performance testing, seamlessly integrated into the Go toolchain. It can also generate code coverage reports and detect data races.


title: CAVEATS
content:
<b>Requires Go Environment</b>: A Go development environment (Go SDK) must be installed and configured.<br><b>File Naming</b>: Test source files must adhere to the Go convention of ending with <I>_test.go</I>.<br><b>Function Naming</b>: Test, Benchmark, and Example functions must start with an uppercase letter and reside in <I>_test.go</I> files.<br><b>Performance Impact</b>: Running tests with race detection (<I>-race</I>) or extensive coverage analysis (<I>-cover</I>) can significantly increase test execution time and memory usage.<br><b>Flag Scope</b>: Flags like <I>-v</I>, <I>-run</I>, <I>-bench</I> are passed to the compiled test binary, not directly interpreted by the <i>go test</i> command itself.


title: TEST FILE NAMING CONVENTIONS
content:
Go test files must always end with the suffix <I>_test.go</I>. For example, tests for mypackage.go would typically be in <I>mypackage_test.go</I>.


title: TEST FUNCTION SIGNATURES
content:
Test functions must have the signature <I>func TestXxx(t *testing.T)</I>. Benchmark functions must have <I>func BenchmarkXxx(b *testing.B)</I>. Example functions must have <I>func ExampleXxx()</I> or <I>func ExampleXxx_suffix()</I> and optionally print output to standard output.


title: INTEGRATION WITH GO TOOLCHAIN
content:
<I>go test</I> is an integral part of the standard Go toolchain, meaning it's available out-of-the-box with any Go installation without requiring additional setup or external dependencies for basic testing.


title: HISTORY
content:
The <b>go test</b> command and the <I>testing</I> package have been fundamental components of the Go programming language since its early development. Go's creators aimed to provide a robust, built-in testing framework to encourage good testing practices from the outset. This native support eliminates the need for third-party test runners or complex configurations. Over time, <b>go test</b> has evolved with new features like integrated race detection, code coverage, and the ability to output results in JSON format (Go 1.15+), continuously enhancing its utility for Go developers.


title: PARAMETERS
content:
<b>-n, --num NUM</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Specifies the maximum number of search results to display per page.</i><br><br><b>-s, --site SITE</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Limits the search to a specific website or domain (e.g., example.com).</i><br><br><b>-t, --time DURATION</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Filters results by time duration (e.g., 'h' for hour, 'd' for day, 'w' for week, 'm' for month, 'y' for year).</i><br><br><b>-w, --lucky</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Automatically opens the first search result directly in your default web browser (akin to Google's 'I'm Feeling Lucky' feature).</i><br><br><b>--np, --no-correct</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Disables Google's automatic spelling correction for the search query, useful for specific terms.</i><br><br><b>--json</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Outputs the search results in a structured JSON format, useful for scripting or parsing.</i><br><br><b>-C, --no-color</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Disables colored output, which can be useful when redirecting output or for terminals with limited color support.</i><br><br><b>-v, --version</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Displays the `googler` version information and then exits.</i><br><br>


title: DESCRIPTION
content:
`googler` is a highly efficient command-line utility designed to bring the power of Google search directly to your terminal. It allows users to quickly perform Google searches without the need to open a web browser, making it ideal for developers, system administrators, and anyone who prefers a minimalist workflow. `googler` prides itself on being fast, lightweight, and privacy-conscious, offering a cleaner search experience by default, free from cookies, JavaScript, and most ads. Users can customize the number of search results displayed, navigate through them using keyboard shortcuts, and even open selected links directly in their preferred web browser. Beyond basic searches, it supports advanced functionalities such as site-specific searches, disabling auto-correction, filtering results by time, and specifying a custom user agent. This tool scrapes the non-AMP mobile version of Google to provide a consistent and reliable command-line interface for your search queries.


title: CAVEATS
content:
As `googler` relies on scraping Google's non-AMP mobile site, future changes to Google's search page structure could potentially break its functionality. Users should also be mindful of Google's rate-limiting, as excessive or rapid queries might lead to temporary blocking of requests. It is not an official Google product and thus offers no guarantees of continuous operation or support from Google. Opening search results requires an external web browser to be configured and available on the system.


title: INTERACTIVE MODE
content:
After performing a search, `googler` enters an interactive session. Users can type a number (1-99) to open the corresponding link in their default web browser, 'n' to navigate to the next page of results, 'p' for the previous page, or 'q' to quit the session. This allows for seamless browsing of search results without leaving the terminal.


title: CUSTOMIZATION AND CONFIGURATION
content:
`googler` can be extensively customized through environment variables (e.g., <i>GOOGLER_SHOW_ARCHIVED</i>) or a configuration file, typically located at <i>~/.config/googler/config</i>. This allows users to set default options like the number of results, color scheme, or preferred browser, tailoring the tool to their specific workflow.


title: HISTORY
content:
The `googler` command-line utility was initially developed by <i>Arun Prakash Jana</i> to provide a convenient and efficient way to perform Google searches directly from the terminal. Since its inception, it has evolved as an open-source project, maintained by a community of contributors on GitHub. Its development has focused on maintaining compatibility with Google's evolving search interfaces while ensuring a fast, lightweight, and privacy-respecting user experience, making it a popular choice among command-line enthusiasts and developers.


title: SYNOPSIS
content:
<i>Not a standard, user-invokable command.</i><br>Typically invoked internally by Google applications for telemetry collection.<br>No publicly documented command-line syntax for direct user execution.


title: PARAMETERS
content:
<b><i>(No publicly documented parameters)</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;As an internal utility, <b>gotelemetry</b> does not have user-facing command-line parameters for direct invocation. Any operational parameters it uses are likely managed internally by the applications that utilize it.<br><br>


title: DESCRIPTION
content:
gotelemetry is <i>not a standard, user-facing Linux command</i>. It is primarily an <b>internal component</b> or library used within Google's software ecosystem, notably by applications like the <b>Google Cloud SDK</b> or various <b>Go-based tools</b> developed by Google. Its main purpose is to collect <i>anonymous usage statistics and diagnostic information</i> from these applications. This data typically helps Google improve its products and services, identify issues, and understand usage patterns.<br><br>Users generally do not invoke <b>gotelemetry</b> directly from the command line; rather, it is executed automatically by the Google applications it supports, often running in the background to transmit telemetry data. Due to its internal nature, detailed public documentation regarding its specific command-line invocation, options, or behavior is generally unavailable.


title: CAVEATS
content:
<b>gotelemetry</b> is <i>not a standalone utility</i> intended for direct user interaction. Its functionality is opaque to the end-user, and attempting to execute it manually may result in errors or unintended behavior. Users concerned about telemetry data collection should refer to the documentation of the specific Google application (e.g., <b>gcloud</b>) that might be utilizing this component, as those applications usually provide options to enable or disable telemetry reporting.


title: PURPOSE
content:
<i>Background data collection.</i><br>This utility operates in the background, initiated by other Google programs, to transparently gather operational metrics and usage data, assisting in product development and debugging.


title: USER CONTROL
content:
<i>Configured via parent applications.</i><br>Users typically control whether telemetry is collected through settings within the parent Google application (e.g., `gcloud config set component_manager/disable_auto_telemetry true`), not directly via the <b>gotelemetry</b> command itself.


title: HISTORY
content:
The <b>gotelemetry</b> concept or package has evolved within Google's internal development, primarily to facilitate usage data collection for its growing suite of cloud services and developer tools. Its development is tied to the need for understanding product usage and improving software quality across various Google applications built using Go. It originated as an internal mechanism rather than a publicly released standalone tool.


title: PARAMETERS
content:
<b><code>--port <port></code></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the port number for the web server to listen on. <br><i>Default: 8080</i><br><br><b><code>--host <address></code></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Defines the host address to bind the web server to. <br><i>Default: 0.0.0.0</i><br><br><b><code>--permit-write</code></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Allows clients to send input to the TTY, enabling interactive sessions. <br><i>Default: Read-only</i><br><br><b><code>--credential <user:pass></code></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables basic authentication for access to the web terminal with specified username and password.<br><br><b><code>--once</code></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Instructs <b>gotty</b> to exit automatically when the last client disconnects.<br><br><b><code>--ssl</code></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables SSL/TLS encryption for secure communication. Requires <code>--ssl-crt</code> and <code>--ssl-key</code>.<br><br><b><code>--ssl-crt <path></code></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Path to the SSL/TLS certificate file (.crt or .pem).<br><br><b><code>--ssl-key <path></code></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Path to the SSL/TLS private key file (.key or .pem).<br><br><b><code>--index <path></code></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies an HTML file to serve as the custom index page for the web interface.<br><br><b><code>--config <path></code></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Path to a YAML configuration file to load options from.<br><br><b><code>--max-clients <num></code></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the maximum number of concurrent client connections allowed.<br><br>


title: DESCRIPTION
content:
<b>Gotty</b> is a simple command-line tool that turns your terminal, or a specific program, into a web application. Written in Go, it launches a web server that streams terminal output to a web browser using WebSockets. This allows users to access a live terminal session remotely without traditional SSH. It's particularly useful for <I>demonstrations</I>, <I>online tutorials</I>, or providing web-based access to specific command-line tools. Gotty supports various features like SSL/TLS encryption, basic authentication, configurable host/port, and the ability to permit client input. Its single-binary distribution makes it easy to deploy across different platforms.


title: CAVEATS
content:
<b>Security Risk</b>: Exposing a full shell with <code>--permit-write</code> to the public internet can be a significant security risk. Consider running specific, sandboxed commands instead of a full shell.<br><b>Resource Usage</b>: Each connected client consumes server resources. High concurrent usage might impact performance.<br><b>Browser Compatibility</b>: Relies on modern web browser features, specifically WebSockets, for real-time communication.


title: DEFAULT COMMAND EXECUTION
content:
If no specific command is provided as an argument, <b>gotty</b> defaults to executing the user's login shell (e.g., <code>/bin/bash</code> or <code>/bin/zsh</code>). This means a full interactive terminal session is exposed by default.


title: WEBSOCKET COMMUNICATION
content:
<b>Gotty</b> heavily relies on <I>WebSockets</I> for real-time, bidirectional communication between the server and the client's web browser. This technology enables a fluid and responsive terminal experience directly within the browser.


title: STATIC FILE SERVING
content:
Beyond the terminal itself, <b>gotty</b> can serve static files from a specified directory. This feature allows for custom styling, branding, or the inclusion of additional web content alongside the terminal interface.


title: HISTORY
content:
<b>Gotty</b> was created by Shota Fukumori (sugyan) and is written in the Go programming language. Its development aimed to provide a lightweight, cross-platform, and easy-to-deploy solution for sharing terminal sessions over the web, leveraging Go's strong networking capabilities and single-binary compilation. It emerged as a simpler alternative to more complex setups involving terminal multiplexers and WebSocket proxies.


title: PARAMETERS
content:
<b><I>-r</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies that the input Gould image file is in the Gould R format. Use this if you are certain of the input format.<br><br><b><I>-s</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies that the input Gould image file is in the Gould S format. If neither <I>-r</I> nor <I>-s</I> is provided, <b>gouldtoppm</b> attempts to automatically detect the format. Explicitly specifying the format is recommended for reliability.<br><br><b><I>-verbose</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints informational messages about the conversion process, such as detection results or progress, to standard error (stderr).<br><br><b><I>filename</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The path to the input Gould image file. If this argument is omitted, <b>gouldtoppm</b> reads the image data from standard input (stdin).<br><br>


title: DESCRIPTION
content:
<b>gouldtoppm</b> is a utility from the <I>Netpbm</I> package that converts image files in the Gould R or Gould S format into a <I>PPM</I> (Portable Pixmap) image. The Gould formats are specific to older Gould/SEL computer systems, making this tool essential for handling legacy graphic data. The output <I>PPM</I> file, a simple and widely supported image format, can then be easily processed by other <I>Netpbm</I> tools or converted to other standard image formats like <I>PNG</I>, <I>JPEG</I>, or <I>GIF</I> using utilities like <b>ppmtogif</b>, <b>ppmtopng</b>, etc. By default, it reads the Gould image from standard input and writes the <I>PPM</I> image to standard output, adhering to the Unix philosophy of composable tools.


title: CAVEATS
content:
<b>gouldtoppm</b> is specifically designed for legacy Gould R and Gould S image formats. It will not process other common image formats (e.g., JPEG, PNG, TIFF) directly. The input file must strictly conform to the expected Gould format, otherwise, the conversion may fail or produce corrupted output. This tool is part of the <I>Netpbm</I> suite and requires the <I>Netpbm</I> package to be installed on your system.


title: INPUT/OUTPUT BEHAVIOR
content:
By default, <b>gouldtoppm</b> reads the Gould image data from standard input (<I>stdin</I>) and writes the resulting <I>PPM</I> image to standard output (<I>stdout</I>). This design allows for seamless integration with other commands through piping, for example: <br><code>cat old_image.gould | gouldtoppm -s > new_image.ppm</code> <br>or <br><code>gouldtoppm -r input.gould > output.ppm</code>.


title: NETPBM INTEGRATION
content:
As a member of the <I>Netpbm</I> suite, <b>gouldtoppm</b> adheres to the Unix philosophy of small, specialized tools that can be chained together. The output <I>PPM</I> file, being a 'portable pixmap', can be further manipulated by dozens of other <I>Netpbm</I> utilities (e.g., <b>ppmscale</b>, <b>ppmdither</b>) or easily converted to a multitude of other graphics formats (e.g., <I>GIF</I>, <I>PNG</I>, <I>JPEG</I>).


title: HISTORY
content:
<b>gouldtoppm</b> is a component of the <I>Netpbm</I> project, a comprehensive collection of graphics utilities that originated from the <I>pbmplus</I> package developed by Jef Poskanzer in the late 1980s and early 1990s. The <I>Netpbm</I> suite has evolved significantly, becoming a widely adopted toolkit for image manipulation on Unix-like systems. Tools like <b>gouldtoppm</b> were created to fulfill the need for converting various historical and specialized image formats into a common, easily processable standard like <I>PPM</I>, <I>PGM</I>, and <I>PBM</I>, thereby ensuring interoperability and facilitating the preservation of data from legacy systems.


title: SYNOPSIS
content:
<br><code>gource [<i>OPTIONS</i>] [<i>PATH_TO_REPOSITORY</i> | <i>LOG_FILE</i>]</code><br><br><b>Examples:</b><br><code>gource ~/my_git_repo</code><br><code>git log --pretty=format:':%ct|%an|%s' --reverse | gource --log-format custom</code>


title: PARAMETERS
content:
<b>-s <seconds>, --seconds-per-day <seconds></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set the simulation speed, representing how many seconds of development time pass per second of real time.<br><br><b>-a <seconds>, --auto-skip-seconds <seconds></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Automatically skip periods of inactivity longer than the specified seconds.<br><br><b>-r <path>, --repository-root <path></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the root directory of the repository, useful if Gource can't automatically detect it.<br><br><b>-p <position>, --start-position <position></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Start playback at a specific percentage (0.0 to 1.0) of the total repository history.<br><br><b>-e <date>, --start-date <YYYY-MM-DD></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Begin the visualization from a specific date.<br><br><b>-D <date>, --stop-date <YYYY-MM-DD></b><br>&nbsp;&nbsp;&nbsp;&nbsp;End the visualization at a specific date.<br><br><b>-U <dir>, --user-image-dir <dir></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify a directory containing user face images (e.g., <code>username.png</code>) to display as avatars.<br><br><b>-c, --hide-filenames</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Hide individual filenames, only showing the directory tree structure.<br><br><b>-f, --fullscreen</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Run Gource in fullscreen display mode.<br><br><b>-o <file>, --output <file></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Output the visualization to a specified file (e.g., <code>output.ppm</code> for raw video streams).<br><br><b>--title <title></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set the title string displayed in the Gource window.<br><br><b>--logo <file></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display a project logo image in the visualization.<br><br><b>--font-size <size></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Adjust the font size used for text elements in the visualization.<br><br><b>--file-idle-time <seconds></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set the time (in seconds) after which an unmodified file will disappear from the tree.<br><br><b>--max-files <N></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Limit the maximum number of files that can be displayed simultaneously.<br><br><b>--log-format <format></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the input log format (e.g., <code>git</code>, <code>svn</code>, <code>mercurial</code>, <code>custom</code>).<br><br><b>--key</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display an on-screen key or legend for colours and elements.<br><br><b>--stop-at-end</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Stop the simulation automatically once the entire log history has been processed.<br><br>


title: DESCRIPTION
content:
Gource is an animated visualization tool for software version control repositories, transforming static commit logs into a captivating real-time display. It graphically represents the project's history as a dynamic tree structure, where files and directories are nodes that appear, disappear, and change over time. Developers, depicted as user avatars or names, fly into the tree, interact with files, and contribute their changes, with file modifications highlighted visually. Gource supports various version control systems including Git, Mercurial, SVN, and Bazaar, and can also process custom log formats. This provides a unique and intuitive insight into a project's evolution, illustrating bursts of activity, file additions, deletions, and modifications. It vividly demonstrates the collaborative nature of software development and is frequently employed to generate compelling project overview videos, making complex development histories easily understandable and engaging.


title: CAVEATS
content:
Gource can be resource-intensive for very large repositories with extensive history, potentially leading to slow frame rates or high memory usage. It relies on accurate version control system logs; malformed logs can cause unexpected behavior. Generating high-quality video output often requires post-processing with external tools like FFmpeg. The default visualization may become cluttered for projects with very high concurrent activity or numerous files, necessitating parameter tuning.


title: CUSTOM LOG FORMATS
content:
Gource is highly versatile due to its support for custom log formats, allowing users to visualize data from sources beyond standard VCS systems. The custom format typically involves lines structured as <code>:timestamp|author|type|file/directory</code>, where <code>type</code> can be <code>A</code> (add), <code>M</code> (modify), or <code>D</code> (delete). This flexibility enables the creation of visualizations from virtually any time-series data related to file or directory changes, making it a powerful tool for various data analysis scenarios.


title: USER AVATARS
content:
For a more personalized and clear visualization, Gource supports displaying custom images (avatars) for each user. By placing PNG or JPG image files named after the commit author (e.g., <code>john.doe.png</code>) in a directory specified by the <code>--user-image-dir</code> option, users can enhance the visual appeal and easily identify who is contributing to the project at a glance.


title: VIDEO EXPORT
content:
While Gource provides real-time rendering, one of its primary use cases is exporting the visualization to a video file for sharing or presentation. This is commonly achieved by piping Gource's raw PPM stream output to a powerful video encoder like FFmpeg. This allows users to create high-quality, shareable videos of their project's entire development history, complete with sound if desired, for archival or promotional purposes.


title: HISTORY
content:
Gource was created by Andrew Light in 2009. It was initially designed to visualize Git repositories but quickly expanded to support other version control systems like Mercurial, SVN, and Bazaar. Its development was driven by the desire to provide a visually engaging and intuitive way to understand project evolution and developer contributions over time. Since its inception, it has gained popularity in open-source communities and businesses alike for its unique ability to bring static version control logs to life.


title: PARAMETERS
content:
<b>-i, --interval <seconds></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the update interval for watching, specified in seconds. Defines how often the command is re-executed or files are re-checked.<br><br><b>-f, --filter <pattern></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Filters the output using a regular expression pattern. Only lines matching the pattern would be displayed.<br><br><b>-t, --transform <script></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Applies an `awk` or `sed`-like transformation script to each line of output, allowing for complex formatting or data extraction.<br><br><b>-n, --lines <num></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays only the last N lines of the output, similar to the `tail -n` command.<br><br><b>-q, --quiet</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Suppresses the initial output. The command would only display output when changes occur.<br><br><b>-c, --clear</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Clears the screen before each update, similar to the `watch -c` command, providing a clean display of the latest information.<br><br>


title: DESCRIPTION
content:
It is crucial to understand that <b>gow</b> is <B>not</B> a standard, pre-installed command found in most mainstream Linux distributions. While a command with this exact name is highly uncommon in a typical Linux environment, if it were to exist, it would conceptually function as a utility for <i><b>g</b>enerating <b>o</b>utput and <b>w</b>atching</i> changes in real-time.<br><br>Such a hypothetical tool might combine functionalities found in commands like <b>watch</b>, <b>tail</b>, <b>grep</b>, and <b>awk</b>. It could enable users to monitor file changes, filter log streams, or periodically execute commands and display their formatted output. It would be useful for live system monitoring, debugging applications by observing log files, or tracking specific data patterns as they emerge. Its non-standard nature suggests that any `gow` command encountered would likely be a custom script, an alias, or part of a highly specialized, niche toolchain, with its purpose entirely dependent on its specific implementation.


title: CAVEATS
content:
It is crucial to emphasize that <b>gow</b> is <B>not</B> a standard, universally recognized Linux command. It is highly unlikely to be pre-installed on any typical Linux distribution. Any `gow` command encountered would almost certainly be a custom shell script, an alias configured by a user or administrator, or part of a very specific, non-mainstream software package. Therefore, its actual functionality, options, and behavior would entirely depend on its unique implementation. Users should not expect `gow` to be available by default or to behave consistently across different systems.


title: CUSTOM IMPLEMENTATIONS
content:
Due to its non-standard nature, a command named `gow` is most likely a custom script written in Bash, Python, or another scripting language. Its features would be entirely defined by the script's author, tailored to a specific set of requirements.


title: ALIAS POTENTIAL
content:
It's possible that `gow` is simply an alias configured in a user's shell startup files (e.g., `~/.bashrc`, `~/.zshrc`) to execute a longer, more complex command or a sequence of commands, providing a convenient shortcut.


title: HISTORY
content:
As <b>gow</b> is not a standard Linux command, it does not have a documented history of development within the mainstream Linux ecosystem. If such a command were to exist, its origin would likely stem from a developer's need to automate specific monitoring or log analysis tasks. It would typically start as a complex shell script that might evolve into a standalone utility for personal or project-specific use. It represents a common pattern in Linux where users create custom tools to combine existing command functionalities for greater efficiency.


title: PARAMETERS
content:
<b>-os OS[,OS...]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the target operating system(s) (e.g., <i>linux, windows, darwin</i>). Multiple values can be comma-separated.<br><br><b>-arch ARCH[,ARCH...]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the target architecture(s) (e.g., <i>amd64, 386, arm, arm64</i>). Multiple values can be comma-separated.<br><br><b>-output PATH</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the output path for the built binaries. Can use placeholders like <i>{{.OS}}, {{.Arch}}, {{.Dir}}, {{.Basename}}</i> for dynamic naming. Example: <i>"dist/{{.OS}}_{{.Arch}}/{{.Basename}}"</i>.<br><br><b>-ldflags LDFLAGS</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Arguments to pass to the Go linker (<i>-ldflags</i>).<br><br><b>-tags TAGS</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Arguments to pass to the Go compiler (<i>-tags</i>), used for conditional compilation.<br><br><b>-verbose</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enable verbose output, showing commands being executed.<br><br><b>-rebuild</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Force a rebuild of packages, ignoring the build cache.<br><br><b>-parallel COUNT</b><br>&nbsp;&nbsp;&nbsp;&nbsp;The number of parallel builds to run. Defaults to the number of CPU cores.<br><br><b>-path PATH</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Path to the Go packages to build. Defaults to the current directory (<i>./...</i>).<br><br><b>-cgo</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enable CGO support for cross-compilation. Note: Cross-compiling with CGO can be complex and may require additional setup (e.g., target C toolchains).<br><br>


title: DESCRIPTION
content:
<i>gox</i> is a powerful utility designed to automate and simplify the process of cross-compiling Go applications for various operating systems and architectures. Traditionally, cross-compiling a Go program involves manually setting <b>GOOS</b> and <b>GOARCH</b> environment variables for each target platform before running <code>go build</code>. <i>gox</i> abstracts this complexity, allowing developers to specify multiple target OS/ARCH combinations (e.g., Linux, Windows, macOS, x86, ARM) in a single command. It can build simultaneously for these targets, organizing the output binaries into a specified directory structure.<br><br>This tool is particularly useful for projects that need to distribute binaries for a wide range of platforms, significantly streamlining the release process. It's built on top of the standard Go toolchain and integrates seamlessly into existing Go workflows, making it a popular choice for developers seeking efficient cross-platform build solutions.


title: CAVEATS
content:
<b>Go Toolchain Requirement</b>: <i>gox</i> requires a Go development environment to be installed and configured, as it leverages the standard <code>go build</code> command internally.<br><b>CGO Limitations</b>: Cross-compiling Go programs that use CGO (C language bindings) is significantly more complex. It often requires specific C compilers (cross-compilers like <i>gcc-arm-linux-gnueabihf</i>) for each target architecture and OS, which are not automatically managed by <i>gox</i>. This can be a major hurdle for CGO-enabled projects.<br><b>External Dependencies</b>: If your Go application has external C/C++ dependencies linked via CGO, you'll need to ensure those dependencies are available and correctly configured for each target platform, which can be non-trivial.


title: EXAMPLE USAGE
content:
To build for Linux (amd64), Windows (amd64), and macOS (amd64) from the current directory, placing binaries in a <i>bin</i> folder:<br><code>gox -os "linux,windows,darwin" -arch "amd64" -output "bin/{{.OS}}_{{.Arch}}/{{.Basename}}" ./...</code><br>This command demonstrates how to specify multiple targets and control the output directory structure using placeholders.


title: INTEGRATION WITH BUILD SYSTEMS
content:
<i>gox</i> is frequently integrated into automated build systems and CI/CD pipelines (e.g., GitHub Actions, GitLab CI, Jenkins). Its simplicity and command-line interface make it easy to incorporate into scripts for generating release artifacts, ensuring consistent cross-platform builds.


title: HISTORY
content:
<i>gox</i> was developed by <i>Mitchell Hashimoto</i>, co-founder of HashiCorp, known for tools like Vagrant, Terraform, and Vault. It emerged as a practical solution to streamline the release process for Go applications, which often need to be distributed across a variety of operating systems and architectures. Its design philosophy aligns with HashiCorp's focus on automation and ease of use, making it a popular choice for developers looking to simplify their Go build pipelines. While not part of the official Go distribution, it has become a de-facto standard tool in the Go ecosystem for cross-compilation.


title: PARAMETERS
content:
<b><i>device</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the disk device to open, e.g., <i>/dev/sda</i>. If omitted, <b>gparted</b> typically opens the first detected disk.<br><br><b><b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a help message with command usage and options.<br><br><b><b>--version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Outputs the <b>gparted</b> version information.<br><br>


title: DESCRIPTION
content:
<b>gparted</b> is a powerful and intuitive <b>graphical partition editor</b> for Linux-based operating systems. It provides a user-friendly interface to manage disk partitions, allowing users to create, delete, resize, move, copy, check, and label partitions without data loss (though <i>backups are always recommended</i>). <b>gparted</b> supports a wide array of file systems, including common ones like <i>ext2/3/4, FAT16/32, NTFS, btrfs, XFS, JFS, and ReiserFS</i>, as well as Linux swap. It is an essential tool for setting up new hard drives, reorganizing disk space, creating dual-boot systems, or repairing partition tables. Its visual representation of disk layouts makes complex partitioning tasks more accessible to users of all skill levels. <b>gparted</b> typically runs with <i>root privileges</i> and is often used from a live CD/USB environment to ensure no partitions are mounted during critical operations.


title: CAVEATS
content:
<b>Data Loss Risk</b>: While <b>gparted</b> aims for non-destructive operations, errors, power failures, or incorrect usage can lead to data loss. <i>Always back up critical data</i> before performing any disk partitioning operations.<br><b>Root Privileges</b>: <b>gparted</b> requires <i>root privileges</i> to run and modify disk partitions.<br><b>Unmounted Partitions</b>: For most operations (especially resizing or moving), the target partition(s) must be <i>unmounted</i>. This is why <b>gparted</b> is frequently used from a live Linux distribution.<br><b>Time Consuming</b>: Operations like moving or resizing large partitions, especially with data, can take a significant amount of time.<br><b>Apply Operations</b>: Changes are not applied immediately; they are queued and must be explicitly applied by the user via the "Apply All Operations" button.


title: <I>RUNNING FROM LIVE MEDIA</I>
content:
It is highly recommended to run <b>gparted</b> from a <i>live Linux distribution</i> (e.g., a bootable USB stick or DVD) to ensure that no partitions are mounted. This minimizes the risk of data corruption and allows operations on all partitions of the primary disk.


title: <I>DISK SELECTION</I>
content:
When <b>gparted</b> starts, it typically displays the first detected hard disk. Users can select different disk devices (e.g., <i>/dev/sdb</i>, <i>/dev/nvme0n1</i>) from a dropdown menu in the top right corner of the interface.


title: HISTORY
content:
<b>gparted</b> was initially developed by <i>Curtis Gedak</i> and first released around 2004. It quickly gained popularity as a user-friendly graphical frontend for the powerful <b>GNU Parted</b> command-line utility. Its design aimed to simplify complex disk management tasks, making them accessible to a wider audience than command-line tools. Over the years, it has become a staple in virtually all major Linux distributions and is a key component of many live Linux rescue CDs and USB drives (like PartedMagic, SystemRescueCD, and Ubuntu Live CDs), enabling users to manage partitions easily without installing an operating system. Continuous development has added support for new file systems and partition table types (like GPT).


title: SEE ALSO
content:
<b>parted(8)</b>: Command-line partition editor, <b>gparted</b>'s backend.<br>, <b>fdisk(8)</b>: Traditional partition table manipulator (primarily MBR).<br>, <b>cfdisk(8)</b>: Curse-based <b>fdisk</b> alternative.<br>, <b>sfdisk(8)</b>: Scriptable partition manipulator.<br>, <b>lsblk(8)</b>: List block devices.<br>, <b>mount(8)</b>: Mount a filesystem.<br>, <b>mkfs(8)</b>: Build a Linux filesystem.


title: SYNOPSIS
content:
<I>gpasswd</I> [<I>OPTIONS</I>] <I>GROUP</I><br><I>gpasswd</I> [-a|-d] <I>USER</I> <I>GROUP</I><br><I>gpasswd</I> [-A|-M] <I>USER,...</I> <I>GROUP</I><br><I>gpasswd</I> [-r|-R] <I>GROUP</I>


title: PARAMETERS
content:
<b>-a <I>user</I> <I>group</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Add <I>user</I> to <I>group</I>.<br><br><b>-d <I>user</I> <I>group</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Delete <I>user</I> from <I>group</I>.<br><br><b>-A <I>user,...</I> <I>group</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set the specified comma-separated list of <I>user</I>s as administrators for <I>group</I>. Existing administrators not in the list are removed.<br><br><b>-M <I>user,...</I> <I>group</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set the specified comma-separated list of <I>user</I>s as members of <I>group</I>. Existing members not in the list are removed.<br><br><b>-r <I>group</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Remove the password for <I>group</I>. Users can no longer use <I>newgrp</I> with a password to join this group unless they are already members.<br><br><b>-R <I>group</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Restrict access to <I>group</I>. This prevents users who are not members of the group from using <I>newgrp</I> with the group's password. It also makes it so that even members must supply the password to <I>newgrp</I> into the group.<br><br><b><I>group</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The name of the group to operate on.<br><br><b><I>user</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The name of the user to operate on (e.g., adding or deleting from a group).<br><br><b><I>user,...</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;A comma-separated list of usernames (used for setting administrators or members).<br><br>


title: DESCRIPTION
content:
The <b>gpasswd</b> command is a utility used to administer the <I>/etc/gshadow</I> file, which stores encrypted group passwords and designated group administrators. It provides a secure way to manage group-related information beyond what basic group management tools like <I>groupmod</I> offer, particularly concerning group passwords and administrator roles.<br><br>With <b>gpasswd</b>, system administrators or designated group administrators can perform various tasks including setting or removing a password for a group (allowing users to join the group via <I>newgrp</I> command if they know the password), adding or removing members from a group, and assigning users as administrators for specific groups. These group administrators are then empowered to manage the membership of their assigned groups without needing root privileges. It's a critical tool for robust and decentralized group management on Linux systems.


title: CAVEATS
content:
Most operations with <b>gpasswd</b> require root privileges. However, a user designated as a group administrator for a specific group can use <b>gpasswd</b> to add or remove members from that particular group. Changes made using <b>gpasswd</b> (especially to group memberships) may not take immediate effect for logged-in users; they might need to log out and log back in, or use the <I>newgrp</I> command to update their group memberships.


title: GROUP ADMINISTRATORS
content:
Users specified with the <I>-A</I> option become group administrators. A group administrator can add or remove users from their managed group using <b>gpasswd</b> without requiring root privileges. This feature enables decentralized management of specific groups, offloading some administrative tasks from the root user.


title: GROUP PASSWORDS
content:
A group password, set by running <b>gpasswd</b> without any options or by root, allows users who are not explicitly members of the group to temporarily join the group using the <I>newgrp</I> command, provided they know the password. This can be useful for granting temporary or conditional access to resources owned by a group without permanently adding users to the group's membership list.


title: HISTORY
content:
<b>gpasswd</b> is part of the <I>shadow-utils</I> package, which provides a set of tools for managing user and group accounts and passwords in a secure manner. Its development was driven by the need to separate sensitive password information into a shadow file (<I>/etc/gshadow</I>), similar to how <I>/etc/shadow</I> works for user passwords. This enhances security by preventing unauthorized access to hashed passwords and allows for features like group administrators.


title: SYNOPSIS
content:
<i>gpclient</i> [<i>--help</i>|<i>-h</i>|<i>--version</i>|<i>-v</i>]<br><i>gpclient</i> <I>subcommand</I> [<i>subcommand_options</i>]


title: PARAMETERS
content:
<b><i>connect</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Initiates a VPN connection to the currently configured GlobalProtect portal. Depending on the portal's authentication settings, this command may trigger a web browser for user interaction (e.g., SAML authentication).<br><br><b><i>disconnect</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Terminates the active VPN connection established by GlobalProtect, severing the secure tunnel.<br><br><b><i>status</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays the current VPN connection status, indicating whether the client is connected or disconnected, the active portal, and the gateway being used.<br><br><b><i>show</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Provides detailed information about the GlobalProtect client's configuration, network details, and connection metrics. Common options include <i>--details</i> for comprehensive information, <i>--all</i> for all available data, and <i>--metrics</i> for performance statistics.<br><br><b><i>set</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Configures GlobalProtect client settings. It is primarily used to specify or update the GlobalProtect portal address.<br>Example: <i>gpclient set --portal <I>vpn.example.com</I></i>.<br><br><b><i>--help</i>, <i>-h</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays general help information for the <i>gpclient</i> command. If used with a subcommand (e.g., <i>gpclient connect --help</i>), it shows help specific to that subcommand.<br><br><b><i>--version</i>, <i>-v</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows the installed GlobalProtect client software version.<br><br>


title: DESCRIPTION
content:
<i>gpclient</i> is the command-line interface component of the Palo Alto Networks GlobalProtect VPN client for Linux. It provides a robust and flexible way for users to manage their VPN connection directly from the terminal, making it ideal for system administrators, developers, and users who prefer a non-graphical approach or need to automate VPN tasks. Through <i>gpclient</i>, users can initiate connections to and disconnect from configured GlobalProtect portals, retrieve real-time connection status, display detailed network and client configuration information, and configure essential portal settings. It acts as a crucial front-end to the underlying GlobalProtect service (<i>PanGPS</i>), facilitating secure network access within enterprise environments without relying on a graphical user interface.


title: CAVEATS
content:
<i>gpclient</i> is a proprietary command-line client developed by Palo Alto Networks for their GlobalProtect VPN solution. It is not included in standard Linux distributions and must be installed separately, usually via a package provided by your organization or Palo Alto Networks. Its functionality is entirely dependent on the underlying <i>PanGPS</i> background service being operational. Certain authentication methods (e.g., SAML, Kerberos) might require a graphical web browser to complete the login process, even when using the command-line interface.


title: BACKGROUND SERVICE: PANGPS
content:
The <i>gpclient</i> command interacts with the essential background GlobalProtect service, <i>PanGPS</i>. This service is responsible for handling the actual VPN tunnel establishment, maintenance, and teardown. For <i>gpclient</i> commands to function correctly, it is crucial to ensure that the <i>PanGPS</i> service is running and accessible.


title: AUTHENTICATION FLOW
content:
Depending on the GlobalProtect portal's configuration, initiating a connection via <i>gpclient connect</i> may not be a purely command-line experience. It can automatically open a web browser for various authentication methods like SAML, Kerberos, or other web-based multi-factor authentication (MFA) flows, requiring user interaction outside the terminal.


title: HISTORY
content:
Palo Alto Networks introduced the GlobalProtect client to provide secure VPN access across various operating systems, including Linux, to extend their enterprise security solutions. The <i>gpclient</i> command-line interface was developed to offer administrators and advanced users a flexible alternative to the graphical user interface, enabling programmatic control over VPN connections and facilitating integration into scripts and automation workflows. Its development is closely tied to the broader GlobalProtect product line's releases and enhancements.


title: PARAMETERS
content:
<b><b>-h</b>, <b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a help message with available options and exits.<br><br><b><b>--status</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows the current status and detailed information of the OpenPGP smart card, including card serial number, key IDs, application details, and remaining PIN tries.<br><br><b><b>--list</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Lists the cryptographic keys (Signature, Encryption, Authentication) currently stored on the smart card, along with their key IDs and capabilities.<br><br><b><b>--change-pin</b> [<i>user</i>|<i>admin</i>|<i>reset</i>]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Allows changing the specified PIN: the <i>user</i> PIN (for daily operations), the <i>admin</i> PIN (for administrative tasks), or the <i>reset</i> code (to unblock a locked user PIN).<br><br><b><b>--admin</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enters administrative mode, enabling access to advanced card management functions and configuration. This operation typically requires the Admin PIN.<br><br><b><b>--import</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Imports existing GnuPG keys from the local keyring onto the smart card. This process securely transfers the private key material to the hardware token.<br><br><b><b>--export</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Exports public keys from the smart card. In some cases, it can prepare private keys for secure export, depending on card capabilities and security policy.<br><br><b><b>--gen-key</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Generates new cryptographic keys (Signature, Encryption, Authentication) directly on the smart card. The private keys are created and stored exclusively on the card, never leaving the hardware, which offers maximum security.<br><br><b><b>--factory-reset</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Performs a <i>destructive</i> factory reset of the smart card, which permanently erases all data, keys, and configurations on the card. <b>Use with extreme caution!</b> This action is irreversible.<br><br><b><b>--send-apdu</b> <i>APDU</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sends a raw Application Protocol Data Unit (APDU) command directly to the smart card. This option is intended for advanced users, diagnostics, and debugging purposes.<br><br><b><b>--fingerprint</b> <i>FINGERPRINT</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the full fingerprint of a particular key to operate on, which is useful when dealing with multiple keys or for specific key management operations.<br><br><b><b>--card-no</b> <i>NUMBER</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Selects a specific smart card by its serial number if multiple smart card readers or cards are detected, allowing precise control over which card to interact with.<br><br>


title: DESCRIPTION
content:
<b>gpg-card</b> is a command-line utility within the GnuPG suite designed to interact with and manage OpenPGP smart cards. It acts as a user-friendly interface to <b>scdaemon</b>, the smart card daemon, enabling users to view card status, manage PINs (User, Admin, Reset Code), import or generate cryptographic keys directly on the card, and perform administrative tasks such as resetting the card to factory defaults. This tool is essential for users leveraging hardware security modules to protect their GnuPG keys and enhance their cryptographic operations, providing a robust layer of security for digital signatures and encryption. It simplifies complex interactions with the card hardware, making advanced cryptographic key management accessible from the command line.


title: CAVEATS
content:
Using <b>gpg-card</b> inherently requires a compatible OpenPGP smart card and a functioning smart card reader connected to the system. <br><br>Administrative operations, particularly <b>--factory-reset</b>, are highly sensitive and irreversible. Incorrect usage can lead to permanent data loss on the card. Always ensure you have backups of your keys if needed before performing destructive actions. Repeated incorrect entries of the Admin PIN can permanently lock the card from certain administrative functions.


title: SECURITY IMPLICATIONS
content:
Leveraging <b>gpg-card</b> with an OpenPGP smart card significantly boosts the security of your GnuPG keys. By moving private keys into a tamper-resistant hardware module, they are protected from software-based attacks, malware, and unauthorized access, making them more resilient than keys stored solely on a computer's file system. This hardware-backed security is crucial for high-value cryptographic operations.


title: PIN MANAGEMENT BEST PRACTICES
content:
Proper management of the User PIN, Admin PIN, and Reset Code is paramount for the security and usability of your OpenPGP smart card. <br>The <i>User PIN</i> protects day-to-day operations like signing or decrypting. <br>The <i>Admin PIN</i> controls sensitive administrative functions such as key generation, import, and card resets. <br>The <i>Reset Code</i> can unblock a locked User PIN without a factory reset. <br>Forgetting the Admin PIN or exceeding the number of incorrect PIN entries can render parts of the card unusable or even permanently lock it, potentially requiring a factory reset and loss of all stored keys.


title: HISTORY
content:
<b>gpg-card</b> emerged as a vital utility within the GnuPG project, which was initiated by Werner Koch in 1997. As the adoption of OpenPGP smart cards grew for secure key storage, GnuPG integrated robust support for these hardware tokens. <b>gpg-card</b> became the primary command-line interface for managing these devices, evolving alongside the OpenPGP card specifications to provide a secure and user-friendly method for handling cryptographic keys directly on hardware, enhancing the overall security posture of GnuPG users.


title: PARAMETERS
content:
<b><b>-h</b>, <b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays the help message and exits.<br><br><b><b>-v</b>, <b>--version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints version information and exits.<br><br>


title: DESCRIPTION
content:
<b>gpg-tui</b> is a modern, interactive <i>terminal user interface (TUI)</i> for GnuPG (GNU Privacy Guard). It aims to simplify the often complex process of managing GPG keys directly from the command line. Unlike traditional command-line <i>gpg</i> operations that can require remembering numerous commands and flags, <b>gpg-tui</b> provides a menu-driven, graphical-like experience within the terminal.<br><br>Users can easily view their public and private keys, import/export keys, sign and encrypt files, revoke keys, and perform other common GPG tasks through intuitive keyboard shortcuts and navigation. It's designed to be more accessible for users who prefer a visual interface without leaving their terminal environment, enhancing productivity and reducing the learning curve associated with GnuPG. It's built with Rust and provides a responsive and clean interface.


title: CAVEATS
content:
<b>gpg-tui</b> functions as a front-end to the underlying <i>gpg</i> system. It requires <i>gpg</i> to be installed and properly configured on the system. While it simplifies interactions, users should still possess a basic understanding of GnuPG concepts and best practices for secure key management. It does not replace the core <i>gpg</i> functionality or its cryptographic security model but rather provides a more approachable interface.


title: HISTORY
content:
<b>gpg-tui</b> is a relatively recent addition to the GnuPG tooling ecosystem, developed to provide a more interactive and user-friendly experience within the terminal. Its creation addresses the demand for visual interfaces that don't rely on full desktop environments, catering to terminal-centric workflows. It leverages modern <i>TUI frameworks</i> (like <i>tui-rs</i>) and programming languages (<i>Rust</i>) to deliver a responsive and aesthetically pleasing application. The development of <b>gpg-tui</b> reflects a broader trend in the Linux community towards building rich, interactive command-line applications that enhance productivity and accessibility for traditionally complex tasks.


title: SYNOPSIS
content:
<b>gpg-zip</b> [<I>options</I>] <I>files...</I><br><b>gpg-zip</b> <I>-d</I> <I>encrypted_file.gpg</I>


title: PARAMETERS
content:
<b><b>-r</b> <I>RECIPIENT</I>, <b>--recipient</b> <I>RECIPIENT</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the recipient's user ID, name, or fingerprint for public-key encryption. Multiple <b>-r</b> options can be used for multiple recipients.<br><br><b><b>-c</b>, <b>--symmetric</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Encrypts with a symmetric cipher using a passphrase. The passphrase will be prompted interactively unless provided via <b>--passphrase</b>.<br><br><b><b>-o</b> <I>FILE</I>, <b>--output</b> <I>FILE</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the name of the output file. If not provided, a default name (e.g., <i>archive.zip.gpg</i> for encryption) is used.<br><br><b><b>-d</b>, <b>--decompress</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Decrypts and decompresses the specified <i>.gpg</i> archive.<br><br><b><b>-v</b>, <b>--verbose</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows more detailed output about the encryption and archiving process.<br><br><b><b>-z</b> <I>LEVEL</I>, <b>--compress-level</b> <I>LEVEL</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the compression level for <b>zip</b> (0-9). 0 means no compression, 9 means best compression.<br><br><b><b>-f</b>, <b>--force</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Overwrites the output file if it already exists without prompting.<br><br><b><b>--gpg-path</b> <I>PATH</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the full path to the <b>gpg</b> executable.<br><br><b><b>--zip-path</b> <I>PATH</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the full path to the <b>zip</b> executable.<br><br>


title: DESCRIPTION
content:
<b>gpg-zip</b> is a utility that simplifies the process of encrypting and archiving multiple files. It acts as a wrapper around the <b>zip</b> archiving tool and the <b>gpg</b> (GnuPG) encryption suite.<br><br>Its primary purpose is to create secure, compressed archives suitable for distribution or backup. Instead of manually piping <b>zip</b> output to <b>gpg</b>, <b>gpg-zip</b> automates this sequence. Users can choose between symmetric (passphrase-based) and asymmetric (public-key-based) encryption.<br><br>When encrypting, it typically first compresses the input files into a <i>.zip</i> archive, then encrypts this archive using GnuPG. When decrypting, it reverses the process: decrypts the <i>.gpg</i> file and then extracts the contents of the <i>.zip</i> archive. This integration makes it convenient for users who need to bundle and protect multiple documents or data sets securely.


title: CAVEATS
content:
<b>Dependency:</b> <b>gpg-zip</b> is typically a shell script that relies on both <b>gpg</b> (GnuPG) and <b>zip</b> being installed and accessible in the system's PATH. If either is missing, the command will fail.<br><br><b>Passphrase Security:</b> Using the <b>--passphrase</b> option directly on the command line is generally insecure as the passphrase might be visible in process listings (e.g., <b>ps -ef</b>) or command history. It's recommended to allow <b>gpg-zip</b> or GnuPG to prompt for the passphrase interactively.<br><br><b>Temporary Files:</b> During operation, <b>gpg-zip</b> may create temporary files for the zipped archive before encryption or after decryption. These are usually cleaned up automatically, but in rare cases of unexpected termination, they might remain.<br><br><b>Wrapper Limitations:</b> As a wrapper script, <b>gpg-zip</b> might not expose all advanced options of <b>gpg</b> or <b>zip</b>. For highly specific or complex scenarios, directly chaining <b>zip</b> and <b>gpg</b> commands might be necessary.


title: ENCRYPTION MODES
content:
<b>gpg-zip</b> supports two primary encryption modes via GnuPG:<br><br><I>Public-key encryption:</I> Activated using the <B>-r</B> or <B>--recipient</B> option. This mode encrypts the archive for one or more specific recipients whose public keys are known to GnuPG. Only the holders of the corresponding private keys can decrypt the archive.<br><br><I>Symmetric encryption:</I> Activated using the <B>-c</B> or <B>--symmetric</B> option. This mode encrypts the archive using a passphrase that you provide. Anyone with the correct passphrase can decrypt the archive. This is often used for self-encrypted backups or when sharing with individuals not using GnuPG key pairs.


title: WORKFLOW
content:
The typical workflow for <b>gpg-zip</b> involves:<br><br><I>Encryption:</I><br><I>a. Compression:</I> The specified input files are first compressed into a temporary <I>.zip</I> archive.<br><I>b. Encryption:</I> This temporary <I>.zip</I> archive is then encrypted using GnuPG, resulting in a <I>.zip.gpg</I> (or similar) file.<br><br><I>Decryption:</I><br><I>a. Decryption:</I> The <I>.zip.gpg</I> file is decrypted using GnuPG (requiring the correct passphrase or private key).<br><I>b. Decompression:</I> The resulting temporary <I>.zip</I> archive is then decompressed, extracting the original files.<br><br>This automated two-step process simplifies secure multi-file management.


title: HISTORY
content:
<b>gpg-zip</b> is not a standalone project with a long, distinct history like GnuPG itself. It emerged as a convenient wrapper script, often distributed alongside GnuPG as part of its utilities or examples, to simplify a common cryptographic workflow: bundling multiple files, compressing them, and then encrypting the resulting archive.<br><br>Its development focus has been on providing a user-friendly abstraction over the manual piping of <b>zip</b> to <b>gpg</b>, reflecting a common need among users for secure multi-file archiving. It leverages the mature and robust capabilities of <b>gpg</b> for encryption and <b>zip</b> for compression, rather than reinventing these functionalities.


title: SYNOPSIS
content:
<b>gpg2</b> [<i>options</i>] [<i>files</i>]<br><br>Common usage examples:<br><b>gpg2</b> --encrypt --recipient <i>user@example.com</i> <i>file.txt</i><br><b>gpg2</b> --decrypt <i>file.txt.gpg</i><br><b>gpg2</b> --sign <i>document.pdf</i><br><b>gpg2</b> --verify <i>signature.sig</i> [<i>signed-file</i>]<br><b>gpg2</b> --list-keys<br><b>gpg2</b> --gen-key


title: PARAMETERS
content:
<b>--encrypt, -e</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Encrypt data for specified recipients.<br><br><b>--decrypt, -d</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Decrypt data. Output is typically written to stdout or a file.<br><br><b>--sign, -s</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Make a detached signature of the input file.<br><br><b>--clearsign</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Make a cleartext signature, embedding the signature in the text.<br><br><b>--verify</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Verify a signature against a file or stdin.<br><br><b>--recipient <i>user-id</i>, -r <i>user-id</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Encrypt for the specified user or key ID.<br><br><b>--output <i>file</i>, -o <i>file</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Write output to the specified file.<br><br><b>--armor, -a</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Create ASCII armored output, suitable for email or text transfer.<br><br><b>--list-keys, -k</b><br>&nbsp;&nbsp;&nbsp;&nbsp;List public keys in the keyring.<br><br><b>--list-secret-keys, -K</b><br>&nbsp;&nbsp;&nbsp;&nbsp;List secret (private) keys in the keyring.<br><br><b>--import</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Import keys from a file or stdin into the keyring.<br><br><b>--export</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Export keys from the keyring to stdout or a file.<br><br><b>--gen-key</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Generate a new OpenPGP key pair interactively.<br><br><b>--delete-secret-keys</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Delete secret keys from the keyring.<br><br><b>--delete-keys</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Delete public keys from the keyring.<br><br><b>--edit-key</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enter an interactive key editing shell.<br><br><b>--refresh-keys</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Refresh public keys from a configured key server.<br><br><b>--batch</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Run in batch mode, avoiding interactive prompts where possible.<br><br>


title: DESCRIPTION
content:
<b>gpg2</b> is the primary command-line tool for the GnuPG 2.x suite, providing a robust and free implementation of the OpenPGP standard (RFC 4880). It enables users to encrypt and decrypt files, sign and verify digital signatures, and manage their OpenPGP keys. Unlike its predecessor <i>gpg</i> (GnuPG 1.x), <b>gpg2</b> is designed with a more modular architecture, heavily relying on components like <i>gpg-agent</i> for passphrase caching and <i>scdaemon</i> for smart card integration.<br><br>This separation of concerns enhances security and usability by centralizing sensitive operations. <b>gpg2</b> is widely used for securing email, documents, and code, ensuring confidentiality, integrity, and authenticity through cryptographic operations. It supports various algorithms and key types, making it a versatile tool for privacy-conscious users and developers alike.


title: CAVEATS
content:
<b>gpg2</b> relies heavily on <i>gpg-agent</i> for passphrase management and private key operations. Issues with <i>gpg-agent</i> (e.g., not running, misconfigured) can prevent <b>gpg2</b> from functioning correctly.<br><br>While `--passphrase` exists, it's generally discouraged due to security risks; it exposes the passphrase in command history and process lists. Prefer using <i>gpg-agent</i> for passphrase caching.


title: KEYRING MANAGEMENT
content:
<b>gpg2</b> stores all cryptographic keys (public and private) in a GnuPG home directory, typically <i>~/.gnupg</i>. This directory also contains the trust database and configuration files. Proper management and backup of this directory are crucial for retaining control over your cryptographic identities.


title: WEB OF TRUST
content:
GnuPG implements a 'Web of Trust' model, where users can sign other users' public keys to indicate their validity. This system provides an alternative to centralized Certificate Authorities. <b>gpg2</b> allows users to manage and express their trust relationships, influencing how keys are validated.


title: AGENT INTERACTION
content:
A core feature of <b>gpg2</b> is its seamless interaction with <i>gpg-agent</i>. Whenever a private key operation (like signing or decrypting) is required, <b>gpg2</b> communicates with the agent, which handles passphrase prompts and caching. This centralizes passphrase management, reducing the number of times a passphrase needs to be entered and enhancing overall system security.


title: HISTORY
content:
GnuPG was originally created by Werner Koch, with <i>gpg</i> (GnuPG 1.x) being the initial stable series. The development of <i>gpg2</i> (GnuPG 2.x) introduced a significant architectural shift, moving towards a more modular design. This led to the creation of separate daemons like <i>gpg-agent</i> (for passphrase caching and private key handling), <i>scdaemon</i> (for smart card integration), and <i>dirmngr</i> (for key server interactions).<br><br>The <b>gpg2</b> series is now the recommended and actively developed branch, improving security by isolating sensitive operations and offering greater flexibility. On many modern Linux distributions, the command <i>gpg</i> is often a symbolic link to <b>gpg2</b>, signifying its status as the default and preferred GnuPG client.


title: SYNOPSIS
content:
<b>gpgconf</b> [<i>options</i>] [<i>component</i> [<i>variable</i> [<i>value</i>]]]<br><b>gpgconf</b> <i>--list-options</i> [<i>component</i>]<br><b>gpgconf</b> <i>--show-options</i> [<i>component</i>]<br><b>gpgconf</b> <i>--change-options</i> [<i>component</i>]<br><b>gpgconf</b> <i>--reload</i> [<i>component</i>]


title: PARAMETERS
content:
<b><i>component</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the GnuPG component (e.g., <i>gpg</i>, <i>gpg-agent</i>, <i>gpgsm</i>, <i>scdaemon</i>) to configure.<br><br><b><i>variable</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The specific configuration variable to operate on.<br><br><b><i>value</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The new value to assign to the configuration <i>variable</i>.<br><br><b><b>--list-options</b> [<i>component</i>]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Lists all available configuration options for the specified <i>component</i>, or all components if none is given.<br><br><b><b>--list-components</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Lists all GnuPG components whose configurations can be managed by <i>gpgconf</i>.<br><br><b><b>--show-options</b> [<i>component</i>]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays the currently effective configuration options and their values for the specified <i>component</i>.<br><br><b><b>--change-options</b> [<i>component</i>]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enters an interactive mode to modify configuration options for a <i>component</i>. Useful for one-time changes.<br><br><b><b>--reload</b> [<i>component</i>]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Instructs the specified <i>component</i> (e.g., <i>gpg-agent</i>) to reload its configuration from disk, applying recent changes.<br><br><b><b>--kill</b> [<i>component</i>]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Terminates the specified running GnuPG <i>component</i> (e.g., <i>gpg-agent</i>), allowing it to restart with new settings.<br><br><b><b>--launch</b> [<i>component</i>]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Ensures the specified <i>component</i> is running; launches it if it's not already active.<br><br><b><b>--homedir</b> <i>dir</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies an alternative GnuPG home directory instead of the default (~/.gnupg).<br><br><b><b>-v</b>, <b>--verbose</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables more verbose output, providing additional details about operations.<br><br><b><b>-q</b>, <b>--quiet</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Suppresses informational output, showing only critical errors or requested data.<br><br><b><b>--version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints the version information of <i>gpgconf</i> and exits.<br><br>


title: DESCRIPTION
content:
The <i>gpgconf</i> command is a vital utility within the GNU Privacy Guard (GnuPG) suite, designed for comprehensive management of configuration settings across its various components. These components include, but are not limited to, <i>gpg</i>, <i>gpg-agent</i>, <i>gpgsm</i>, and <i>scdaemon</i>. <i>gpgconf</i> provides a centralized and programmatic interface to view, set, or unset configuration parameters, eliminating the need to manually edit potentially scattered and complex configuration files. It's an indispensable tool for customizing GnuPG's behavior, especially in scripting and automated environments where precise control over GnuPG's operational aspects is required. It can list all available options for each component, display their current values, and apply modifications, ensuring that changes are applied to the correct part of the GnuPG system and interacting seamlessly with the user's GnuPG home directory.


title: CAVEATS
content:
Careless modification of GnuPG configurations using <i>gpgconf</i> can lead to unexpected behavior or break GnuPG functionality. Some changes, especially those affecting daemons like <i>gpg-agent</i>, might require a <b>--reload</b> or <b>--kill</b>/<b>--launch</b> sequence to take effect. Users should always exercise caution and understand the impact of configuration changes. Additionally, <i>gpgconf</i> operates within the context of the GnuPG home directory, and proper file system permissions are essential for its correct operation.


title: UNDERLYING CONFIGURATION FILES
content:
While <i>gpgconf</i> provides a command-line interface, it primarily interacts with and modifies plain-text configuration files located within the GnuPG home directory (typically <i>~/.gnupg/</i>). Examples include <i>gpg.conf</i>, <i>gpg-agent.conf</i>, and <i>dirmngr.conf</i>. Direct editing of these files is possible but <i>gpgconf</i> offers validation and a structured approach, reducing the risk of errors.


title: SCRIPTING AND AUTOMATION
content:
One of <i>gpgconf</i>'s key strengths is its suitability for scripting. Its ability to programmatically query and set options makes it invaluable for automated deployments, managing GnuPG instances on servers, or dynamically adjusting settings based on operational needs without requiring manual intervention.


title: HISTORY
content:
<i>gpgconf</i> emerged as a necessary tool within the GnuPG ecosystem as the suite evolved into a more modular and complex system. Introduced to manage the configurations of individual components like <i>gpg-agent</i> and <i>scdaemon</i>, it provided a standardized and programmatic way to interact with settings that were previously managed through disparate configuration files. Its development reflects GnuPG's growth from a single cryptographic tool into a comprehensive framework for secure communication and data handling, requiring robust configuration management capabilities.


title: PARAMETERS
content:
<b>--output <i>DIR</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies a directory <i>DIR</i> where the extracted components should be written as separate files.<br><br><b>--list-packets</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Instead of writing to files, lists all identified OpenPGP packets and their types to standard output.<br><br><b>--dry-run</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Performs a simulated run without actually writing any output files or modifying the system. Useful for testing.<br><br><b>--force</b><br>&nbsp;&nbsp;&nbsp;&nbsp;When used with <code>--output</code>, allows <i>gpgsplit</i> to overwrite existing files in the specified directory.<br><br><b>--verbose</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables more detailed output, showing progress and information about the processed packets.<br><br><b>--version</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays the version information of <i>gpgsplit</i> and exits.<br><br><b>--help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a brief help message with available options and exits.<br><br><b>--homedir <i>DIR</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the GnuPG home directory to <i>DIR</i>. This is usually not needed for <i>gpgsplit</i> as it operates on raw key data.<br><br><b>--debug-level <i>LEVEL</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the debug level for diagnostics (e.g., <code>guru</code> for maximum verbosity).<br><br><b>--batch</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Runs in batch mode, suppressing all user interaction.<br><br><b>--no-tty</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Disables the use of the TTY for user interaction or prompts.<br><br>


title: DESCRIPTION
content:
<i>gpgsplit</i> is a specialized utility within the GnuPG suite designed to parse and dissect a GnuPG key block into its constituent OpenPGP packets. When provided with a key file (or standard input), it identifies and extracts distinct elements such as the primary public key, subkeys, user IDs, and their associated signatures. Each of these components is then output as a separate, self-contained block.<br><br>This functionality is invaluable for developers, security researchers, and auditors who need to examine the granular structure of a GnuPG key, understand its composition, or troubleshoot issues. It processes raw OpenPGP packet data, offering a detailed view beyond what standard GnuPG key listing functions provide, making it a powerful tool for in-depth key analysis and manipulation.


title: CAVEATS
content:
<i>gpgsplit</i> is primarily a parsing tool and does not perform cryptographic validation of the key material. It merely dissects the OpenPGP packet stream. The extracted components, especially private key packets, should be handled with extreme care due to their sensitive nature. It assumes the input is a valid OpenPGP key block; malformed input may lead to unexpected behavior.


title: OUTPUT FILE NAMING CONVENTION
content:
When using the <code>--output</code> option, <i>gpgsplit</i> creates files with a consistent naming scheme. Files are typically named <code>XXXXXX-YYY.EXT</code>, where <code>XXXXXX</code> is a sequential key block number (e.g., <code>000000</code> for the first key), <code>YYY</code> is a sequential packet number within that block (e.g., <code>001</code>, <code>002</code>), and <code>EXT</code> indicates the packet type (e.g., <code>.pk</code> for public key, <code>.sk</code> for subkey, <code>.uid</code> for user ID, <code>.sig</code> for signature, <code>.psk</code> for private subkey). This systematic naming aids in organizing and understanding the key's disassembled parts.


title: PACKET TYPES HANDLED
content:
<i>gpgsplit</i> can identify and extract various OpenPGP packet types, including Public-Key Packet (primary key), Public-Subkey Packet, User ID Packet, Signature Packet, Public-Key Encrypted Session Key Packet, Symmetric-Key Encrypted Session Key Packet, Compressed Data Packet, Literal Data Packet, Trust Packet, User Attribute Packet, Symmetrically Encrypted and Malleable Data Packet, and others. This comprehensive dissection allows for a deep inspection of the key's entire structure and associated data.


title: HISTORY
content:
<i>gpgsplit</i> is an integral part of the GnuPG (GNU Privacy Guard) project, a free implementation of the OpenPGP standard. It was developed to provide a low-level tool for analyzing and breaking down OpenPGP key structures, complementing the higher-level functions of the main <i>gpg</i> command. Its development follows the GnuPG project's commitment to transparency and auditable cryptography, allowing users and developers to inspect the raw components of cryptographic keys.


title: PARAMETERS
content:
<b><b>-P</b> <i>project_file</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the main project file(s) to build. This is usually the entry point for the build.<br><br><b><b>-X</b> <i>name=value</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the value of an external variable <i>name</i>. These variables can be used within project files for conditional compilation or path definitions.<br><br><b><b>-R</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Recursively processes all projects referenced by the main project(s). This is crucial for building entire project hierarchies.<br><br><b><b>-p</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Creates all necessary object and executable directories if they don't exist. Ensures the build environment is ready.<br><br><b><b>-f</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Forces recompilation of all sources, ignoring timestamps. Useful for ensuring a clean build from scratch.<br><br><b><b>-c</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Only compiles source files; does not perform linking to create executables or libraries. Creates object files only.<br><br><b><b>-l</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Only links compiled object files; does not recompile source files. Assumes all necessary object files are already present.<br><br><b><b>-m</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Rebuilds objects or executables only if their source files are newer than the compiled output. This is the default incremental build behavior.<br><br><b><b>-j</b> <i>N</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the number of parallel jobs to execute. Speeds up compilation on multi-core systems by utilizing multiple CPU cores.<br><br><b><b>-q</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Runs in quiet mode, suppressing most informational output. Only errors and warnings are typically displayed.<br><br><b><b>-v</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Runs in verbose mode, displaying detailed information about the build process, including executed commands and dependencies.<br><br><b><b>-k</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Continues building other projects or source files even if errors occur in some parts of the build. Useful for finding multiple errors.<br><br><b><b>--clean</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Cleans the project by removing all generated object files, executables, and intermediate build artifacts.<br><br><b><b>--target=</b><i>target_name</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the target for cross-compilation (e.g., <I>arm-elf</I>). Directs <b>gprbuild</b> to use a specific cross-toolchain.<br><br><b><b>--build-mode=</b><i>mode</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the build mode, which can affect compilation options (e.g., <I>development</I> for debug, <I>release</I> for optimized builds).<br><br>


title: DESCRIPTION
content:
<br><b>gprbuild</b> is a sophisticated build system primarily used for projects developed with the Ada programming language, but also supporting C and C++. It is part of the GNAT (GNU Ada Toolset) ecosystem provided by AdaCore. Unlike simpler build tools, <b>gprbuild</b> operates based on project files, typically with a <I>.gpr</I> extension, which define the structure, dependencies, and build properties of a software system. <br><br>These project files allow for a highly modular and organized approach to complex software development, enabling easy management of source directories, object directories, executable names, libraries, and external toolchain configurations. <b>gprbuild</b> intelligently detects dependencies between sources and projects, ensuring that only necessary components are recompiled. It excels in managing multi-language projects, allowing seamless integration and compilation of Ada, C, and C++ sources within a single build process. Furthermore, it offers robust support for cross-compilation, making it a versatile tool for embedded systems and other specialized targets.


title: CAVEATS
content:
<br><b>gprbuild</b> relies heavily on the GNAT project file concept, which can have a learning curve for new users. While it supports C and C++, its primary strength and deepest integration are with Ada. It requires a properly configured GNAT (GCC-based) toolchain to function correctly. Its project file syntax can become complex for very large and intricate software systems.


title: GNAT PROJECT FILES (<I>.GPR</I>)
content:
At the core of <b>gprbuild</b> is the GNAT Project File system. These <I>.gpr</I> files are declarative text files that define the components of a project: its source directories, object directories, executables, libraries, compiler/linker options, and dependencies on other projects. They allow for modularity, reusability, and clear separation of concerns, enabling <b>gprbuild</b> to understand the entire build graph and perform efficient, dependency-aware compilations and links.


title: CROSS-COMPILATION SUPPORT
content:
<b>gprbuild</b> provides extensive and robust support for cross-compilation. By specifying a target architecture using the <I>--target</I> option or through project file configurations, it can seamlessly integrate with cross-compilation toolchains. This makes it an ideal choice for developing software for embedded systems, microcontrollers, and other platforms where the development environment differs from the target execution environment, streamlining the complex cross-build process.


title: HISTORY
content:
<br><b>gprbuild</b> was developed by AdaCore as a successor and more powerful alternative to the traditional <b>gnatmake</b> utility. While <b>gnatmake</b> was primarily designed for building single Ada projects, <b>gprbuild</b> was created to address the growing complexity of multi-language projects and the need for a robust, hierarchical build system based on the GNAT Project File (GPR) standard. It became the recommended build tool for Ada projects, especially those involving C/C++ components or cross-compilation, integrating seamlessly with the GNAT toolchain and significantly enhancing build management capabilities for Ada developers.


title: SYNOPSIS
content:
`gprof` <I>options</I> <I>executable-file</I> [<I>profile-file</I> ...]<br><br>Example: <I>gprof my_program gmon.out</I><br>Example: <I>gprof -b -p my_program</I>


title: PARAMETERS
content:
<b>-b</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Don't print the verbose descriptions. This is useful for scripts that want to parse the output of `gprof`.<br><br><b>-p</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Print the flat profile. This is the default output that shows the total time spent in each function.<br><br><b>-q</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Print the call graph. This is the default output that shows parent/child relationships between functions and their accumulated time.<br><br><b>-s</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Summarize the information in the specified profile files into a single <I>gmon.sum</I> file. This is useful for combining profiling data from multiple runs.<br><br><b>-l</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enable line-by-line profiling. `gprof` attempts to discover what parts of a function are responsible for the time spent in it, reporting time per source line.<br><br><b>-z</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display functions that have zero usage (i.e., they were never called or had no time attributed to them). By default, such functions are suppressed.<br><br><b>-A</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Print annotated source code. This option displays source code segments, annotated with execution counts and times, for functions that appear in the profile.<br><br><b>-e <I>function_name</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Exclude <I>function_name</I> and its children from the call graph and flat profile displays. Time spent in the function is still accounted for, but not displayed.<br><br><b>-f <I>function_name</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Include <I>function_name</I> and its children in the call graph and flat profile displays, even if they would otherwise be suppressed. This is the inverse of <I>-e</I>.<br><br><b>-E <I>function_name</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Exclude <I>function_name</I> from the flat profile display. This only affects the flat profile, not the call graph.<br><br><b>-F <I>function_name</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Include <I>function_name</I> in the flat profile display, even if it would otherwise be suppressed. This is the inverse of <I>-E</I>.<br><br>


title: DESCRIPTION
content:
`gprof` is a powerful command-line utility used to analyze the execution profile of programs compiled with the <I>-pg</I> option. It reads profiling data generated by the program at runtime (typically from a file named <I>gmon.out</I> by default) and presents it in a human-readable format. This analysis helps developers understand where their program spends most of its time and which functions call other functions, thereby identifying performance bottlenecks. `gprof` provides two main views: a flat profile, showing the total time spent in each function and the number of times it was called; and a call graph, illustrating the parent-child relationships between functions and their respective contributions to the total execution time. It is an essential tool for performance optimization in C, C++, and Fortran applications.


title: CAVEATS
content:
`gprof` introduces runtime overhead due to instrumentation, which can alter program behavior and skew results slightly. It primarily uses sampling-based profiling, meaning its accuracy depends on the system's clock resolution and the frequency of samples. It requires the program to be compiled with the <I>-pg</I> flag, linking in profiling libraries. `gprof` is generally not suitable for profiling multithreaded applications accurately, as its call graph analysis and time accounting can be misleading in concurrent environments. Furthermore, it typically only profiles code within the main executable and not shared libraries unless specifically compiled and linked for profiling.


title: <I>PROFILING WORKFLOW</I>
content:
To use `gprof`, a program must first be compiled with the GCC <B>-pg</B> option (e.g., `gcc -pg -o my_program my_program.c`). This option instruments the executable to record profiling data during execution. After compilation, run the program normally (e.g., `./my_program`). Upon successful completion, a profile file named <B>gmon.out</B> (by default) will be generated in the current directory. Finally, run `gprof` on the executable and the profile file (e.g., `gprof my_program gmon.out`) to analyze the collected data.


title: <I>OUTPUT INTERPRETATION</I>
content:
`gprof` typically generates two main sections in its output: the <B>Flat Profile</B> and the <B>Call Graph</B>. The <B>Flat Profile</B> lists each function, the percentage of total execution time spent in it, its cumulative time, self time, and the number of calls. This helps identify functions consuming significant CPU cycles. The <B>Call Graph</B> (or Call Tree) shows how functions call each other, indicating the time spent in each function and its descendants. It includes fields like <B>%time</B>, <B>cumulative seconds</B>, <B>self seconds</B>, <B>calls</B>, and <B>name</B>. Analyzing the call graph helps understand function dependencies and propagation of performance issues through the call chain.


title: HISTORY
content:
The concept of execution profiling dates back to early computing. `gprof` itself was developed as part of the GNU Project, building upon earlier Unix profiling tools like <I>prof(1)</I>. Its initial release was in the 1980s, becoming a standard utility within the GNU Binutils collection. While newer, more sophisticated profiling tools like <I>perf</I> and <I>Valgrind</I> have emerged, `gprof` remains a reliable and widely used tool for basic function-level profiling of single-threaded applications due to its simplicity and direct integration with GCC's compilation process. Its development has focused on maintaining compatibility and providing essential profiling capabilities for open-source projects.


title: SEE ALSO
content:
gcc(1): The GNU C Compiler, used to compile programs with the <I>-pg</I> flag for `gprof`., perf(1): A Linux profiling tool for performance monitoring, often more powerful and flexible than `gprof` for system-wide and multi-threaded profiling., valgrind(1): A suite of dynamic analysis tools, including <I>callgrind</I> for detailed call-graph and cache profiling, often used as an alternative to `gprof`.


title: SYNOPSIS
content:
<b>grafana-cli</b> [<i>global-options</i>] <i>command</i> [<i>command-options</i>] [<i>arguments</i>]


title: PARAMETERS
content:
<b>plugins</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Subcommands for managing Grafana plugins:<br><ul><li><b>install</b> <i><plugin-id></i>: Installs a specified plugin from the official Grafana plugin repository.</li><li><b>ls</b>: Lists all currently installed plugins.</li><li><b>update</b> <i><plugin-id></i>: Updates a specific plugin to its latest compatible version.</li><li><b>update-all</b>: Updates all installed plugins to their latest compatible versions.</li><li><b>remove</b> <i><plugin-id></i>: Uninstalls a specified plugin.</li></ul><br><br><b>admin</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Subcommands for administrative tasks:<br><ul><li><b>reset-admin-password</b> <i><new-password></i>: Resets the password for the default Grafana administrator user.</li><li><b>change-user-password</b> <i><username> <new-password></i>: Changes the password for a specific user.</li><li><b>panel-plugins-version-check</b>: Checks if all installed panel plugins are compatible with the current Grafana version.</li></ul><br><br><b>upgrade</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Migrates the Grafana database to the latest version required by a Grafana upgrade. Typically run after a Grafana binary update.<br><br><b>--version / -v</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays the current version of <i>grafana-cli</i>.<br><br><b>--help / -h</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays help information for the command or a subcommand.<br><br>


title: DESCRIPTION
content:
<i>grafana-cli</i> is the official command-line utility for managing Grafana installations. It serves as a powerful tool for administrators to perform various operations, primarily focused on plugin management such as installing, listing, updating, and removing plugins. Beyond plugins, it also provides functionalities for administrative tasks like resetting administrator passwords, changing user passwords, upgrading Grafana, and validating configurations.<br><br>It is an essential component for automating Grafana maintenance tasks, especially in environments where direct access to the Grafana UI might be restricted or for scripting deployments. The command operates directly on the Grafana installation directory, requiring appropriate permissions, often `sudo`, to modify system-level files or install plugins into Grafana's data directories.


title: CAVEATS
content:
<ul><li>Requires appropriate file system permissions, often `sudo` or root privileges, to install plugins or modify Grafana configurations, especially when Grafana is installed in system directories.</li><li>After installing, updating, or removing plugins, it is usually necessary to restart the Grafana server process for the changes to take effect.</li><li>The <i>grafana-cli</i> binary must be accessible in the system's PATH or invoked with its full path (e.g., `/usr/sbin/grafana-cli`).</li><li>Plugin installation requires an active internet connection to download from the Grafana plugin repository.</li><li>Running the <b>upgrade</b> command without prior Grafana binary update can lead to unexpected behavior.</li></ul>


title: EXECUTION CONTEXT
content:
<i>grafana-cli</i> typically needs to be run from the Grafana installation directory or pointed to it via environment variables if the Grafana service is not running. However, when installed via system packages, it's often configured to locate the Grafana installation automatically.


title: PLUGIN DEPENDENCIES
content:
Some plugins may have external dependencies that need to be manually installed on the operating system before the plugin can function correctly. This is usually specified in the plugin's documentation.


title: HISTORY
content:
<i>grafana-cli</i> was introduced relatively early in Grafana's development lifecycle to simplify plugin management and offer command-line administrative capabilities. As Grafana grew in popularity and functionality, the CLI evolved to support more administrative tasks, becoming an indispensable tool for deployments, automation, and troubleshooting, especially for large-scale or non-GUI Grafana installations. Its design allows for direct interaction with the Grafana backend without needing to access the web UI.


title: PARAMETERS
content:
<b><b>-i, --ignore-case</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Ignores case distinctions in patterns and input.<br><br><b><b>-v, --invert-match</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Selects lines that <i>do not</i> match the pattern.<br><br><b><b>-r, --recursive</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Recursively searches files under each directory.<br><br><b><b>-l, --files-with-matches</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints only the names of files containing matches.<br><br><b><b>-n, --line-number</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prefixes output lines with their 1-based line numbers.<br><br><b><b>-c, --count</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints a count of matching lines for each file.<br><br><b><b>-E, --extended-regexp</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Interprets pattern as an extended regular expression.<br><br><b><b>-F, --fixed-strings</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Interprets pattern as fixed strings, not regular expressions.<br><br><b><b>-A NUM, --after-context=NUM</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints <i>NUM</i> lines of context <i>after</i> a match.<br><br><b><b>-B NUM, --before-context=NUM</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints <i>NUM</i> lines of context <i>before</i> a match.<br><br><b><b>-C NUM, --context=NUM</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints <i>NUM</i> lines of context <i>around</i> a match.<br><br><b><b>-w, --word-regexp</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Matches only whole words.<br><br><b><b>-x, --line-regexp</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Matches only lines that exactly match the whole pattern.<br><br><b><b>-o, --only-matching</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints only the matched parts of a line, each on a new line.<br><br><b><b>--color[=WHEN]</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Highlights matched strings with color; WHEN can be 'never', 'always', or 'auto'.<br><br>


title: DESCRIPTION
content:
<i>grep</i> is a powerful command-line utility for searching plain-text data for lines matching a regular expression. Named after the <i>ed</i> editor command <i>g/re/p</i> (global / regular expression / print), it filters log files, searches source code, and processes text. <i>grep</i> can search recursively, count matches, invert results, show context, and use various regular expression types. It's an indispensable tool for administrators and developers, offering flexibility and precision in text manipulation.


title: CAVEATS
content:
<i>grep</i> is case-sensitive by default. Performance may vary with very large files or complex regular expressions. Proper escaping of shell special characters in patterns is crucial to avoid unexpected behavior.


title: REGULAR EXPRESSIONS
content:
<i>grep</i> uses regular expressions to define search patterns. By default, it supports Basic Regular Expressions (BRE). The <b>-E</b> option enables Extended Regular Expressions (ERE), offering more features like <b>+</b> (one or more), <b>?</b> (zero or one), and <b>|</b> (alternation).


title: EXIT STATUS
content:
<i>grep</i> exits with status <i>0</i> for matches, <i>1</i> for no matches, and <i>2</i> for errors. This exit code is vital for scripting and conditional execution.


title: HISTORY
content:
<i>grep</i> was written by <i>Ken Thompson</i> in 1974 for <i>Unix</i>, named from the <i>ed</i> editor command <i>g/re/p</i>. Early variants like <i>egrep</i> (extended regex) and <i>fgrep</i> (fixed strings) existed, but their functionality is now integrated into modern <i>grep</i> via options like <b>-E</b> and <b>-F</b>. It remains a fundamental <i>Unix-like</i> utility, known for its enduring design.


title: PARAMETERS
content:
<b><b>-?</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays usage information and exits.<br><br><b><b>-V</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints the version information and exits.<br><br><b><i>file ...</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies one or more input files containing <i>grap</i> descriptions. If no files are specified, <i>grap2graph</i> reads from standard input.<br><br>


title: DESCRIPTION
content:
<i>grap2graph</i> is a command-line utility designed to translate graph descriptions written in the <i>grap</i> language into the <i>dot</i> language, which is the primary input format for Graphviz visualization tools. <i>grap</i> is a language typically used within <i>troff</i> or <i>groff</i> documents for typesetting mathematical graphs and charts.<br><br>By converting <i>grap</i> output to <i>dot</i>, <i>grap2graph</i> enables users to leverage the powerful rendering capabilities of Graphviz (like <i>dot</i>, <i>neato</i>, <i>fdp</i>, <i>sfdp</i>, <i>twopi</i>, <i>circo</i>) to visualize graphs originally defined for <i>troff</i> typesetting. This conversion facilitates a modern workflow for visualizing <i>grap</i> definitions outside of the traditional <i>troff</i> rendering pipeline, allowing for more diverse output formats (PNG, SVG, PDF, etc.) and interactive explorations through Graphviz's ecosystem. It reads <i>grap</i> descriptions from standard input and writes the corresponding <i>dot</i> graph to standard output.


title: CAVEATS
content:
<i>grap2graph</i> is primarily a translator for the <i>syntax</i> of <i>grap</i> into <i>dot</i>. It may not perfectly translate all <i>grap</i> constructs, especially those related to text positioning or highly specialized plotting features that don't have direct <i>dot</i> equivalents.<br><br>The output <i>dot</i> graph might require further manual adjustments for optimal visualization, depending on the complexity of the original <i>grap</i> definition and the desired Graphviz layout. It assumes the input is valid <i>grap</i> syntax; errors in the input <i>grap</i> code will likely lead to errors in the <i>dot</i> output or <i>grap2graph</i> itself.


title: USAGE EXAMPLE
content:
<i>grap2graph</i> typically operates as a filter in a pipeline. For example, you might pipe the output of a <i>grap</i> preprocessor or a raw <i>grap</i> file into <i>grap2graph</i>. The <i>dot</i> output can then be piped directly to a Graphviz renderer like <i>dot</i> to generate an image:<br><br><code>cat mygraph.grap | grap2graph | dot -Tpng > mygraph.png</code><br><br>This allows for the conversion of <i>grap</i> definitions into various image formats supported by Graphviz without needing the full <i>troff</i> typesetting environment.


title: HISTORY
content:
<i>grap2graph</i> is part of the <i>Graphviz</i> suite of open-source graph visualization software, which was originally developed at AT&T Labs Research. <i>grap2graph</i> was created to bridge the gap between older <i>troff</i>-based graph definitions using the <i>grap</i> language and the modern <i>dot</i> language and Graphviz rendering engine.<br><br>This utility facilitated the migration and reuse of existing <i>grap</i> content in a more flexible and widely supported visualization environment. Its development reflects the continuous effort to integrate different graph description paradigms within a unified visualization framework.


title: PARAMETERS
content:
<b>-o <I>outfile</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the output file where the converted Graphviz DOT data will be written. If this option is not used, the output is written to standard output (stdout).<br><br><b>-?</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a brief usage message outlining the command's options and then exits.<br><br>


title: DESCRIPTION
content:
<i>graphml2gv</i> is a utility program within the Graphviz suite designed to convert graph data stored in the GraphML XML format into the Graphviz DOT language. GraphML is a comprehensive XML-based file format for graphs, often used for exchanging graph data between different applications. The Graphviz DOT language, on the other hand, is a simple text-based language for describing graphs, primarily used as input for Graphviz layout engines (like <b>dot</b>, <b>neato</b>, <b>fdp</b>) to generate visual representations of graphs.<br><br>This command acts as a crucial bridge, allowing users to leverage the powerful visualization capabilities of Graphviz on graph datasets originally created or stored in GraphML. It parses the GraphML structure, including nodes, edges, and their attributes, and translates them into corresponding DOT language elements. This enables subsequent processing, layout, and rendering of the graph using the rich set of Graphviz tools. <i>graphml2gv</i> is particularly useful for workflows involving heterogeneous graph tools or for archiving graph data in a standardized, yet easily visualizable, format.


title: CAVEATS
content:
The conversion process focuses on core graph structures (nodes, edges) and common attributes. Complex or highly specialized GraphML features, especially those not directly supported by the Graphviz DOT language or its layout engines, might be omitted or simplified during the conversion process. Users should verify the fidelity of the conversion for intricate GraphML inputs.


title: INPUT/OUTPUT
content:
<i>graphml2gv</i> reads GraphML data from standard input (stdin) if no input files are specified on the command line. This allows for piping data from other commands. The converted Graphviz DOT output is written to standard output (stdout) by default, but can be redirected to a specified file using the <b>-o</b> option.


title: HISTORY
content:
<i>graphml2gv</i> is an integral part of the Graphviz (Graph Visualization Software) project, which originated at AT&T Labs Research. Graphviz has been under continuous development since the mid-1990s, with <i>graphml2gv</i> being developed to support interoperability with the GraphML standard, allowing broader adoption and use of Graphviz tools for diverse graph data sources. Its inclusion underscores Graphviz's commitment to supporting open graph data formats.


title: SYNOPSIS
content:
The > operator is not a standalone command but an integral part of shell syntax used in conjunction with commands.<br><br><i>command > file_path</i><br><br>Examples:<br><i>ls -l > file_list.txt</i><br><i>echo 'Hello, World!' > message.txt</i><br><i>cat /dev/null > empty_file.txt</i><br>Optionally, you can explicitly specify the file descriptor to redirect (1 for stdout):<br><i>command 1> file_path</i>


title: PARAMETERS
content:
<b>target_file</b><br>&nbsp;&nbsp;&nbsp;&nbsp;The > operator itself does not accept traditional command-line options or flags. Its 'parameter' is the target file or path where the command's standard output will be redirected.<br><br>The structure is:<br><i>command > <b>target_file</b></i><br><br>The <b>target_file</b> is a required argument specifying the name and optional path of the file to which the output will be written.<br><br>


title: DESCRIPTION
content:
The <b>greater-than</b> symbol (>) is a fundamental shell operator in Linux and Unix-like systems, used for <i>output redirection</i>. It takes the <i>standard output</i> (stdout) of a command and writes it entirely to a specified file. If the target file does not exist, the shell creates it. Crucially, if the file already exists, its contents are <b>overwritten</b> without any warning or prompt, potentially leading to data loss if not used carefully. This operator is essential for capturing command results, logging information, or feeding output from one process into a file for later use. It is distinct from the >> operator, which appends the output to the end of the file rather than overwriting it.


title: CAVEATS
content:
<b><i>Data Overwriting</i></b>: The most significant caveat is that > will mercilessly overwrite the contents of an existing file without any warning or prompt. This can lead to irreversible data loss. To prevent this, consider using >> for appending, or enable the <i>noclobber</i> shell option (e.g., <i>set -o noclobber</i> in Bash) which prevents accidental overwriting of existing files. If <i>noclobber</i> is set, you can still force overwrite using >|.<br><br><b><i>Permissions</i></b>: The shell user must have write permissions to the directory where the file is being created, or write permissions to the file itself if it already exists.<br><br><b><i>Shell Feature</i></b>: > is a shell built-in redirection operator, not an external executable command. Its behavior is handled directly by the shell (e.g., Bash, Zsh), meaning its functionality can sometimes vary slightly between different shells, though the core behavior remains consistent.


title: FILE DESCRIPTORS AND DEFAULT BEHAVIOR
content:
In Unix-like systems, processes interact with files and devices using <i>file descriptors</i>. Standard output (stdout) is associated with file descriptor 1. When you use >, it is implicitly redirecting file descriptor 1. You can explicitly specify the file descriptor, for example, <i>1> file.txt</i> is identical to <i>> file.txt</i>. This distinction becomes important when redirecting other streams like standard error (stderr), which uses file descriptor 2 (e.g., <i>2> error.log</i>).


title: PREVENTING ACCIDENTAL OVERWRITE
content:
To prevent accidental overwriting of existing files when using >, you can set the <i>noclobber</i> option in your shell. For Bash, this is done with <br><i>set -o noclobber</i><br>. Once set, any attempt to use > on an existing file will result in an error. To override <i>noclobber</i> for a specific redirection, you can use the <i>>|</i> operator (e.g., <i>command >| existing_file.txt</i>).


title: COMMON USE CASES
content:
1. <b>Saving Command Output</b>: Easily store the results of a command for later analysis or viewing (e.g., <i>ls -R > directory_contents.txt</i>).<br>2. <b>Creating Empty Files</b>: Quickly create an empty file (e.g., <i>> new_file.txt</i> or <i>touch new_file.txt</i>).<br>3. <b>Clearing File Contents</b>: Empty an existing file without deleting it (e.g., <i>> log_file.txt</i>).<br>4. <b>Basic Logging</b>: Redirecting command output to a log file (e.g., <i>my_script.sh > script_log.txt 2>&1</i>).


title: HISTORY
content:
The concept of I/O redirection, including output redirection using the > operator, is a cornerstone of the Unix operating system. It was developed at Bell Labs in the early 1970s as part of the original Unix design by Ken Thompson and Dennis Ritchie. This mechanism is central to the 'Unix philosophy' of creating small, single-purpose tools that can be combined in powerful ways. The standardization of file descriptors (0 for stdin, 1 for stdout, 2 for stderr) and their redirection capabilities became a fundamental feature of all subsequent Unix shells (like Bourne Shell, C Shell, Bash, Zsh) and Linux distributions, enabling sophisticated command chaining and scripting.


title: SEE ALSO
content:
<i>>></i> (Append standard output to a file)<br><i><</i> (Redirect standard input from a file)<br><i>2></i> (Redirect standard error to a file)<br><i>&></i> or <i>>&</i> (Redirect both standard output and standard error)<br><i>|</i> (Pipe: Redirect standard output of one command as standard input to another)<br><i>tee(1)</i> (Read from standard input and write to both standard output and files)<br><i>cat(1)</i> (Concatenate files and print on the standard output, often used to create or view files in conjunction with >)<br><i>echo(1)</i> (Display a line of text, frequently used to write short strings to files with >)


title: PARAMETERS
content:
<b>-i, --ignore-case</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Ignore case distinctions in both the PATTERN and the input files.<br><br><b>-v, --invert-match</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Invert the sense of matching, to select non-matching lines.<br><br><b>-c, --count</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Suppress normal output; instead print a count of matching lines for each input file.<br><br><b>-n, --line-number</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prefix each line of output with the 1-based line number within its input file.<br><br><b>-r, --recursive</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Read all files under each directory, recursively. This is equivalent to -d recurse.<br><br><b>-l, --files-with-matches</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Suppress normal output; instead print the name of each input file from which output would normally have been printed.<br><br><b>-L, --files-without-matches</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Suppress normal output; instead print the name of each input file from which no output would normally have been printed.<br><br><b>-w, --word-regexp</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Select only those lines containing matches that form whole words.<br><br><b>-E, --extended-regexp</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Interpret PATTERN as an extended regular expression (ERE). This is the default with 'egrep'.<br><br><b>-F, --fixed-strings</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Interpret PATTERN as a list of fixed strings, separated by newlines, any of which is to be matched. This is the default with 'fgrep'.<br><br><b>-A NUM, --after-context=NUM</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Print NUM lines of trailing context after matching lines.<br><br><b>-B NUM, --before-context=NUM</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Print NUM lines of leading context before matching lines.<br><br><b>-C NUM, --context=NUM</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Print NUM lines of output context (leading and trailing).<br><br>


title: DESCRIPTION
content:
<i>grep</i> (Global Regular Expression Print) is a powerful command-line utility on Linux and Unix-like systems. It's designed to search for lines that match a specified pattern within one or more input files, or from standard input.<br><br>The name 'grep' originates from the <i>ed</i> editor command <I>g/re/p</I> (global / regular expression / print), which performs a global search for a regular expression and prints all matching lines. It is an essential tool for system administrators, developers, and anyone who needs to quickly find, filter, or analyze textual data. <i>grep</i> is highly versatile, supporting various regular expression syntaxes and numerous options to control its search behavior, output formatting, and file handling.


title: CAVEATS
content:
When searching large directories or large files, <i>grep</i> can consume significant system resources. Complex regular expressions can sometimes lead to unexpected performance issues or non-obvious matches. Special characters within your pattern (e.g., $, *, ., ^, [], ()) often need to be escaped with a backslash (<I>\</I>) or enclosed in single quotes to prevent the shell from interpreting them.


title: NO 'GREED' COMMAND
content:
Please note that there is no standard Linux command officially named 'greed'. This response has been tailored assuming a likely typo for the widely used and critically important 'grep' command. If you were indeed referring to a custom or less common utility, please clarify.


title: REGULAR EXPRESSIONS
content:
<i>grep</i>'s core power comes from its use of regular expressions (regex). These are sequences of characters that define a search pattern. <i>grep</i> supports Basic Regular Expressions (BRE) by default, and Extended Regular Expressions (ERE) with the <I>-E</I> option (or by using the <I>egrep</I> command). Fixed strings, where the pattern is treated literally without regex interpretation, can be used with the <I>-F</I> option (or <I>fgrep</I>).


title: EXIT STATUS
content:
<i>grep</i> communicates its success or failure through its exit status, which is crucial for scripting: <ul><li><I>0</I>: One or more lines were selected (a match was found).</li><li><I>1</I>: No lines were selected (no match was found).</li><li><I>2</I>: An error occurred (e.g., file not found, bad option).</li></ul>


title: HISTORY
content:
<i>grep</i> was originally written by Ken Thompson in 1970 for the Unix operating system. Its inception was driven by the need for a powerful text searching utility, leveraging the concept of regular expressions. It quickly became a fundamental tool in the Unix toolkit, embodying the Unix philosophy of 'do one thing and do it well'. Its design and functionality have been highly influential, inspiring countless other text processing utilities and programming language features.


title: SYNOPSIS
content:
<B>grep</B> [<I>OPTIONS</I>] <I>PATTERN</I> [<I>FILE</I>...]<br><B>grep</B> [<I>OPTIONS</I>] <I>-e PATTERN</I>... [<I>FILE</I>...]<br><B>grep</B> [<I>OPTIONS</I>] <I>-f FILE_OF_PATTERNS</I> [<I>FILE</I>...]


title: PARAMETERS
content:
<b><B>-i</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Ignores case distinctions in both the <I>PATTERN</I> and the input files.</I><br><br><b><B>-v</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Inverts the match; selects non-matching lines.</I><br><br><b><B>-r</B>, <B>-R</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Recursively searches directories. <B>-R</B> follows symbolic links.</I><br><br><b><B>-l</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Lists only the names of files that contain matches, not the matching lines.</I><br><br><b><B>-c</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Suppresses normal output; instead, prints a count of matching lines for each input file.</I><br><br><b><B>-n</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Prefixes each line of output with the 1-based line number within its input file.</I><br><br><b><B>-w</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Selects only those lines containing matches that form whole words.</I><br><br><b><B>-x</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Selects only those matches that match the entire line.</I><br><br><b><B>-E</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Interprets <I>PATTERN</I> as an extended regular expression (ERE). Similar to <B>egrep</B>.</I><br><br><b><B>-F</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Interprets <I>PATTERN</I> as a list of fixed strings, separated by newlines, any of which is to be matched. Similar to <B>fgrep</B>.</I><br><br><b><B>-A</B> <I>NUM</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Prints <I>NUM</I> lines of trailing context after a matching line.</I><br><br><b><B>-B</B> <I>NUM</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Prints <I>NUM</I> lines of leading context before a matching line.</I><br><br><b><B>-C</B> <I>NUM</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Prints <I>NUM</I> lines of context around a matching line (combines <B>-A</B> and <B>-B</B>).</I><br><br><b><B>-o</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Prints only the matched (non-empty) parts of a matching line, with each such part on a separate output line.</I><br><br><b><B>--color</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Highlights the matched strings in the output.</I><br><br><b><B>-q</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Quiet mode; suppresses all normal output. Useful for scripting when only the exit status matters.</I><br><br><b><B>-h</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Suppresses the prefixing of file names on output when multiple files are searched.</I><br><br><b><B>-e</B> <I>PATTERN</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Specifies a <I>PATTERN</I>. Useful for patterns starting with a hyphen (-) or to specify multiple patterns.</I><br><br><b><B>-f</B> <I>FILE</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Obtains patterns from <I>FILE</I>, one per line.</I><br><br>


title: DESCRIPTION
content:
<I>The <B>grep</B> command is a powerful command-line utility used to search for specific text patterns within one or more files. Its name, an acronym for "global regular expression print," originates from the <B>ed</B> editor's <B>g/re/p</B> (global / regular expression / print) command. <B>grep</B> excels at filtering lines that match a given regular expression, making it indispensable for system administrators, developers, and users alike.<br><br>It can be used to search log files for errors, find specific code snippets in source directories, filter the output of other commands via pipes, and identify configuration settings. <B>grep</B> supports various types of regular expressions, from basic (BRE) to extended (ERE) and sometimes Perl-compatible (PCRE), providing immense flexibility in defining complex search patterns.</I>


title: CAVEATS
content:
<I>When dealing with a very large number of files or extremely large individual files, <B>grep</B> can be resource-intensive. Performance might degrade if complex regular expressions are used on extensive datasets. Care must be taken when using special characters in <I>PATTERN</I>, as they often require escaping (e.g., using <B>\</B> or single quotes) to prevent shell interpretation. Different versions of <B>grep</B> (GNU <B>grep</B>, BSD <B>grep</B>, etc.) and locale settings can subtly affect regular expression behavior and Unicode handling.</I>


title: <I>REGULAR EXPRESSIONS</I>
content:
<I>The core power of <B>grep</B> lies in its ability to interpret regular expressions (regex). These are sequences of characters that define a search pattern. <B>grep</B> supports Basic Regular Expressions (BRE) by default, Extended Regular Expressions (ERE) with <B>-E</B> or <B>egrep</B>, and in some versions, Perl Compatible Regular Expressions (PCRE) with <B>-P</B>. Understanding regex is crucial for leveraging <B>grep</B>'s full capabilities, allowing for flexible and precise pattern matching, including character sets, quantifiers, anchors, and grouping.</I>


title: <I>EXIT STATUS</I>
content:
<I><B>grep</B> communicates its success or failure through its exit status, which is vital for scripting. An exit status of <B>0</B> indicates that one or more lines were selected. An exit status of <B>1</B> means no lines were selected. An exit status of <B>2</B> indicates an error occurred (e.g., inaccessible file, invalid option). This allows scripts to make decisions based on whether a pattern was found.</I>


title: HISTORY
content:
<I>The <B>grep</B> utility dates back to the early days of Unix, created by Ken Thompson in 1973. Its name is an acronym for "global / regular expression / print" and comes from a command in the <B>ed</B> text editor, <B>g/re/p</B>, which performs a global search for a regular expression and prints all matching lines. <B>grep</B> quickly became a fundamental Unix tool, embodying the Unix philosophy of doing one thing well. Over time, variants like <B>egrep</B> (for extended regular expressions) and <B>fgrep</B> (for fixed strings) emerged, later often integrated back into the main <B>grep</B> command via options like <B>-E</B> and <B>-F</B>. Its enduring design and widespread use underscore its importance in the command-line ecosystem.</I>


title: SEE ALSO
content:
<B>awk</B>(1), <B>sed</B>(1), <B>find</B>(1), <B>less</B>(1), <B>more</B>(1), <B>cat</B>(1), <B>locate</B>(1), <B>pcregrep</B>(1)


title: PARAMETERS
content:
<b><b>-s</b>, <b>--show-only</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Output only the matching field, not the whole paragraph.<br><br><b><b>-v</b>, <b>--invert-match</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Invert the sense of matching, to select non-matching paragraphs.<br><br><b><b>-i</b>, <b>--ignore-case</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Ignore case distinctions in patterns and data.<br><br><b><b>-e</b> <i>PATTERN</i>, <b>--regexp=</b><i>PATTERN</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Use <i>PATTERN</i> as a regular expression. Can be used multiple times to specify multiple patterns.<br><br><b><b>-f</b> <i>FILE</i>, <b>--file=</b><i>FILE</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Obtain patterns from <i>FILE</i>, one per line.<br><br><b><b>-F</b>, <b>--fixed-strings</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Interpret <i>PATTERN</i>s as fixed strings, not regular expressions.<br><br><b><b>-X</b>, <b>--extract</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Extract and output matched fields, including their field names and values.<br><br><b><b>-l</b>, <b>--files-with-matches</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Suppress normal output; instead print the name of each input file from which output would normally have been printed.<br><br><b><b>-L</b>, <b>--files-without-matches</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Suppress normal output; instead print the name of each input file from which no output would normally have been printed.<br><br><b><b>-h</b>, <b>--no-filename</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Suppress the prefixing of filenames on output when multiple files are searched.<br><br><b><b>-n</b>, <b>--paragraph-number</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prefix each output paragraph with the 1-based paragraph number within its input file.<br><br><b><b>-d</b>, <b>--debian-control</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Treat input as a Debian control file. This is often the default behavior due to its primary purpose.<br><br>


title: DESCRIPTION
content:
<i>grep-dctrl</i> is a specialized command-line utility for searching Debian control files, such as those found in <i>/var/lib/dpkg/status</i>, <i>Packages.gz</i>, or <i>Sources.gz</i> files. Unlike the standard <i>grep</i>, which operates on lines of text, <i>grep-dctrl</i> understands the paragraph-and-field structure inherent in Debian control files. This allows users to search for patterns within specific fields (e.g., <b>Package</b>, <b>Description</b>, <b>Depends</b>) or across all fields of a control paragraph.<br><br>It is an invaluable tool for system administrators, package maintainers, and developers within the Debian ecosystem. It enables quick and precise queries on package metadata, helping to find packages based on their description, dependencies, maintainer, or any other information stored in their structured control records. <i>grep-dctrl</i> is part of the <i>dctrl-tools</i> suite and leverages Perl regular expressions for powerful pattern matching.


title: CAVEATS
content:
<i>grep-dctrl</i> is specifically designed for the Debian control file format. While it can process any plain text formatted with blank-line-separated paragraphs and colon-separated fields, its primary utility is within the Debian package management context.<br>Being a Perl script, its performance characteristics might differ from native C programs like GNU <i>grep</i>, especially on extremely large unstructured files, though this is rarely a practical limitation for its intended use case.


title: INPUT HANDLING
content:
<i>grep-dctrl</i> can read structured data from standard input (via a pipe) or from one or more specified <i>FILE</i> arguments. If no <i>FILE</i> is provided, it defaults to reading from standard input.


title: FIELD-SPECIFIC SEARCHING
content:
If one or more <i>FIELD</i> arguments are provided before the <i>PATTERN</i>s, <i>grep-dctrl</i> will restrict its search to only those named fields. If no fields are specified, the search is performed across all fields within each paragraph.


title: PARAGRAPH-ORIENTED OUTPUT
content:
Unlike traditional <i>grep</i>, <i>grep-dctrl</i> primarily operates on 'paragraphs' (records separated by blank lines) rather than individual lines. By default, it outputs the entire paragraph that contains a match, making it easier to view complete package records.


title: HISTORY
content:
<i>grep-dctrl</i> is a core utility within the <i>dctrl-tools</i> package, which provides a set of powerful command-line tools for processing Debian control files. Its development is closely tied to the Debian project's needs for efficiently querying and manipulating package metadata, serving as a foundational tool for package management operations.


title: PARAMETERS
content:
<b><i>PATTERN</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The regular expression or fixed string to search for within the JAR files.<br><br><b><i>JAR_FILE</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;One or more paths to the JAR files to be searched.<br><br><b><b>-i</b>, <b>--ignore-case</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Ignore case distinctions in the <i>PATTERN</i> and input data.<br><br><b><b>-v</b>, <b>--invert-match</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Invert the sense of matching, to select non-matching lines.<br><br><b><b>-c</b>, <b>--count</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Suppress normal output; instead print a count of matching lines for each file within the JAR.<br><br><b><b>-l</b>, <b>--files-with-matches</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Suppress normal output; instead print the name of each file inside the JAR that contains a match.<br><br><b><b>-L</b>, <b>--files-without-matches</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Suppress normal output; instead print the name of each file inside the JAR that does not contain a match.<br><br><b><b>-n</b>, <b>--line-number</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prefix each line of output with the 1-based line number within its respective file inside the JAR.<br><br><b><b>-E</b>, <b>--extended-regexp</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Interpret <i>PATTERN</i> as an extended regular expression (ERE).<br><br><b><b>-F</b>, <b>--fixed-strings</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Interpret <i>PATTERN</i> as a list of fixed strings, separated by newlines, any of which is to be matched.<br><br><b><b>-P</b>, <b>--perl-regexp</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Interpret <i>PATTERN</i> as a Perl regular expression (PCRE).<br><br>


title: DESCRIPTION
content:
<i>grepjar</i> is a conceptual or custom command-line utility designed to search for text patterns within the contents of Java Archive (JAR) files. Unlike standard <i>grep</i>, which operates on regular files, <i>grepjar</i> extends this functionality to compressed JAR archives. It typically works by temporarily extracting or listing the contents of the JAR file and then applying <i>grep</i>-like pattern matching to the individual files (e.g., .java, .xml, .properties) found inside the archive. This tool is invaluable for Java developers and system administrators who need to quickly locate specific code snippets, configuration values, or resource references embedded within compiled Java applications or libraries without manually extracting the JAR's contents.


title: CAVEATS
content:
<i>grepjar</i> is not a standard Linux command and is typically implemented as a custom shell script or an alias by users or organizations. Its exact behavior, available options, and performance can vary significantly depending on its specific implementation. Common implementations might involve temporary file extraction, which can be slow for large JARs or when searching many archives. It may also struggle with non-textual files within the JAR or nested JARs/ZIPs unless specifically programmed to handle them.


title: COMMON IMPLEMENTATION APPROACHES
content:
A typical <i>grepjar</i> script often combines standard Unix tools:<br>1. Using <b>jar tf</b> (or <b>unzip -l</b>) to list contents.<br>2. Pipelining the list to <b>xargs</b> to extract specific files or using a loop to extract all files to a temporary directory.<br>3. Running <b>grep</b> on the extracted files.<br>4. Cleaning up the temporary directory.<br>More advanced versions might use the <b>JarFile</b> API in Java itself for direct stream processing without full extraction.


title: HISTORY
content:
The need for `grep`-like functionality within Java Archive files arose naturally with the widespread adoption of Java for application development. As JAR files became ubiquitous containers for compiled code, resources, and configuration, developers frequently encountered the challenge of searching their contents without cumbersome manual extraction. This led to the organic creation of custom shell scripts and aliases, often named `grepjar`, by individual developers and development teams, becoming an indispensable tool for debugging, auditing, and understanding complex Java applications.


title: SYNOPSIS
content:
<b>grex</b> [<i>OPTIONS</i>] [<i>STRING...</i>]<br>or<br><i>command</i> | <b>grex</b> [<i>OPTIONS</i>]


title: PARAMETERS
content:
<b><b>--glob</b>, <b>-g</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Interpret input strings as glob patterns (e.g., `*.txt`) rather than literal strings for regex inference.<br><br><b><b>--format</b> &lt;FORMAT&gt;, <b>-f</b> &lt;FORMAT&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the output format for the generated regular expression. Common formats include <i>pcre</i>, <i>rust</i>, <i>java</i>, <i>javascript</i>, and <i>python</i>.<br><br><b><b>--literal</b>, <b>-l</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Treat input strings as purely literal, escaping all special regular expression characters and matching them exactly.<br><br><b><b>--invert</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Generate a regular expression that matches <i>none</i> of the provided input strings.<br><br><b><b>--strict</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Generate the strictest possible regular expression, matching only the given strings exactly without over-generalizing patterns.<br><br><b><b>--word</b>, <b>-w</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Force word boundaries (<code>\b</code>) around the inferred regular expression pattern, ensuring it matches whole words.<br><br><b><b>--digits</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Treat sequences of digits (e.g., '123') as the regex pattern <code>\d+</code> (one or more digits) or <code>\d*</code> (zero or more digits).<br><br><b><b>--escape</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Escape all characters in the input that are not ASCII alphanumerics, treating them as literals.<br><br><b><b>--case-insensitive</b>, <b>-i</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Generate a case-insensitive regular expression, typically by adding an 'i' flag if the format supports it.<br><br><b><b>--no-anchors</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Do not add start-of-string (<code>^</code>) and end-of-string (<code>$</code>) anchors to the generated regular expression.<br><br><b><b>--output</b> &lt;FILE&gt;, <b>-o</b> &lt;FILE&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Write the generated regular expression to the specified output file instead of standard output.<br><br><b><b>--help</b>, <b>-h</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display help information for the <b>grex</b> command.<br><br><b><b>--version</b>, <b>-V</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Print the version information for <b>grex</b>.<br><br><b>[<i>STRING...</i>]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;One or more input strings from which <b>grex</b> will infer the regular expression. If no strings are provided, input is read from standard input.<br><br>


title: DESCRIPTION
content:
<i>grex</i> is a command-line utility written in Rust that intelligently infers a regular expression from one or more given test strings.<br><br>It analyzes the input strings to identify common patterns like digits, whitespace, word characters, and literal parts, then constructs a concise regex that matches all provided examples. This tool is invaluable for developers, system administrators, and anyone needing to quickly generate a regex without manual trial and error, especially when working with many example inputs. It's particularly useful for tasks like validating user input, parsing log files, or sanitizing data, by providing a robust pattern based on representative samples.


title: CAVEATS
content:
Regular expression inference is based on the provided samples; insufficient or unrepresentative inputs may lead to an overly broad or too narrow regex. Complex regex constructs such as backreferences or lookaheads/lookbehinds are generally not inferred by <b>grex</b>. Its effectiveness depends on the quality and diversity of the test cases.


title: INPUT MODES
content:
<b>grex</b> offers flexible input methods. You can provide input strings directly as command-line arguments, separating multiple strings with spaces. Alternatively, for larger sets of data or integration into pipelines, <b>grex</b> can read input from standard input (stdin), where each line is treated as a separate string for regex inference.


title: LANGUAGE-SPECIFIC OUTPUT
content:
A powerful feature of <b>grex</b> is its ability to generate regular expressions tailored for specific programming languages. Using the <b>--format</b> option, you can output regexes compatible with Rust, JavaScript, Python, Java, and other environments, simplifying direct integration into your code without manual translation or escaping adjustments.


title: HISTORY
content:
<b>grex</b> is a relatively modern command-line utility, implemented in the Rust programming language. It was created by Peter Bourgon to automate the often tedious and error-prone process of manually crafting regular expressions from examples. Its development in Rust ensures high performance and memory safety, contributing to its growing popularity within the developer community for its ease of use and effectiveness in generating robust regex patterns.


title: SYNOPSIS
content:
<i><b>grip</b></i> [<i>OPTIONS</i>] [<i>PATH</i>] <br><i><b>grip</b></i> [<i>OPTIONS</i>] --export [<i>PATH</i>] -o <i>OUTPUT_FILE</i> <br><i><b>grip</b></i> --help <br><i><b>grip</b></i> --version


title: PARAMETERS
content:
<b><b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show program's help message and exit.<br><br><b><b>--version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show program's version number and exit.<br><br><b><b>--port</b> <i>PORT</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The port to listen on (default: 6419).<br><br><b><b>--host</b> <i>HOST</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The host to listen on (default: 127.0.0.1).<br><br><b><b>--no-open</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Do not open a browser tab automatically.<br><br><b><b>--browser</b> <i>BROWSER</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the browser to open (e.g., chrome, firefox).<br><br><b><b>--title</b> <i>TITLE</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set the title of the HTML page.<br><br><b><b>--asset-path</b> <i>PATH</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify a path to serve assets from.<br><br><b><b>--export</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Instead of serving, export the rendered HTML to a file.<br><br><b><b>--output</b> <i>FILE</i>, <b>-o</b> <i>FILE</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the output file for export mode.<br><br><b><b>--keep-html</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Do not remove the HTML file after serving.<br><br><b><b>--user</b> <i>USERNAME</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;GitHub username for API authentication (for higher rate limits).<br><br><b><b>--pass</b> <i>PASSWORD</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;GitHub password for API authentication.<br><br><b><b>--token</b> <i>TOKEN</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;GitHub personal access token for API authentication.<br><br><b><b>--api-url</b> <i>URL</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify a custom GitHub API URL.<br><br><b><b>--offline</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Render Markdown completely offline without GitHub API.<br><br><b><b>--style</b> <i>CSS_URL</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Custom stylesheet URL or path.<br><br><b><b>--quiet</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Suppress output except for errors.<br><br><b><b>--clear-cache</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Clear GitHub API cache.<br><br><b><b>--skip-math</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Skip rendering math equations.<br><br><b><b>--skip-emoji</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Skip rendering emoji shortcodes.<br><br>


title: DESCRIPTION
content:
<i><b>grip</b></i> is a powerful command-line utility designed to render GitHub Flavored Markdown (GFM) files locally. It accomplishes this by starting a lightweight web server that serves the rendered Markdown content, allowing you to preview your `README.md` files, Wiki pages, or any other Markdown document in your web browser exactly as it would appear on GitHub. This eliminates the need to commit and push changes to GitHub just to see how the Markdown is rendered, significantly speeding up the documentation workflow. It leverages GitHub's own Markdown API by default for accurate rendering, but also offers an offline mode for basic GFM display. Key features include live reloading on file changes, customizable port and host settings, and the ability to export rendered HTML to a file. <i><b>grip</b></i> is an indispensable tool for developers and technical writers who frequently work with Markdown for GitHub repositories, ensuring consistency and accuracy in their documentation.


title: CAVEATS
content:
<i><b>grip</b></i> requires Python to be installed on your system. By default, it relies on GitHub's Markdown API for accurate rendering, which means an active internet connection is typically needed. Without authentication (via username/password or personal access token), you might encounter GitHub API rate limits. While the `--offline` mode allows rendering without an internet connection, it may not perfectly replicate all GitHub-specific styles or extensions as it uses a local Markdown parser.


title: INSTALLATION
content:
<i><b>grip</b></i> is typically installed via pip, Python's package installer. You can install it using the command: <br> `pip install grip`. <br> It's recommended to install it in a virtual environment to avoid conflicts with system-wide Python packages.


title: BASIC USAGE EXAMPLES
content:
<ul><li>To preview a `README.md` file: <br> `grip README.md`</li><li>To preview content from standard input: <br> `cat my_notes.md | grip`</li><li>To export a Markdown file to HTML: <br> `grip --export documentation.md -o documentation.html`</li><li>To preview a file on a specific port without opening a browser: <br> `grip --port 8000 --no-open my_doc.md`</li></ul>


title: HISTORY
content:
<i><b>grip</b></i> was created by Joe Esposito to fill a specific niche: providing an accurate, local preview of GitHub Flavored Markdown documents. Before <i><b>grip</b></i>, developers often had to commit and push changes to GitHub just to see the final rendered output, or rely on less accurate browser extensions. Written in Python, <i><b>grip</b></i> quickly became a popular choice for streamlining the Markdown documentation workflow due to its simplicity, live-reloading capabilities, and reliance on GitHub's own API for rendering accuracy. It continues to be maintained and updated by its community.


title: SYNOPSIS
content:
<b>grn</b> [ <i>-CTZ</i> ] [ <i>-M dir</i> ] [ <i>-d num</i> ] [ <i>-f family</i> ] [ <i>-s num</i> ] [ <i>-m num</i> ] [ <i>-o num</i> ] [ <i>-p num</i> ] [ <i>-F dir</i> ] [ <i>files ...</i> ]


title: PARAMETERS
content:
<b><i>-C</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables compatibility mode for older <i>Gremlin</i> files.<br><br><b><i>-T</i> <i>dev</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the output device for <i>groff</i>, such as <i>-Tps</i> for PostScript.<br><br><b><i>-Z</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Suppresses the output of <i>groff</i> commands that represent comments in the <i>Gremlin</i> input. Useful for debugging.<br><br><b><i>-M</i> <i>dir</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Adds <i>dir</i> to the list of directories searched for <i>Gremlin</i> font files.<br><br><b><i>-d</i> <i>num</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the default text size (in <i>Gremlin</i> units) for text objects that do not explicitly specify one.<br><br><b><i>-f</i> <i>family</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the default font family for text objects.<br><br><b><i>-s</i> <i>num</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Applies a scaling factor to all generated graphic coordinates. A value of 1.0 implies no scaling.<br><br><b><i>-m</i> <i>num</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the minimum line thickness for drawing objects. Lines thinner than this value will be rendered at this thickness.<br><br><b><i>-o</i> <i>num</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the default oblique angle (in degrees) for text objects that do not specify one.<br><br><b><i>-p</i> <i>num</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints debugging information related to points, useful for understanding coordinate transformations.<br><br><b><i>-F</i> <i>dir</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Adds <i>dir</i> to the list of directories searched for <i>groff</i> font files. This option is passed to <i>groff</i>.<br><br><b><i>files ...</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;One or more <i>Gremlin</i> input files to be processed. If no files are specified, <i>grn</i> reads from standard input.<br><br>


title: DESCRIPTION
content:
<i>grn</i> is a specialized preprocessor for the <i>groff</i> text formatting system, designed to interpret and render picture descriptions written in the <i>Gremlin</i> language. Originally developed at Xerox PARC, <i>Gremlin</i> provides a simple, structured way to define vector graphics through commands for drawing lines, arcs, circles, ellipses, and placing text.<br><br>When invoked, <i>grn</i> reads one or more <i>Gremlin</i> input files or standard input. It then translates these graphical commands into corresponding <i>groff</i> drawing requests, effectively embedding the pictures directly into the <i>groff</i> document stream. This allows users to combine complex graphical elements with textual content formatted by <i>groff</i>.<br><br><i>grn</i> acts as a pipeline component within the <i>groff</i> processing chain, much like <i>pic</i> or <i>eqn</i>. Its primary utility lies in maintaining compatibility with existing <i>Gremlin</i> graphics files and integrating them seamlessly into modern <i>groff</i> workflows, although <i>Gremlin</i> itself is now a relatively obscure format.


title: CAVEATS
content:
<i>grn</i> is a highly specialized and somewhat legacy tool. It does not support all features of the <i>Gremlin</i> language; notably, it currently lacks support for <b>fill</b> and <b>color</b> commands. Its primary purpose is integration with the <i>groff</i> system, making it less suitable for standalone graphics creation or for workflows outside the <i>troff</i>/<i>groff</i> ecosystem. Modern graphics tools offer far more extensive capabilities and broader output formats.


title: <B>GREMLIN FILE FORMAT</B>
content:
<i>grn</i> processes files written in the <i>Gremlin</i> picture language. <i>Gremlin</i> files consist of commands describing graphical objects such as lines, curves, circles, ellipses, and text. Each command specifies the object type and its associated parameters, such as coordinates, sizes, and font information for text. The language is text-based and relatively simple, designed for programmatic generation and manipulation of vector graphics.


title: <B>ENVIRONMENT VARIABLES</B>
content:
<i>grn</i> respects several environment variables:<br><ul><li><b>GROFF_FONT_PATH</b>: Specifies directories to search for <i>groff</i> font description files, similar to the <i>-F</i> option.</li><li><b>GROFF_TMPDIR</b>: Defines the directory where temporary files are created during processing.</li></ul>


title: HISTORY
content:
<i>grn</i>'s history is intertwined with the development of the <i>groff</i> project and the <i>Gremlin</i> picture language itself. <i>Gremlin</i> was developed at Xerox PARC in the late 1970s and early 1980s as a vector graphics description language. When James Clark began the <i>groff</i> project in 1989 as a free software replacement for AT&T's <i>troff</i>, he aimed to include compatible preprocessors for various functionalities. <i>grn</i> was created to provide compatibility for users with existing <i>Gremlin</i> picture files, allowing them to continue using these graphics within the new <i>groff</i> environment. Its development has since proceeded as part of the broader <i>groff</i> utilities suite, ensuring continued support for this niche, yet historically significant, graphics format within the traditional Unix document processing pipeline.


title: PARAMETERS
content:
<b><b>-b</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Print characters in bold instead of using light fonts when no specific font is available. This is primarily a fallback mechanism.<br><br><b><b>-l</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set the paper orientation to landscape mode for the DVI output.<br><br><b><b>-p</b><i><I>paper_size</I></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the paper size for the output. <i><I>paper_size</I></i> can be a predefined size like 'letter' or 'a4', or a custom size like '11in,8.5in'.<br><br><b><b>-r</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Reverse white and black colors in the output, producing a negative image of the document.<br><br><b><b>-s</b><i><I>point_size</I></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set the default point size for fonts. This is typically used for basic font sizing if not otherwise specified in the groff document.<br><br><b><b>-e</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Encapsulate fonts within the DVI file. This can increase file size but ensures portability.<br><br><b><b>-a</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Generate DVI output using only ASCII characters, converting or omitting non-ASCII characters.<br><br><b><b>-c</b><i><I>font_map_file</I></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Use the specified <i><I>font_map_file</I></i> to define font mappings for DVI. This allows customization of how groff fonts map to TeX fonts.<br><br><b><b>-w</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enable verbose warnings during processing, providing more diagnostic information.<br><br><b><b>-x</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Pass through DVI specials, which are commands or data embedded in the DVI stream that are specific to certain DVI processors or viewers.<br><br><b><b>-F</b><i><I>directory</I></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Search <i><I>directory</I></i> for font and device description files. This is a common <i>groff</i> option.<br><br><b><b>-V</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Print the version number of <b>grodvi</b> to standard error and exit.<br><br>


title: DESCRIPTION
content:
The <b>grodvi</b> command is a <i>groff</i> output driver responsible for translating the <i>groff</i> intermediate output into DVI (DeVice Independent) format. DVI is a platform-independent page description language primarily used by the TeX typesetting system. <br><br>When you use <code>groff -T dvi file.roff</code>, <b>grodvi</b> is automatically invoked behind the scenes to produce a DVI file. This DVI output can then be viewed using a DVI viewer like <i>xdvi</i>, or further converted into other formats such as PostScript using <i>dvips</i>, or PDF using <i>dvipdfm</i> or <i>dvipdfmx</i>. <br><br><b>grodvi</b> correctly handles character positioning, font selection, and graphic primitives generated by <i>groff</i>, ensuring that the final typeset document maintains its intended layout and appearance in a TeX-compatible environment. It is a crucial component for users who require <i>groff</i> documents to integrate into workflows centered around TeX/LaTeX.


title: CAVEATS
content:
<b>grodvi</b> produces DVI (DeVice Independent) files, which are intermediate representations. These files typically require a separate DVI viewer (like <i>xdvi</i>) or conversion to other formats (like PostScript or PDF) using tools such as <i>dvips</i> or <i>dvipdfm</i>/<i>dvipdfmx</i> for viewing or printing. Proper font setup for the TeX environment is often necessary for correct rendering of DVI files generated by <b>grodvi</b>.


title: INPUT AND OUTPUT
content:
<b>grodvi</b> reads its input from standard input or from the files specified on the command line. This input is expected to be in the <i>groff</i> intermediate output format, as generated by the <i>groff</i> preprocessors and main formatter. The command then writes the resulting DVI (DeVice Independent) file to standard output.


title: TYPICAL USAGE
content:
While <b>grodvi</b> can be run directly, it is most commonly invoked automatically by the <i>groff</i> command itself when the <code>-T dvi</code> option is specified. For example, <code>groff -T dvi document.roff > document.dvi</code> will process <code>document.roff</code> and pipe its intermediate output to <b>grodvi</b>, which then produces <code>document.dvi</code>.


title: HISTORY
content:
<b>grodvi</b> is an integral part of the GNU <i>troff</i> (<i>groff</i>) project, which was initiated by James Clark in the early 1990s as a free software re-implementation of the AT&T <i>troff</i> text formatter. The development of <b>grodvi</b> provided <i>groff</i> with the capability to generate output in the DVI format, making <i>groff</i> documents compatible with the TeX ecosystem. This expanded <i>groff</i>'s utility beyond its traditional PostScript (via <i>grops</i>) or plain text outputs, allowing users to leverage <i>groff</i> for documents intended for TeX-centric workflows and high-quality typesetting on various DVI-compatible output devices.


title: PARAMETERS
content:
<b><b>-e</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Preprocess the input with <i>eqn</i> for typesetting mathematical equations.<br><br><b><b>-p</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Preprocess the input with <i>pic</i> for drawing diagrams.<br><br><b><b>-t</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Preprocess the input with <i>tbl</i> for formatting tables.<br><br><b><b>-s</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Preprocess the input with <i>soelim</i> for handling `.so` requests (source inclusion).<br><br><b><b>-R</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Preprocess the input with <i>refer</i> for processing bibliographic references.<br><br><b><b>-z</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Preprocess the input with <i>grap</i> for drawing graphs.<br><br><b><b>-T</b><i>dev</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the output device. Common devices include <i>ps</i> (PostScript), <i>pdf</i>, <i>html</i>, <i>ascii</i> (plain text), and <i>dvi</i>.<br><br><b><b>-m</b><i>name</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Select a macro package to use (e.g., <i>man</i> for manual pages, <i>ms</i> for manuscripts, <i>mm</i> for memoranda).<br><br><b><b>-o</b><i>pages</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Output only the specified pages. Pages can be listed as ranges or individual numbers (e.g., `1-5`, `7`, `9-`).<br><br><b><b>-I</b><i>path</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Add <i>path</i> to the search path for include files (specified by `.so` requests).<br><br><b><b>-L</b><i>path</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Add <i>path</i> to the search path for macro files.<br><br><b><b>-P</b><i>arg</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Pass <i>arg</i> directly to the postprocessor, which renders the output for the specified device.<br><br><b><b>-U</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enable "unsafe" mode, allowing `groff` to use `open` and `exec` requests, which can pose security risks.<br><br><b><b>-V</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display version information and exit.<br><br><b><b>-v</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display a shorter version string and exit.<br><br><b><b>-W</b><i>warning</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Disable specific warnings (e.g., `Wwarn-all` for all warnings, `Wno-macro` for macro warnings).<br><br><b><b>-w</b><i>warning</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enable specific warnings (e.g., `wall` for all warnings, `wmacro` for macro warnings).<br><br>


title: DESCRIPTION
content:
<b>groff</b> is a <i>powerful</i> and <i>versatile</i> document formatting system, a free implementation of the classic <b>troff</b> typesetting program. It takes plain text files embedded with `roff` formatting requests and macro calls, processing them to produce high-quality output for various devices.<br><br>Originally developed for Unix, <b>groff</b> extends and enhances the functionality of its predecessors, <b>troff</b> and <b>nroff</b>. It is widely used in the Linux and Unix world, most notably for rendering <b>man</b> pages, but also for creating books, technical documentation, and reports.<br><br>The system's strength lies in its modularity and extensibility. It utilizes specialized <b>preprocessors</b> like <b>eqn</b> for equations, <b>pic</b> for diagrams, <b>tbl</b> for tables, and <b>refer</b> for bibliographies, allowing complex content to be embedded directly within the source document. Furthermore, <b>groff</b> supports various <b>macro packages</b> (e.g., <b>man</b>, <b>ms</b>, <b>mm</b>) that provide higher-level formatting commands, simplifying document creation.<br><br>Output can be generated in multiple formats, including PostScript, PDF, HTML, DVI, and plain text, making <b>groff</b> a flexible tool for a wide range of publishing needs. Despite its age, <b>groff</b> remains a fundamental component of many Unix-like operating systems.


title: CAVEATS
content:
Learning <b>groff</b> can be challenging due to its complex and often arcane syntax, which is rooted in its <b>troff</b> heritage. While extremely powerful for precise typesetting, modern users might find alternatives like <b>Markdown</b> or <b>LaTeX</b> easier for general document preparation. Its primary and most widespread use today is for formatting <b>man</b> pages, where its deep integration with the Unix ecosystem remains essential.


title: PREPROCESSORS
content:
<b>Groff</b> leverages a suite of specialized <b>preprocessors</b> to handle different types of content before the main <b>troff</b> formatter processes the document. Each preprocessor interprets its own markup language for a specific task. For example, <b>eqn</b> processes mathematical equations, <b>pic</b> draws diagrams, <b>tbl</b> formats tables, and <b>refer</b> manages bibliographic references. These tools allow complex, structured content to be seamlessly integrated into `roff` source files.


title: MACRO PACKAGES
content:
<b>Macro packages</b> in <b>groff</b> provide a higher-level abstraction over the basic `roff` commands, simplifying document creation. Instead of writing low-level formatting requests, users employ macros that represent common document structures (e.g., headings, paragraphs, lists). Popular packages include <b>man</b> (for manual pages), <b>ms</b> (for manuscripts), and <b>mm</b> (for memoranda). Selecting a macro package with the `<b>-m</b>` option significantly streamlines the document writing process.


title: OUTPUT DEVICES
content:
<b>Groff</b> is designed to produce output suitable for a variety of <b>devices</b> or formats, specified using the `<b>-T</b>` option. Common output devices include <b>ps</b> (PostScript), <b>pdf</b> (Portable Document Format), <b>html</b> (HyperText Markup Language), <b>ascii</b> (plain text), and <b>dvi</b> (Device Independent file format, often used with TeX systems). This versatility allows <b>groff</b> documents to be viewed, printed, or published in many contexts.


title: HISTORY
content:
<b>Groff</b> (<i>GNU troff</i>) is the GNU project's free software implementation of the <b>troff</b> and <b>nroff</b> text formatters, which originated in Bell Labs. Development of <b>groff</b> was started by <i>James Clark</i> in 1990, with the goal of creating a fully compatible replacement for the proprietary <i>troff</i>.<br><br>Since its inception, <b>groff</b> has become the standard typesetting system for most Unix-like operating systems, notably Linux. Its development has focused on maintaining compatibility with legacy <i>troff</i> documents and providing extensibility through modern features and support for various output formats. It has been crucial for the widespread adoption and consistent display of <b>man</b> pages across diverse systems.


title: PARAMETERS
content:
<b>-a, --apropos</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Interpret arguments as topics for <i>apropos</i>, searching man page descriptions.<br><br><b>-d, --device=<i>name</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set the output device to <i>name</i> (e.g., <b>ps</b>, <b>dvi</b>, <b>pdf</b>, <b>html</b>, <b>utf8</b>, <b>ascii</b>). This determines the final rendered format.<br><br><b>-D, --disable-detection</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Disable automatic detection of <i>groff</i> options for input files.<br><br><b>-e, --example</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display example output for the given arguments, demonstrating rendering.<br><br><b>-f, --font=<i>name</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set the base font to <i>name</i> for the output document.<br><br><b>-F, --font-path=<i>dir</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Add <i>dir</i> to the font search path for <i>groff</i>.<br><br><b>-g, --groff-option=<i>string</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Pass <i>string</i> directly as an option to the underlying <i>groff</i> command.<br><br><b>-h, --help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display a help message and exit.<br><br><b>-I, --include-path=<i>dir</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Add <i>dir</i> to the <i>groff</i> include search path for `.so` requests.<br><br><b>-k, --keyword</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Treat arguments as keywords to search for within man page content.<br><br><b>-K, --language=<i>lang</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set the language for man page lookup, e.g., <b>en</b>, <b>de</b>.<br><br><b>-L, --list-devices</b><br>&nbsp;&nbsp;&nbsp;&nbsp;List all available output devices and exit.<br><br><b>-m, --macro=<i>name</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Use the specified macro package <i>name</i> (e.g., <b>man</b>, <b>mdoc</b>) for processing.<br><br><b>-M, --macro-path=<i>dir</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Add <i>dir</i> to the macro search path for <i>groff</i>.<br><br><b>-n, --number</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Number the output pages.<br><br><b>-o, --output-file=<i>file</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Redirect output to <i>file</i> instead of displaying it in a pager.<br><br><b>-O, --pager-option=<i>string</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Pass <i>string</i> directly as an option to the pager program (e.g., <i>less</i>).<br><br><b>-p, --paper-size=<i>size</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set the paper size to <i>size</i> (e.g., <b>a4</b>, <b>letter</b>).<br><br><b>-P, --pager=<i>pager</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Use <i>pager</i> instead of the default <i>less</i> or system-configured pager.<br><br><b>-r, --request=<i>name</i>=<i>value</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set a <i>groff</i> request <i>name</i> to <i>value</i>.<br><br><b>-R, --raw</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Do not process input with <i>groff</i>; display raw content without formatting.<br><br><b>-s, --section=<i>section</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Search for man pages only in the specified <i>section</i> (e.g., <b>1</b>, <b>8</b>).<br><br><b>-S, --stand-alone</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Do not use <i>groff</i> or a pager; output raw processed content directly to stdout.<br><br><b>-t, --tab-width=<i>width</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set the tab width for processing input to <i>width</i> characters.<br><br><b>-T, --terminal=<i>name</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Use <i>name</i> as the terminal type (for <i>groff -T</i>).<br><br><b>-u, --update</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Update man page caches (similar to <i>mandb</i>).<br><br><b>-U, --usage</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display a brief usage message and exit.<br><br><b>-v, --version</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display version information and exit.<br><br><b>-w, --whatis</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Interpret arguments as topics for <i>whatis</i>, displaying one-line descriptions.<br><br><b>-W, --warning=<i>category</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enable warnings for a specific <i>category</i> (e.g., <b>all</b>, <b>missing</b>).<br><br><b>-z, --compress-output</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Compress the output if writing to a file (requires <i>gzip</i> or similar).<br><br><b>--debug</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display detailed debug information about processing.<br><br><b>--license</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display license information and exit.<br><br><b>--pager-debug</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display debug information related to the pager command.<br><br><b>--strict</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Abort processing on the first error encountered.<br><br>


title: DESCRIPTION
content:
<i>groffer</i> is a versatile command-line utility for viewing <i>groff</i> files, <i>man</i> pages, and plain text documents on Unix-like systems. It acts as a sophisticated pager that automatically detects the type of input file and applies appropriate <i>groff</i> processing before displaying the formatted output. It can handle compressed files and supports various output devices, rendering documents into formats like PostScript, PDF, DVI, HTML, or plain text. <br>The primary use case is to provide a rich viewing experience for documents that would traditionally be processed by <i>groff</i>, including system manual pages, offering features like syntax highlighting and convenient navigation through an external pager like <i>less</i>. It intelligently determines the correct <i>groff</i> macros and options required for proper rendering, simplifying the viewing process for complex documentation.


title: CAVEATS
content:
<i>groffer</i> relies heavily on the underlying <i>groff</i> system and the configured pager (usually <i>less</i>). Issues with these dependencies can affect its functionality. Automatic detection can sometimes fail for unusual or malformed <i>groff</i> files. The <i>man</i> page features (sections, language, keywords) depend on a properly configured <i>man-db</i> or similar system. Rendering to graphical devices like PDF requires a <i>groff</i> device driver and potentially external tools (e.g., <i>ghostscript</i> for PostScript).


title: AUTOMATIC DETECTION
content:
<i>groffer</i> intelligently attempts to determine the best way to process a file by examining its content and common file extensions. This includes identifying <i>groff</i> macro packages (like <b>man</b> or <b>mdoc</b>), character encodings, and compression types. This feature greatly simplifies viewing complex documents as users don't need to specify <i>groff</i> options manually.


title: PAGER INTEGRATION
content:
By default, <i>groffer</i> pipes its processed output to a pager, typically <i>less</i>. This integration allows for interactive viewing, searching, and navigation within the document, providing a much richer experience than simple <i>cat</i> to <i>stdout</i>. The pager can be customized using the <b>GROFFER_PAGER</b> environment variable or the <b>-P</b> option.


title: ENVIRONMENT VARIABLES
content:
<i>groffer</i> can be configured via several environment variables, such as <b>GROFFER_PAGER</b> (to specify a pager), <b>GROFFER_COMMAND_PATH</b> (for additional command search paths), <b>GROFFER_GROFF_COMMAND</b> (to override the <i>groff</i> command), and others. These provide granular control over its behavior.


title: HISTORY
content:
<i>groffer</i> was developed as a more advanced and user-friendly front-end for viewing <i>groff</i> documents, especially <i>man</i> pages, compared to directly piping <i>groff</i> output to a pager. It aims to simplify the process by automating the detection of file types and <i>groff</i> options, providing a seamless viewing experience. Its design emphasizes convenience and flexibility, allowing users to customize viewing parameters and integrate with various output devices and pagers. The command has been maintained as part of the <i>groff</i> project, evolving to support new features and address user needs for document viewing.


title: PARAMETERS
content:
<b><b>-v</b>, <b>--version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays the version information for <b>grog</b> and then exits.<br>This is a common GNU utility option found in many commands.<br><br><b><i>files</i>...</b><br>&nbsp;&nbsp;&nbsp;&nbsp;One or more input files to be scanned by <b>grog</b>.<br>If no files are specified, <b>grog</b> reads from standard input, allowing it to be used in a pipeline.<br><br>


title: DESCRIPTION
content:
<b>grog</b> is a utility program integrated within the <i>GNU groff</i> (<i>GNU roff</i>) document formatting system. Its primary purpose is to analyze a given input document and intelligently determine the appropriate <b>groff</b> command-line options and arguments required for its correct processing.<br>This tool is especially valuable for documents that utilize various <b>groff</b> preprocessors (such as <i>eqn</i> for equations, <i>pic</i> for graphics, <i>tbl</i> for tables, or <i>refer</i> for bibliographies) or specific macro packages (like <i>ms</i>, <i>mm</i>, <i>me</i>, or <i>mandoc</i>).<br>By outputting the detected options to standard output, <b>grog</b> significantly simplifies the compilation process, helping users automate the <b>groff</b> command line without needing to manually identify all required arguments for complex documents.


title: CAVEATS
content:
<b>grog</b> provides an <i>educated guess</i>; it might not always be perfectly accurate for all <b>groff</b> documents, especially those with highly complex, non-standard, or conditionally compiled structures.<br>It primarily relies on scanning for specific directive patterns (e.g., lines starting with <b>.</b> or <b>."</b>) and preprocessor calls, which may not cover every possible <b>groff</b> configuration.<br>Its output is designed to be used with shell command substitution (e.g., <i>groff</i> `<i>grog file</i>`) to automatically pass the detected options to the <b>groff</b> command. <b>grog</b> itself does not execute <b>groff</b> directly after printing its suggestions.


title: USAGE EXAMPLE
content:
<b>grog</b> is most commonly utilized in shell scripts with command substitution to automatically pass its detected options to the <b>groff</b> command.<br>For instance, to format a document named <i>my_document.mom</i> that might contain mathematical equations (<i>eqn</i>) and uses the <i>mom</i> macro package, you would typically execute:<br><i>groff</i> `<i>grog my_document.mom</i>` <i>> my_document.pdf</i><br>In this command, `<i>grog my_document.mom</i>` would output options such as <b>-e -Tps -mom my_document.mom</b>, which are then substituted directly into the <b>groff</b> command line by the shell, simplifying the formatting process.


title: HISTORY
content:
<b>grog</b> is an integral part of the <i>GNU groff</i> project, which is the GNU implementation of the classic <i>roff</i> and <i>troff</i> text formatting systems.<br>The original <i>roff</i> (<i>Reversed Off</i>) formatters were developed at Bell Labs in the 1970s, with <i>troff</i> being the typesetting version.<br>James Clark initiated the <i>GNU groff</i> project in the early 1990s to create a free software replacement for <i>troff</i>.<br><b>grog</b> was developed as a complementary utility to simplify the invocation of <b>groff</b>.<br>It automates the tedious process of identifying necessary preprocessor and macro options for a given document, thereby making the powerful <b>groff</b> system more accessible and user-friendly, especially in automated scripting scenarios.


title: SYNOPSIS
content:
<code>grohtml [<b>-hlr</b>] [<b>-s </b><i>number</i>] [<b>-a </b><i>all-char</i>] [<b>-D </b><i>directory</i>] [<b>-F </b><i>directory</i>] [<b>-o </b><i>name</i>] [<b>-S </b><i>number</i>] [<b>-V</b>]</code><br>or<br><code>groff <b>-Thtml</b> <i>[options] files...</i> | grohtml [<i>options</i>]</code>


title: PARAMETERS
content:
<b><b>-h</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays usage information and exits.<br><br><b><b>-l</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Disables linking for cross-references, footnotes, and external links.<br><br><b><b>-r</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Turns off character replacement, useful for debugging or when <b>HTML</b> entities are not desired.<br><br><b><b>-s <i>number</i></b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the base font size for the <b>HTML</b> output. The <i>number</i> usually refers to font size in points.<br><br><b><b>-a <i>all-char</i></b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies a character to be used for unavailable (alternative) characters in the output.<br><br><b><b>-D <i>directory</i></b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the output <i>directory</i> when the <b>-S</b> option is used to split the document into multiple files.<br><br><b><b>-F <i>directory</i></b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Adds <i>directory</i> to the search path for font description files. This is useful for custom font definitions.<br><br><b><b>-o <i>name</i></b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the output file <i>name</i>. If not provided, output goes to standard output.<br><br><b><b>-S <i>number</i></b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Splits the document into multiple <b>HTML</b> files. The <i>number</i> indicates the maximum section level that will trigger a split.<br><br><b><b>-V</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays the version information of <b>grohtml</b> and exits.<br><br>


title: DESCRIPTION
content:
<b>grohtml</b> is a backend driver for the <b>groff</b> (GNU <b>roff</b>) document formatting system. Its primary purpose is to convert the intermediate output of <b>groff</b> into <b>HTML</b> (HyperText Markup Language) format. This enables <b>groff</b> documents, commonly used for man pages and technical documentation, to be rendered and viewed directly in web browsers.<br><br><b>grohtml</b> intelligently handles various <b>groff</b> features, including tables, equations (processed by <b>eqn</b>), and cross-references, translating them into suitable <b>HTML</b> structures. It provides support for different character sets and <b>HTML</b> entities, ensuring the correct display of special characters.<br><br>While typically invoked indirectly by the <b>groff</b> command using the <b>-Thtml</b> option (e.g., <code>groff <b>-Thtml</b> <i>filename</i></code>), it can also be run standalone. The output is usually a single <b>HTML</b> file, but it possesses the capability to generate multiple linked files for large documents, facilitating easier navigation. The generated <b>HTML</b> strives for semantic correctness, often benefiting from external <b>CSS</b> for tailored visual presentation.


title: CAVEATS
content:
The <b>HTML</b> generated by <b>grohtml</b> is primarily semantic, meaning it focuses on content structure rather than visual presentation. For aesthetically pleasing output, users often need to provide custom <b>CSS</b> stylesheets.<br><br>While <b>grohtml</b> handles many <b>groff</b> features, some very complex formatting or specific <i>troff</i> escape sequences might not have a direct or perfect <b>HTML</b> equivalent, potentially leading to slight rendering discrepancies. The output can sometimes be verbose, especially for heavily formatted documents.


title: <B>TYPICAL USAGE</B>
content:
While <b>grohtml</b> can be run standalone, it is most commonly invoked by the <b>groff</b> command using the <b>-Thtml</b> option. For instance, to convert a man page source file (<code><i>myfile.man</i></code>) to <b>HTML</b> and save it as <code><i>myfile.html</i></code>, you would typically use:<br><code>groff <b>-Thtml</b> <i>myfile.man</i> > <i>myfile.html</i></code><br><br>This command first processes <code><i>myfile.man</i></code> with <b>groff</b>, which then pipes its intermediate output to <b>grohtml</b>, and the final <b>HTML</b> is redirected to <code><i>myfile.html</i></code>.


title: <B>CHARACTER ENTITIES AND ENCODING</B>
content:
<b>grohtml</b> aims to produce valid <b>HTML</b>, using character entities (e.g., <code>&amp;amp;</code>, <code>&amp;lt;</code>) for special characters and supporting various character sets. This ensures that the formatted output displays correctly across different browsers and platforms.


title: <B>INTEGRATION WITH PREPROCESSORS</B>
content:
<b>grohtml</b> works seamlessly with <b>groff</b>'s powerful preprocessors such as <b>eqn</b> (for equations), <b>tbl</b> (for tables), and <b>pic</b> (for diagrams). When <b>groff</b> processes a document containing these preprocessor commands, their output is transformed into suitable <b>HTML</b> equivalents (e.g., tables into <code>&lt;table&gt;</code> tags, equations often into images or MathML, though images are more common with <b>grohtml</b>).


title: HISTORY
content:
<b>grohtml</b> is an integral part of the <b>groff</b> (GNU <b>roff</b>) project, which was initiated by James Clark in the late 1980s as a free software replacement for the proprietary <i>troff</i> text formatter. As web technologies gained prominence, <b>grohtml</b> was developed as a backend driver for <b>groff</b> to enable the conversion of <b>groff</b> documents into <b>HTML</b>, thereby making them accessible and viewable in web browsers. Its development paralleled the increasing need to present traditional Unix documentation (like man pages) on the web.


title: PARAMETERS
content:
<b><i>-F dir</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prepend <i>dir/fonttab</i> to the font search path. This allows <i>grolbp</i> to locate font description files in custom directories.<br><br><b><i>-p paper_size</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set the output paper size. Common values include <i>A4</i>, <i>A3</i>, <i>Letter</i>, and <i>Legal</i>, configuring the page dimensions for the CAPSL output.<br><br><b><i>-l</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Output in landscape orientation. By default, pages are printed in portrait mode.<br><br><b><i>-s</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Simulate bold characters by overstriking. This is the default behavior and is useful for printers without distinct bold fonts.<br><br><b><i>-S</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Do not simulate bold characters by overstriking. Characters will be printed without overstriking.<br><br><b><i>-C</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enable compatibility mode. In this mode, <i>grolbp</i> attempts to handle or ignore certain <i>groff</i>-specific commands for broader compatibility with various CAPSL environments.<br><br><b><i>-o num</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Start page numbering at <i>num</i>. This can be useful for printing sections of a larger document.<br><br><b><i>-r num</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Rotate pages by <i>num</i> degrees. Common values are 90, 180, or 270 degrees, allowing for page orientation adjustments.<br><br><b><i>-P</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enable variable pitch font selection for characters. By default, <i>grolbp</i> might use fixed-pitch fonts; this option allows for more flexible font rendering if the printer supports it.<br><br><b><i>-T dev</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set the output device. For <i>grolbp</i>, this is intrinsically <i>lbp</i>. While often specified with <i>groff</i> (e.g., <i>groff -Tlbp</i>), <i>grolbp</i> can accept it without altering its fundamental output type.<br><br><b><i>-v</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Print the version number of <i>grolbp</i> to standard output and exit.<br><br>


title: DESCRIPTION
content:
<i>grolbp</i> is a GNU <i>groff</i> output driver specifically designed to convert <i>groff</i> intermediate output into Canon CAPSL (Canon Advanced Printing System Language) commands. These commands are understood by older Canon LBP-4 and LBP-8 series laser printers, as well as compatible models. It functions as a backend processor, typically receiving its input via a pipe from the <i>groff</i> formatter. Its primary role is to interpret the typesetting and formatting commands generated by <i>groff</i> (such as font selection, character positioning, line drawing, and page layout) and translate them into the specific escape sequences and control codes required by CAPSL-compatible printers. While historically significant for supporting a particular range of printers, its use has significantly declined with the widespread adoption of more universal printer languages like PostScript and PCL, which are supported by drivers such as <i>grops</i> and <i>grolj4</i>.


title: CAVEATS
content:
<i>grolbp</i> is primarily designed for older Canon LBP-4/LBP-8 series printers and compatibles that utilize the proprietary CAPSL language. Its utility is significantly diminished in modern computing and printing environments, where printers overwhelmingly rely on industry-standard languages like PostScript or PCL. For broader compatibility with contemporary printers, users should typically employ <i>grops</i> (for PostScript) or <i>grolj4</i> (for PCL) instead.


title: USAGE WITH GROFF
content:
<i>grolbp</i> typically does not process raw <i>roff</i> source files directly. Instead, it consumes the intermediate output generated by the <i>groff</i> formatter. The common usage pattern involves piping the output of <i>groff</i> to <i>grolbp</i>:<br><b>groff -Tlbp <i>document.roff</i> | grolbp > <i>document.capsl</i></b><br>In this example, <b>groff</b> first formats <i>document.roff</i> for the <i>lbp</i> device and then sends its intermediate output to <b>grolbp</b>, which converts it into CAPSL commands, redirecting them to <i>document.capsl</i>.


title: CAPSL LANGUAGE
content:
Canon Advanced Printing System Language (CAPSL) is a proprietary page description language used by certain Canon laser printers. It dictates how text, graphics, and images are rendered on a page through a sequence of control codes and escape sequences. Unlike more open standards, CAPSL is typically more low-level and tailored to specific Canon hardware capabilities. <i>grolbp</i>'s primary function is to translate the generic <i>groff</i> output into this specific printer language.


title: HISTORY
content:
<i>grolbp</i> is an integral component of the GNU <i>groff</i> project, which commenced development in the early 1990s as a free and open-source re-implementation of AT&T's <i>troff</i> typesetting system. As laser printers gained widespread adoption, specialized drivers like <i>grolbp</i> were developed to support various printer control languages, including proprietary ones such as Canon's CAPSL. Its existence reflects an era when specific drivers were crucial for interacting with diverse hardware, predating the widespread standardization provided by languages like PostScript.


title: DESCRIPTION
content:
The command <i>grolj4</i> does not appear to be a standard or commonly recognized command in typical Linux distributions. Searches for its manual page, executable, or general documentation yield no results.<br><br>It is possible that <i>grolj4</i> is a typo, a highly specialized internal command within a very specific system, or a placeholder name. Users are advised to double-check the command name for any errors or consult the documentation specific to their system if they believe it should exist.


title: CAVEATS
content:
This command name is not found in standard Linux command repositories or documentation. It is highly probable that it does not exist or is a misinterpretation of another command.


title: VERIFICATION
content:
Attempts to locate a manual page (e.g., <code>man grolj4</code>), an executable file (e.g., <code>which grolj4</code>), or any online documentation for <i>grolj4</i> were unsuccessful. This strongly indicates the command does not exist in common Linux environments.


title: PARAMETERS
content:
<b><B>-u, --ungron</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Reconstructs JSON from the <I>gron</I> format. This effectively reverses the <I>gron</I> transformation, converting assignments back into a valid JSON document.<br><br><b><B>-a, --all-values</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Includes all values in the output, even if they are <I>null</I> or empty arrays/objects. By default, <I>gron</I> omits such values.<br><br><b><B>-s, --stream</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Reads the input as a continuous stream of JSON objects, processing each one individually. This is useful for handling large log files or continuous data streams.<br><br><b><B>-j, --json</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;When used with <B>-u</B> (<I>ungron</I>), outputs the reconstructed JSON in a compact, single-line format.<br><br><b><B>-y, --yaml</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;When used with <B>-u</B> (<I>ungron</I>), outputs the reconstructed data in YAML format instead of JSON.<br><br><b><B>-c, --color</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables colorized output for better readability of the <I>gron</I> assignments in a terminal.<br><br><b><B>-m, --monochrome</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Disables colorized output, which can be useful when piping <I>gron</I> output to other commands or in terminals that do not support colors.<br><br><b><B>-p, --obj-prefix &lt;prefix&gt;</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Adds a custom string prefix to all variable names in the <I>gron</I> output. For example, <B>--obj-prefix 'mydata'</B> would result in assignments like <I>mydata.json.key = ...</I>.<br><br><b><B>--no-sort</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Disables sorting of object keys in the output. This can lead to more predictable output order, especially useful for diffing or consistent processing.<br><br><b><B>--indent &lt;spaces&gt;</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the number of spaces to use for indentation when outputting formatted JSON or YAML (typically with <B>-u</B>).<br><br><b><B>-h, --help</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a help message with available options and exits.<br><br><b><B>-v, --version</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints the <I>gron</I> version information and exits.<br><br>


title: DESCRIPTION
content:
<I>gron</I> is a powerful command-line utility that transforms JSON data into a series of discrete, newline-separated assignments. This unique transformation flattens complex, nested JSON structures, making them exceptionally amenable to standard Unix text processing tools such as <I>grep</I>, <I>awk</I>, and <I>sed</I>.<br><br>Instead of navigating intricate JSON paths, <I>gron</I> represents each value with a unique, dot-separated path, like <I>json.data[0].id = 123;</I>. This flat, assignment-based format allows users to easily search for specific values, patterns, or modify data within JSON documents using familiar text commands, eliminating the need for specialized JSON parsers for many tasks.<br><br>A key feature of <I>gron</I> is its 'round-trip' capability. After processing or filtering the <I>gron</I> output with other tools, the modified data can be piped back into <I>gron -u</I> (or the alias <I>ungron</I>) to reconstruct the original or modified JSON structure. This makes <I>gron</I> an incredibly versatile tool for debugging, inspecting API responses, automating data transformations, and generally leveraging the Unix philosophy on structured data.


title: CAVEATS
content:
While powerful, <I>gron</I> can produce very large output files for extensive JSON documents, potentially impacting performance or memory usage. Modifying the <I>gron</I> output manually requires careful adherence to its specific assignment syntax; any errors can lead to parsing failures when attempting to <I>ungron</I> back into JSON. <I>gron</I> expects valid JSON input and may not handle malformed data gracefully.


title: ROUND-TRIP TRANSFORMATION
content:
<I>gron</I>'s fundamental strength lies in its ability to perform a 'round-trip' transformation. You can convert JSON to the <I>gron</I> format, process or filter it using standard Unix tools (like <I>grep</I>, <I>sed</I>, <I>awk</I>), and then pipe the modified <I>gron</I> output back into <I>gron -u</I> (or <I>ungron</I>) to reconstruct a valid, modified JSON document. This makes it incredibly flexible for data manipulation workflows that benefit from the power of line-oriented text processing.


title: INTEGRATION WITH UNIX TOOLS
content:
<I>gron</I> is explicitly designed for seamless interoperability with traditional Unix command-line tools. By flattening structured JSON into simple, line-oriented text assignments, it allows users to apply a vast ecosystem of text processing commands that were not originally designed for hierarchical data. This integration makes otherwise complex JSON manipulation tasks straightforward and highly scriptable, fitting perfectly within the Unix philosophy of small, specialized tools working together.


title: HISTORY
content:
<I>gron</I> was created by Tomas Lindberg and first released around 2016. Its development was inspired by the need for a simple, Unix-philosophy-aligned tool to make JSON data easily searchable and manipulable with existing text-processing utilities. Before <I>gron</I>, users often had to rely on more complex tools like <I>jq</I> for even basic searches, or write custom scripts. <I>gron</I> filled a niche by allowing users to directly leverage their existing <I>grep</I>/<I>sed</I>/<I>awk</I> knowledge on JSON structures, providing a simpler and highly effective alternative for common use cases. Its adoption grew rapidly within the DevOps, system administration, and data analysis communities for its utility in handling JSON-formatted log files and API responses.


title: DESCRIPTION
content:
<i>The command <b>grops</b> is not a recognized or standard utility in common Linux distributions. A thorough search of official documentation, common manual pages, and widely used system utilities reveals no such command. It is highly probable that <b>grops</b> is a typographical error. Common similar-sounding commands include <b>groups</b>, which is used to display the group memberships for a user, or <b>grep</b>, a powerful tool for searching plain-text data sets for lines that match a regular expression.<br><br>As <b>grops</b> does not exist as a standard command, it lacks a defined syntax, specific parameters, a documented history of development, or related tools. Any attempt to execute <b>grops</b> in a Linux shell will typically result in a "command not found" error message, indicating that the shell cannot locate an executable file with that name in the directories specified by the system's PATH environment variable. Therefore, specific analysis regarding its functionality, options, or usage cannot be provided.</i>


title: CAVEATS
content:
<i>This command does not exist in standard Linux distributions. Attempting to use it will result in a "command not found" error message from your shell.</i>


title: HISTORY
content:
<i>N/A - As <b>grops</b> is not a standard or historical Linux command, there is no development or usage history to describe.</i>


title: PARAMETERS
content:
<b><b>-b</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Suppress the use of backspace characters for overstruck characters. This can be useful for terminals that don't handle backspaces correctly or for producing cleaner plain text.<br><br><b><b>-E</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Do not output error messages generated by the <i>troff</i> preprocessor. This can make the output cleaner by silencing formatting warnings.<br><br><b><b>-F</b> <i>dir</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Search for font and device description files in the specified <i>dir</i> before checking standard locations. Useful for custom groff setups.<br><br><b><b>-l</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Use the Latin-1 (ISO 8859-1) character set for output. This is often the default or preferred for terminals supporting Latin-1 characters, allowing for a wider range of displayable glyphs than pure ASCII.<br><br><b><b>-R</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Do not use reverse line feeds (half-line movements). This might be necessary for some older or specialized terminals that do not support this feature, which is sometimes used for precise vertical positioning.<br><br><b><b>-u</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Use the underscore character (<code>_</code>) for underlining, rather than backspace-overstriking. This is a simpler method suitable for terminals where backspace-overstrike might not render correctly or be desired.<br><br><b><b>-v</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Print the version number of <i>grotty</i> to standard error and exit.<br><br><b><b>-X</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Output XON/XOFF flow control characters. This enables software flow control, which can be useful for managing data flow between <i>grotty</i> and a terminal that supports it.<br><br>


title: DESCRIPTION
content:
<i>grotty</i> is a device driver for the GNU <i>roff</i> (groff) text formatting system. Its primary function is to translate <i>groff</i> intermediate output, typically generated by <i>troff</i> or <i>nroff</i>, into a plain ASCII or Latin-1 format suitable for display on character-mode terminals or printers. <br><br>While <i>groff</i> itself is a powerful typesetter capable of producing high-quality output formats like PostScript or PDF, <i>grotty</i> specifically handles the rendering for simpler, text-only environments. It achieves text effects like <b>bold</b>, <i>italic</i>, and underlining using techniques such as backspacing and overstriking characters, or by representing italics with underscores. This makes it indispensable for displaying formatted text, most notably Linux <b>man</b> pages, directly in a terminal.<br><br>It's often used in pipelines, for example, `man <command>` (though <b>man</b> typically handles this internally) or `groff -Tlatin1 -P-o -mandoc <file> | grotty`, ensuring that documents formatted with <i>roff</i> macros are legible on any standard terminal.


title: CAVEATS
content:
<b>Limited Formatting:</b> <i>grotty</i> can only render text-based formatting. Complex layouts, images, or advanced typography from <i>groff</i> are lost.<br><b>Terminal Dependence:</b> The quality of output (especially for bolding and underlining) depends heavily on the terminal emulator's ability to interpret backspaces and overstrikes.<br><b>Character Set Issues:</b> Incorrect terminal encoding settings can lead to garbled characters, particularly when using the <b>-l</b> (Latin-1) option.


title: HOW OUTPUT IS FORMATTED
content:
<i>grotty</i> achieves effects like <b>bold</b> and <i>italic</i> by using backspace characters (representing <code>\b</code>) to overstrike characters. For example, writing 'o', then backspacing and writing another 'o' can produce a bold 'o'. Underlining is typically done by overstriking with an underscore. This method relies on the terminal correctly interpreting and displaying these sequences, which is standard for most modern terminal emulators.


title: COMMON USAGE PATTERN
content:
Although <i>grotty</i> can be invoked directly, it's most commonly used implicitly as part of the <i>groff</i> command or through wrappers like <i>man</i>. For instance, `groff -Tlatin1 -mandoc mydoc.roff | grotty | less` would format a <i>roff</i> document for Latin-1, pipe it through <i>grotty</i> for text rendering, and then display it using the <i>less</i> pager.


title: HISTORY
content:
<i>grotty</i> is an integral part of the GNU <i>groff</i> project, which began in the late 1980s by James Clark as a free software replacement for the proprietary AT&T <i>troff</i> text formatting system. Prior to <i>groff</i>, formatting for text-only terminals was typically handled by <i>nroff</i>. <i>grotty</i> was developed to provide a robust, modern alternative for rendering <i>groff</i>'s intermediate output to plain text, maintaining compatibility with the existing <i>roff</i> ecosystem while offering enhancements and portability across various Unix-like systems. Its design reflects the need to display complex formatted documents like man pages effectively on basic character-mode terminals, which were prevalent at the time of its inception.


title: SYNOPSIS
content:
<code>groupadd [<i>options</i>] <i>GROUP</i></code><br><br><i>Arguments:</i><br><b>GROUP</b><br>The name of the new group to be created.


title: PARAMETERS
content:
<b>-g GID, --gid GID</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the Group ID (GID) of the new group. If not specified, a unique GID is automatically assigned by the system, typically the next available above a certain threshold (e.g., 1000).<br><br><b>-r, --system</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Create a system group. System groups usually have a GID below a certain threshold (e.g., 1000 on many systems) and are intended for system services or daemon accounts, rather than human users.<br><br><b>-f, --force</b><br>&nbsp;&nbsp;&nbsp;&nbsp;If the group already exists, <b>groupadd</b> will normally exit with an error. The <i>-f</i> option forces the command to exit with success if the group already exists, but it does not create a new entry in this case.<br><br><b>-K KEY=VALUE, --key KEY=VALUE</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Override default values for new groups as specified in the <i>/etc/login.defs</i> file. For example, <i>-K GID_MIN=1000</i> could override the minimum GID for regular groups.<br><br><b>-o, --non-unique</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Allow creation of a group with a non-unique GID. This option is primarily used in conjunction with <i>-g</i> to create multiple groups that share the same GID, which is generally not recommended for standard setups.<br><br><b>-p PASSWORD, --password PASSWORD</b><br>&nbsp;&nbsp;&nbsp;&nbsp;An encrypted password for the new group. This password will be placed in the <i>/etc/gshadow</i> file. It is generally recommended to use the <b>gpasswd</b> command to manage group passwords after group creation for better security.<br><br>


title: DESCRIPTION
content:
The <b>groupadd</b> command is used on Linux and Unix-like operating systems to create new group accounts. When a new group is created, an entry is added to the <i>/etc/group</i> file, which maps group names to Group IDs (GIDs). Optionally, an entry may also be created in the <i>/etc/gshadow</i> file if group passwords or administrators are configured.<br><br>This command is crucial for managing system permissions and access control, as users can be members of one or more groups. Files and directories can then be assigned group ownership, allowing multiple users within that group to have specific permissions. By default, <b>groupadd</b> assigns the next available GID above the system range, or within the system range if the <i>-r</i> (system group) option is used. Root privileges are required to execute this command successfully.


title: CAVEATS
content:
&bull; <b>Root Privileges Required</b>: Only the root user or a user with appropriate sudo privileges can execute <b>groupadd</b>.<br>&bull; <b>GID Conflicts</b>: Without the <i>-o</i> option, <b>groupadd</b> will fail if the specified GID (via <i>-g</i>) is already in use.<br>&bull; <b>Name Uniqueness</b>: Group names must be unique on the system. If the specified group name already exists, the command will fail unless <i>-f</i> is used, which makes it exit successfully without creating a duplicate entry.


title: DEFAULT CONFIGURATION
content:
The default behavior of <b>groupadd</b>, such as the ranges for system and regular Group IDs (GIDs), is configured in the <i>/etc/login.defs</i> file. Administrators can modify these settings to customize group creation to fit their specific system requirements.


title: RELATED GROUP FILES
content:
New group entries created by <b>groupadd</b> are primarily appended to the <i>/etc/group</i> file, which lists all groups and their members. If group passwords or group administrators are set (e.g., using <i>-p</i> or subsequent <b>gpasswd</b> commands), an entry is also created or updated in the <i>/etc/gshadow</i> file, which stores encrypted group passwords and group administration details securely.


title: HISTORY
content:
<b>groupadd</b> is a fundamental command, typically part of the <i>shadow-utils</i> package (or similar on other Unix-like systems), which provides essential tools for managing user and group accounts on Linux systems. Its development mirrors the evolution of secure account management practices on Unix, with a focus on separating sensitive password information into dedicated 'shadow' files (like <i>/etc/gshadow</i>) for enhanced security.


title: PARAMETERS
content:
<b><I>GROUP</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The name of the group to be removed from the system. This argument is mandatory.<br><br>


title: DESCRIPTION
content:
The <b>groupdel</b> command is used to remove a group definition from the local system’s account files, typically <i>/etc/group</i> and <i>/etc/gshadow</i>. This operation is critical for maintaining a clean and accurate user and group database. For the command to succeed, it is imperative that no user currently has the group being deleted as their primary group. If any user's primary group is the one being deleted, the command will fail, and such users must first be assigned a different primary group using tools like <b>usermod</b>. Users who are secondary (supplementary) members of the deleted group will automatically have that group removed from their supplementary group list, ensuring consistency. This command is a fundamental tool for system administrators to efficiently manage and maintain group accounts on a Linux or Unix-like system, contributing to proper access control and security.


title: CAVEATS
content:
<b>Primary Group Conflict:</b> <b>groupdel</b> will fail if the specified group is the primary group for any user. All such users must be re-assigned a different primary group before the group can be deleted.<br><b>File Ownership:</b> Deleting a group does not change the group ownership of existing files. Files previously owned by the deleted group will display the numeric Group ID (GID) instead of a group name. Manual intervention (e.g., using <b>chgrp</b>) is required to re-assign ownership.<br><b>System Groups:</b> Deleting system-level groups (typically GIDs below 1000, though this can vary by distribution) can have unintended consequences and is generally not recommended unless absolutely necessary.


title: GID REUSE AND SECURITY
content:
When a group is deleted, its Group ID (GID) becomes available for reuse. If a new group is subsequently created with the same GID, it could potentially inherit ownership of files or directories that were previously owned by the old group, leading to unexpected permissions or security issues if not properly managed. It is important to audit file ownership after group deletions, especially if GIDs are reused.


title: HISTORY
content:
<b>groupdel</b> is part of the <i>shadow-utils</i> package, which provides a comprehensive set of tools for managing user and group accounts, including support for shadow passwords. This command has been a staple in Linux and Unix-like environments for many years, offering a standardized and reliable way to remove group entries from the system’s configuration files. Its core functionality has remained largely consistent across different distributions and versions.


title: SYNOPSIS
content:
<i>groupmems</i> [<i>options</i>]<br><i>groupmems</i> [<b>-g</b> <i>group</i>] [<b>-a</b> <i>user</i> | <b>-d</b> <i>user</i> | <b>-l</b>]


title: PARAMETERS
content:
<b><b>-g</b> <i>group</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the target group to administer. If omitted, the current user's primary group is typically assumed.<br><br><b><b>-a</b> <i>user</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Adds the specified <i>user</i> to the group. This operation requires appropriate administrative privileges for the target group.<br><br><b><b>-d</b> <i>user</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Removes the specified <i>user</i> from the group. This operation also requires appropriate administrative privileges.<br><br><b><b>-l</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Lists the current members of the group. This option can usually be run without administrative privileges if the group is readable.<br><br>


title: DESCRIPTION
content:
<i>groupmems</i> is a utility designed for <b>group administrators</b> to manage the membership list of groups they administer. Unlike commands like <i>usermod</i> or <i>gpasswd</i>, which often require <i>root privileges</i> for broader user and group modifications, <i>groupmems</i> provides a more targeted approach. It allows a user who is designated as a group administrator (e.g., by being the primary group owner of the target group, or listed in <i>/etc/gshadow</i>) to <b>add or remove users</b> from <i>that specific group</i>. This delegation of control is valuable in multi-user environments, enabling non-root users to perform specific administrative tasks without compromising overall system security. The command ensures that only authorized administrators can modify a group's members, reflecting changes in <i>/etc/group</i> and <i>/etc/gshadow</i>.


title: CAVEATS
content:
The invoking user must have appropriate administrative privileges for the target group, typically by being the group's primary owner or explicitly listed as an administrator in <i>/etc/gshadow</i>. Without these permissions, modification attempts will fail. This command does not change a user's primary group affiliation. Changes made by <i>groupmems</i> are immediately reflected in the system's user and group configuration files (e.g., <i>/etc/group</i>, <i>/etc/gshadow</i>).


title: REQUIRED PERMISSIONS
content:
To successfully modify a group's membership using <i>groupmems</i>, the user executing the command must possess administrative rights over the specified group. This is typically achieved by:<br><i>1. Being the primary owner of the group</i> (i.e., your user's primary GID matches the target group's GID).<br><i>2. Being listed as an administrator</i> for that group in the <i>/etc/gshadow</i> file. <br>Attempting to modify a group without these permissions will result in a permission denied error.


title: IMPACT ON SYSTEM FILES
content:
Any changes made by <i>groupmems</i> (adding or removing users) are persistently written to the system's core group configuration files, primarily <i>/etc/group</i> and <i>/etc/gshadow</i>. These files store the definitive list of group memberships and associated administrative metadata. Care should be taken when using <i>groupmems</i> to avoid unintended modifications to these critical system files.


title: HISTORY
content:
<i>groupmems</i> is a component of the <i>shadow-utils</i> package, which provides a suite of tools for managing user and group accounts on Linux systems. Its development reflects the evolution of Unix-like security models, moving towards more granular permission delegation where specific administrative tasks can be performed by non-root users. It addresses the need for decentralized group management without requiring full superuser privileges.


title: PARAMETERS
content:
<b>-g GID, --gid GID</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Changes the group ID (GID) to the specified value.<br><br><b>-n NEW_GROUP, --new-name NEW_GROUP</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Changes the group's name to the new specified name.<br><br><b>-o, --non-unique</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Allows the new group ID to be non-unique, enabling duplicate GIDs.<br><br><b>-R CHROOT_DIR, --root CHROOT_DIR</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Applies changes in the specified chroot directory instead of the system root.<br><br><b>-P PREFIX_DIR, --prefix PREFIX_DIR</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Applies changes in the specified prefix directory (used by shadow utilities).<br><br><b>-h, --help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a help message and exits the command.<br><br>


title: DESCRIPTION
content:
The <b>groupmod</b> command is used to modify an existing group's definition on a Linux system. It allows administrators to change a group's name or its Group ID (GID). When changing the group name, all entries referencing the old name in system files like <i>/etc/group</i> and <i>/etc/gshadow</i> are updated. Similarly, changing the GID updates these files. This command is crucial for maintaining proper group management, especially in environments where group identifiers or names need to be adjusted without recreating the group and reassigning its members. It automatically handles updates to the necessary system configuration files. Note that changing a GID does <b>not</b> automatically update the ownership of files belonging to that group; this requires a separate command like <i>chgrp</i>.


title: CAVEATS
content:
When changing a group's GID, <b>groupmod</b> does <b>not</b> automatically update the GID of files owned by that group. This must be done manually using commands like <i>chgrp</i> and <i>find</i>. Processes running under the old GID will continue to do so until they are restarted. Using the <i>--non-unique</i> option can lead to issues with file permissions and security as multiple groups might share the same GID.


title: FILE OWNERSHIP UPDATE
content:
When a group's GID is changed, the ownership of files and directories that belong to that group is <b>not</b> automatically updated. An administrator must manually update these using commands such as <i>find / -gid OLD_GID -exec chgrp -h NEW_GID {} \;</i> to ensure consistency across the filesystem. Note the escaped semicolon in the example command.


title: PROCESS GID
content:
Running processes that are associated with the group's old GID will continue to run with that old GID until they are restarted. This is an important consideration for system services or long-running applications affected by a GID change.


title: HISTORY
content:
<b>groupmod</b> is a part of the `shadow-utils` package, which provides essential utilities for managing user and group accounts on Linux and Unix-like systems. These tools have been a fundamental component of system administration for decades, evolving to support modern security practices like shadowed passwords and GIDs, ensuring robust and secure account management.


title: PARAMETERS
content:
<b>--help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a help message and exits, providing information on command usage.<br><br><b>--version</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Outputs version information about the <b>groups</b> command and exits.<br><br><b><i>USERNAME</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the username for which to display group memberships. If omitted, the command defaults to displaying the group memberships for the current effective user.<br><br>


title: DESCRIPTION
content:
The <b>groups</b> command is a utility used to print the names of the primary and any supplementary groups that a specified user belongs to. When no username is provided, it defaults to displaying the group memberships for the current effective user. It's commonly employed to quickly verify a user's group affiliations, which is crucial for managing file permissions, access control, and troubleshooting. The information returned by <b>groups</b> is sourced from the system's configured user and group databases, such as <i>/etc/passwd</i>, <i>/etc/group</i>, or external Name Service Switch (NSS) sources like LDAP or NIS. The output is a simple, space-separated list of group names. For instance, running <i>groups alice</i> might yield <i>alice users sudo docker</i>, where <i>alice</i> is her primary group (if configured as such) and <i>users</i>, <i>sudo</i>, and <i>docker</i> are supplementary groups. The primary group is typically the one listed in the user's entry in <i>/etc/passwd</i> and is usually the first one shown by the command. Understanding group memberships is fundamental for ensuring correct access to system resources and performing privileged operations securely.


title: CAVEATS
content:
The <b>groups</b> command only displays group names, not their numerical IDs (GIDs). For GIDs, use the <b>id</b> command. The information provided relies on the system's configured Name Service Switch (NSS) modules, meaning it can query local files, NIS, LDAP, or other sources configured in <i>/etc/nsswitch.conf</i>. The output format is a simple space-separated list, which might require additional parsing with tools like <b>awk</b> or <b>cut</b> for more complex scripting needs.


title: OUTPUT FORMAT
content:
The <b>groups</b> command prints a space-separated list of group names to standard output. The primary group for the specified user is generally listed first, followed by any supplementary groups. For example, for a user <i>testuser</i>, the output might be <i>testuser users docker</i>.


title: PERMISSIONS
content:
Any user can execute the <b>groups</b> command to inquire about the group memberships of any other user on the system. This information is generally considered publicly accessible for system administration and understanding user contexts, as it does not expose sensitive data like passwords or GIDs.


title: NAME SERVICE SWITCH (NSS) INTEGRATION
content:
<b>groups</b> leverages the Name Service Switch (NSS) system to resolve user and group information. This allows it to retrieve data not only from local files (<i>/etc/passwd</i>, <i>/etc/group</i>) but also from centralized directories or network services like NIS or LDAP, depending on the system's configuration in <i>/etc/nsswitch.conf</i>.


title: HISTORY
content:
The <b>groups</b> command is a fundamental utility that has been a part of Unix-like operating systems for many decades, typically bundled within the <i>coreutils</i> package on GNU/Linux systems. Its core functionality—to list a user's group memberships—has remained consistently simple and direct throughout its history. Its development has focused on robustness and adherence to system-wide user and group management standards, particularly its seamless integration with the Name Service Switch (NSS) to accommodate various identity management backends beyond local files.


title: SEE ALSO
content:
id(1), whoami(1), logname(1), users(1), getent(1), passwd(5), group(5), usermod(8), groupadd(8), useradd(8)


title: SYNOPSIS
content:
<b>growisofs</b> [<i>OPTIONS</i>] <i>&lt;device&gt;</i> [<i>mkisofs/genisoimage_options</i> ...]<br><br>Primary modes:<br><b>growisofs</b> <b>-Z</b> <i>&lt;device&gt;</i> [<i>mkisofs/genisoimage_options</i> ...]<br><b>growisofs</b> <b>-M</b> <i>&lt;device&gt;</i> [<i>mkisofs/genisoimage_options</i> ...]<br><b>growisofs</b> <b>-F</b> <i>&lt;device&gt;</i><br><b>growisofs</b> <b>-R</b> <i>&lt;device&gt;</i> [<i>mkisofs/genisoimage_options</i> ...]


title: PARAMETERS
content:
<b><b>-Z</b> <i>&lt;device&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Starts a <i>new ISO9660 session</i> and writes to the specified optical device.<br><br><b><b>-M</b> <i>&lt;device&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Appends data</i> to an existing ISO9660 session on the specified optical device.<br><br><b><b>-F</b> <i>&lt;device&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Formats</i> a rewritable disc (e.g., DVD-RW, BD-RE) in the specified device.<br><br><b><b>-R</b> <i>&lt;device&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Re-opens</i> a session on a device for appending, typically after an ungraceful shutdown.<br><br><b><b>-speed=</b><i>&lt;speed&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the <i>burning speed</i> for the operation (e.g., <i>4x</i>, <i>max</i>).<br><br><b><b>-dry-run</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Simulates the burning process without actually writing data to the disc.<br><br><b><b>-dvd-compat</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Pads the track to a multiple of 16 sectors for <i>DVD-RAM compatibility</i>.<br><br><b><b>-use-the-force-luke</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Forces operations, bypassing some safety checks and warnings.<br><br><b><b>-version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays the program <i>version</i> information and exits.<br><br>


title: DESCRIPTION
content:
growisofs is a powerful utility for Linux and Unix-like systems, primarily used for recording ISO9660 filesystems directly to recordable optical media like DVD&plusmn;R/RW, BD-R/RE, and CD-R/RW. It acts as a front-end to <i>mkisofs</i> (or <i>genisoimage</i>) for creating the filesystem image on-the-fly and simultaneously writes it to the disc, often employing <i>dvd&plus;rw-tools</i>' underlying burning capabilities. Its key strength lies in its ability to perform incremental writes, allowing users to add data to an existing session on a disc, making it ideal for multi-session backups or building up a disc's content over time. It can handle various source file systems and supports different disc types and burning modes, integrating image generation and burning into a single command for streamlined optical disc content management.


title: CAVEATS
content:
growisofs relies on <i>mkisofs</i> (or <i>genisoimage</i>) to be installed and available in the system's PATH. Incorrect permissions for accessing the optical drive device (e.g., <i>/dev/sr0</i>) are a common issue. Using <b>-M</b> carefully is advised, as it appends to the last session, which might not be the intended free space if the disc's history is complex. Understanding specific disc types (DVD-R vs. DVD&plus;R, R vs. RW) is crucial for optimal results.


title: COMMON USAGE PATTERNS
content:
<b>Creating a new data disc:</b><br><i>growisofs -Z /dev/sr0 -R -J /path/to/data/</i><br><br><b>Appending data to an existing disc:</b><br><i>growisofs -M /dev/sr0 -R -J /path/to/more/data/</i><br><br><b>Formatting a rewritable disc:</b><br><i>growisofs -F /dev/sr0</i>


title: DISC FORMATS
content:
growisofs supports a wide range of optical disc formats including <b>DVD-R/RW</b>, <b>DVD&plus;R/RW</b>, <b>DVD-RAM</b>, <b>BD-R/RE</b>, and <b>CD-R/RW</b>. While the command often handles specific format nuances internally, users benefit from understanding the characteristics of each disc type for optimal usage, especially regarding single-session (R) versus rewritable (RW) media.


title: HISTORY
content:
growisofs is a key component of the <i>dvd&plus;rw-tools</i> suite, primarily developed by Andy Polyakov. It emerged as a sophisticated tool for writing to DVD&plus;RW media, leveraging its unique ability to 'grow' the filesystem incrementally. Its innovation lay in integrating on-the-fly ISO image generation with direct disc burning, significantly streamlining the process compared to traditional methods that involved piping <i>mkisofs</i> output to separate burning utilities. Over time, its support expanded to encompass a wide array of DVD and BD formats, solidifying its position as a go-to command for multi-session and incremental optical media burning.


title: PARAMETERS
content:
<b>DEVICE</b><br>&nbsp;&nbsp;&nbsp;&nbsp;The block device containing the partition (e.g., <b>/dev/sda</b>).<br><br><b>PARTITION_NUMBER</b><br>&nbsp;&nbsp;&nbsp;&nbsp;The numerical identifier of the partition to be expanded (e.g., <b>1</b> for <b>/dev/sda1</b>).<br><br><b>-h, --help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display a help message and exit.<br><br><b>-v, --version</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show program's version number and exit.<br><br><b>-N, --dry-run</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Perform a dry run; print what would be done without making actual changes.<br><br><b>-u, --update auto|off</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Control kernel partition table update. 'auto' (default) attempts to update, 'off' does not.<br><br><b>-b, --bytes N</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Limit the expansion to N bytes after the partition's original size.<br><br>


title: DESCRIPTION
content:
<br><i>growpart</i> is a command-line utility used to expand a specified disk partition to occupy all available contiguous free space on the underlying storage device. It is commonly employed in virtualized environments where the disk size of a virtual machine is increased, and the corresponding partition needs to be extended to utilize the newly available capacity. Unlike tools such as <i>fdisk</i> or <i>parted</i>, which require more manual intervention and understanding of disk geometry, <i>growpart</i> simplifies the process by automatically identifying and extending the partition to the largest possible size. It works by modifying the partition table entry for the given partition, typically extending it to the end of the disk. It is crucial to remember that <i>growpart</i> only resizes the partition itself; the filesystem residing within that partition must be resized separately using appropriate tools like <i>resize2fs</i> for ext2/3/4 or <i>xfs_growfs</i> for XFS after the partition has been successfully extended.


title: CAVEATS
content:
<br>Requires root privileges to execute.<br>Only resizes the partition entry in the disk's partition table; the filesystem on the partition must be resized separately.<br>Cannot shrink partitions or move them.<br>Risk of data loss if operations are interrupted or used incorrectly.


title: IMPORTANT USAGE NOTE
content:
<br>After successfully using <b>growpart</b> to extend a partition, it is critical to also resize the filesystem located on that partition to utilize the newly available space. For <b>ext2/3/4</b> filesystems, use <b>resize2fs</b> (e.g., <b>resize2fs /dev/sda1</b>). For <b>XFS</b> filesystems, use <b>xfs_growfs</b> (e.g., <b>xfs_growfs /mnt/mydata</b>). Failing to resize the filesystem will result in the partition being larger, but the filesystem still using only its original capacity.


title: HISTORY
content:
<br><i>growpart</i> is often found as part of the <i>cloud-utils</i> or <i>cloud-init</i> packages, which are crucial for automating the initial setup and configuration of cloud instances. Its development was motivated by the common need in virtualized environments to programmatically expand disk partitions after a virtual machine's underlying disk has been increased. It provides a simpler, scriptable alternative to more interactive and complex partitioning tools, streamlining the deployment and scaling of cloud resources.


title: SYNOPSIS
content:
<b>grpck</b> [<i>options</i>]<br><b>grpck</b> [<b>-r</b>] [<b>-s</b>] [<b>-q</b>] [<b>-R</b> <i>CHROOT_DIR</i>] {<i>group_file</i> | <b>-</b>}


title: PARAMETERS
content:
<b><b>-r</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Repair mode. <i>grpck</i> attempts to fix or remove erroneous entries. It prompts the user for confirmation before making changes.<br><br><b><b>-s</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sorted mode. Causes <i>grpck</i> to print the list of users in each group in sorted order.<br><br><b><b>-q</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Quiet mode. Suppresses all output unless an error is detected. Useful for scripting.<br><br><b><b>-R</b> <i>CHROOT_DIR</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Apply changes to a <i>chroot</i> environment located at <i>CHROOT_DIR</i> instead of the default root directory. This is useful for checking filesystems of unbootable systems.<br><br><b><i>group_file</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies an alternative group file to check instead of <i>/etc/group</i>. If <b>-</b> is used, <i>grpck</i> reads from standard input.<br><br><b><b>-</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Reads group data from standard input instead of <i>/etc/group</i>. Often used for piping data from other commands.<br><br>


title: DESCRIPTION
content:
<i>grpck</i> is a crucial utility for maintaining the integrity of the system's group databases: <i>/etc/group</i> and <i>/etc/gshadow</i>.<br><br>It performs a series of checks to ensure the structural and semantic correctness of these files. This includes verifying that each entry has the correct number of fields, that group names and GIDs (Group IDs) are valid and unique, and that all group members listed actually exist in the <i>/etc/passwd</i> file.<br><br>The command helps identify common issues like corrupted entries, duplicate GIDs, or invalid usernames within group memberships. By default, <i>grpck</i> reports any inconsistencies found to standard output. However, with the <b>-r</b> option, it can attempt to automatically fix or remove erroneous entries, making it a powerful tool for system administrators to prevent security vulnerabilities and ensure proper user and group management.


title: CAVEATS
content:
Using the <b>-r</b> (repair) option can make irreversible changes to your group files. It is strongly recommended to <b>back up</b> <i>/etc/group</i> and <i>/etc/gshadow</i> before attempting any repairs.<br><br><i>grpck</i> requires <b>root privileges</b> to access and modify the system group files. It primarily checks for structural and basic consistency issues; it does not validate group policies or complex permission schemes.


title: FILES
content:
<i>grpck</i> typically accesses the following system files:<br><ul><li><i>/etc/group</i> - The standard group file.</li><li><i>/etc/gshadow</i> - The secure group account information file.</li><li><i>/etc/passwd</i> - Referenced to validate user existence for group members.</li></ul>


title: EXIT STATUS
content:
<i>grpck</i> exits with a status of <b>0</b> on success, <b>1</b> if errors are found but not fixed, or <b>2</b> if errors are found and fixed (when <b>-r</b> is used). Other non-zero values indicate critical system errors.


title: HISTORY
content:
<i>grpck</i> is part of the <b>shadow-utils</b> package, which provides a comprehensive set of programs for managing user and group accounts, including shadow passwords and group files. Its development closely mirrors that of <i>pwck</i>, its counterpart for password file integrity checking.<br><br>The tool became essential with the widespread adoption of shadow password and group files (<i>/etc/shadow</i> and <i>/etc/gshadow</i>) to enhance system security by separating sensitive hashed passwords and group-related information from the publicly readable <i>/etc/passwd</i> and <i>/etc/group</i> files. <i>grpck</i> helps ensure the integrity of these critical system files, preventing issues that could lead to security vulnerabilities or account management problems.


title: SEE ALSO
content:
<b>group(5)</b>, <b>gshadow(5)</b>, <b>passwd(5)</b>, <b>pwck(8)</b>, <b>useradd(8)</b>, <b>groupadd(8)</b>, <b>usermod(8)</b>, <b>groupmod(8)</b>


title: PARAMETERS
content:
<b><b>-r</b>, <b>--root</b> <i>CHROOT_DIR</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Apply changes relative to the directory <i>CHROOT_DIR</i> rather than the system's root directory. Useful for managing systems in a chroot environment.<br><br><b><b>-f</b>, <b>--force</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Force the conversion or update operation, even if <b>grpconv</b> determines that it is not necessary or that the files are already in the correct format.<br><br>


title: DESCRIPTION
content:
<b>grpconv</b> is a command-line utility used to synchronize and convert group information between the traditional <i>/etc/group</i> file and its shadow counterpart, <i>/etc/gshadow</i>. It plays a crucial role in enhancing system security by separating encrypted group passwords (if any) from the publicly readable <i>/etc/group</i> file and storing them in the less accessible <i>/etc/gshadow</i> file.<br><br>When executed, <b>grpconv</b> reads entries from <i>/etc/group</i>. If <i>/etc/gshadow</i> does not exist, it creates it. For each group listed in <i>/etc/group</i>, <b>grpconv</b> checks if a corresponding entry exists in <i>/etc/gshadow</i>. If not, it creates a new entry in <i>/etc/gshadow</i> for that group. If an entry already exists, <b>grpconv</b> updates it, moving any encrypted password hash from <i>/etc/group</i> to <i>/etc/gshadow</i> and replacing it with an 'x' in <i>/etc/group</i>. This ensures that sensitive password data is kept in a file with stricter permissions, typically readable only by root.<br><br>The command is usually run as part of initial system setup or system migration efforts where shadow passwords are being introduced or maintained. It's a key component of the shadow password suite of utilities.


title: CAVEATS
content:
Running <b>grpconv</b> requires root privileges.<br><br>It is strongly recommended to back up <i>/etc/group</i> and <i>/etc/gshadow</i> before running this command, as it modifies critical system authentication files.<br><br>For consistency and to prevent data corruption, it's best to run <b>grpconv</b> when the system is quiet or in single-user mode, or when no other processes are actively modifying group information.


title: FILE LOCATIONS
content:
<b>grpconv</b> primarily operates on two critical system files:<br><i>/etc/group</i>: The traditional file containing group definitions, including group name, GID, and a list of members.<br><i>/etc/gshadow</i>: The shadow group file, designed to store secure information for groups, primarily encrypted group passwords and administrators.


title: SECURITY IMPLICATIONS
content:
By moving sensitive group password hashes from <i>/etc/group</i> to the permissions-restricted <i>/etc/gshadow</i>, <b>grpconv</b> significantly enhances system security. It prevents unauthorized users from easily obtaining and attempting to crack group passwords, reinforcing the principle of least privilege.


title: HISTORY
content:
The concept of shadow passwords, which <b>grpconv</b> facilitates, emerged in Unix-like systems as a security enhancement. Historically, user and group password hashes were stored directly in <i>/etc/passwd</i> and <i>/etc/group</i> respectively, files that typically had world-readable permissions. This posed a significant security risk, as anyone could potentially copy these hashes and attempt to crack them offline.<br><br>To mitigate this, the <i>shadow</i> password suite was developed, introducing separate files like <i>/etc/shadow</i> and <i>/etc/gshadow</i> to store encrypted passwords. These shadow files have much stricter permissions, typically readable only by the root user. <b>grpconv</b> was created as part of this suite to manage the transition and ongoing synchronization of group password information from the traditional <i>/etc/group</i> to the more secure <i>/etc/gshadow</i> file, replacing the password field in <i>/etc/group</i> with an 'x' to indicate that the password is in the shadow file. This development greatly improved the overall security posture of Unix and Linux systems.


title: SEE ALSO
content:
grpunconv(8), group(5), gshadow(5), pwconv(8), pwunconv(8), groupadd(8), groupmod(8), groupdel(8), useradd(8)


title: SYNOPSIS
content:
<b>grub-install</b> [<i>OPTION</i>...] <i>INSTALL_DEVICE</i><br><i>or for UEFI:</i><br><b>grub-install</b> [<i>OPTION</i>...] <b>--target</b>=<i>TARGET</i> <b>--efi-directory</b>=<i>EFI_DIR</i> [<b>--bootloader-id</b>=<i>ID</i>]


title: PARAMETERS
content:
<b>INSTALL_DEVICE</b><br>&nbsp;&nbsp;&nbsp;&nbsp;The target device (e.g., <i>/dev/sda</i>) onto which GRUB will be installed for BIOS systems.<br><br><b>--boot-directory=DIR</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Use DIR as the boot directory where GRUB files will be placed.<br><br><b>--efi-directory=DIR</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the root directory of the EFI System Partition (ESP) for UEFI installations.<br><br><b>--target=TARGET</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Install GRUB for the specified platform (e.g., <i>i386-pc</i> for BIOS, <i>x86_64-efi</i> for UEFI).<br><br><b>--modules=MODULES</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify a comma-separated list of additional GRUB modules to install.<br><br><b>--recheck</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Probe a device again to refresh its information before installation.<br><br><b>--debug</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Print verbose debugging information during the installation process.<br><br><b>--version</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Print GRUB version information and exit.<br><br><b>--help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display a help message and exit.<br><br>


title: DESCRIPTION
content:
The <i>GRUB</i> (Grand Unified Bootloader) is the standard bootloader for most Linux distributions. It is responsible for loading the operating system kernel into memory from storage devices and passing control to it.<br><br><i>GRUB</i> is highly configurable, supporting multiple operating systems (dual-booting), various file systems, and different architectures (BIOS, UEFI). While there isn't a single executable named "grub" that serves as a general-purpose command-line utility with diverse options, the term "grub command" often refers to the <i>suite</i> of utilities used to manage and configure the GRUB bootloader, or the interactive GRUB shell.<br><br>Key utilities include <i>grub-install</i> (for installing GRUB to a device), <i>grub-mkconfig</i> (for generating the main configuration file, <i>grub.cfg</i>), and <i>grub-probe</i> (for device mapping). The interactive GRUB shell (often encountered during boot issues) provides its own set of internal commands for manual booting or troubleshooting. This analysis primarily focuses on the common external utilities, particularly <i>grub-install</i>, which is central to GRUB deployment.


title: CAVEATS
content:
The <b>grub-install</b> command is extremely powerful and can render a system unbootable if used incorrectly. Care must be taken to specify the correct <i>INSTALL_DEVICE</i> or EFI parameters. Modern systems often require careful handling of <i>UEFI</i> variables and boot order, which <b>grub-install</b> manages, but misconfiguration can lead to boot failures. Using <b>update-grub</b> (a Debian/Ubuntu specific wrapper for <b>grub-mkconfig</b>) is generally safer for updating configuration after kernel changes.


title: GRUB CONFIGURATION FILE (GRUB.CFG)
content:
The primary configuration file for GRUB 2 is <i>/boot/grub/grub.cfg</i>. This file is typically <i>not</i> meant to be edited manually by users. Instead, it is generated by the <b>grub-mkconfig</b> utility (or <b>update-grub</b> on Debian/Ubuntu-based systems) based on templates in <i>/etc/grub.d/</i> and settings in <i>/etc/default/grub</i>. Manual edits can be overwritten and may prevent the system from booting.


title: INTERACTIVE GRUB SHELL
content:
When a system fails to boot properly, or during installation, users might encounter the interactive GRUB shell (e.g., <i>grub></i> or <i>grub rescue></i>). This command-line environment allows for manual booting, inspecting devices, loading modules, and troubleshooting boot issues using internal commands like <b>ls</b>, <b>set</b>, <b>insmod</b>, <b>linux</b>, <b>initrd</b>, and <b>boot</b>. It's a critical tool for recovery.


title: HISTORY
content:
<i>GRUB</i>'s development began in 1999 as part of the GNU Project. The original <i>GRUB</i> (now referred to as <i>GRUB Legacy</i>) served as the primary bootloader for many Linux distributions. In 2002, <i>GRUB 2</i> (or <i>GRUB</i>, as it's commonly known today) began development to rewrite and improve upon the legacy version, introducing modularity, better internationalization, and support for a wider range of file systems and firmware interfaces (like <i>UEFI</i>). <i>GRUB 2</i> became the default bootloader for major distributions around 2010-2012 (e.g., Ubuntu 9.10, Fedora 15, Debian 6.0), largely replacing <i>GRUB Legacy</i>. Its continuous development focuses on supporting new hardware, security features, and ease of configuration, solidifying its role as the de facto standard bootloader for Linux and other <i>UNIX</i>-like systems.


title: PARAMETERS
content:
<b>DEVICE</b><br>&nbsp;&nbsp;&nbsp;&nbsp;The target device (e.g., <i>/dev/sda</i>) where GRUB's boot code will be installed. This should typically be the entire disk, not a partition.<br><br><b><b>--force</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Force installation even if it's considered unsafe or potentially problematic (e.g., if it would overwrite a valid partition table). Use with extreme caution.<br><br><b><b>--recheck</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Probe a device and recheck the device map for GRUB. This is useful if the disk layout has changed since the last GRUB configuration.<br><br><b><b>--no-floppy</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Do not probe or use floppy drives during the installation process, which can speed up the operation on systems without floppies.<br><br><b><b>--boot-directory=</b><i>DIR</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify an alternate directory (<i>DIR</i>) for the GRUB core image and modules. By default, this is usually <i>/boot/grub</i>.<br><br><b><b>--modules=</b><i>MODULES</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Install specific GRUB modules (comma-separated list). This can be used to include or exclude particular features from the core image.<br><br><b><b>--grub-setup=</b><i>FILE</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Use <i>FILE</i> as the <i>grub-setup</i> program. This is an advanced option for customizing the setup process.<br><br><b><b>--force-extra-removable</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Force installation even if the device is not removable. This is useful for installing GRUB on USB drives where the BIOS might try to use biosdrive instead of device.<br><br>


title: DESCRIPTION
content:
The <i>grub-bios-setup</i> command is a specialized helper script used to install the GRand Unified Bootloader (GRUB) to the Master Boot Record (MBR) or a partition's boot sector on systems utilizing the traditional BIOS firmware. It acts as a convenient wrapper around the more general <i>grub-install</i> command, specifically pre-configuring it for <i>i386-pc</i> (BIOS) targets.<br><br>This command is crucial for making a Linux system bootable on BIOS machines, as it writes the necessary initial boot stages of GRUB into the bootable area of a specified disk, allowing the system to load the GRUB menu and subsequently the operating system kernel. It simplifies the installation process by abstracting away the intricacies of <i>grub-install</i>'s target architecture options, making it a go-to tool for legacy BIOS setups.


title: CAVEATS
content:
<b>Root Privileges Required</b>: This command modifies the Master Boot Record (MBR) or boot sector of a disk and therefore requires root (superuser) privileges to execute successfully.<br><br><b>Data Loss Risk</b>: Incorrect usage, such as specifying the wrong device (e.g., a data partition instead of the primary disk), can lead to data loss or render your system unbootable. Always double-check the target <i>DEVICE</i>.<br><br><b>BIOS-Only</b>: <i>grub-bios-setup</i> is specifically designed for traditional BIOS firmware. It is not suitable for UEFI (Unified Extensible Firmware Interface) systems, which require a different installation approach (e.g., <i>grub-install --target=x86_64-efi</i>).<br><br><b>Device Path</b>: Ensure the specified <i>DEVICE</i> (e.g., <i>/dev/sda</i>) refers to the entire disk and not a specific partition (e.g., <i>/dev/sda1</i>), unless you explicitly intend to install GRUB to a partition's boot sector (which is less common for the MBR).


title: WRAPPER FOR `GRUB-INSTALL --TARGET=I386-PC`
content:
The `grub-bios-setup` command is essentially a convenience wrapper script that executes `grub-install` with the `--target=i386-pc` option implicitly set. This `i386-pc` target is specifically for traditional BIOS-based systems, ensuring that the installed bootloader is compatible with the firmware. Understanding this underlying mechanism helps in troubleshooting and advanced customization, as most of the actual work is performed by `grub-install`.


title: MBR VS. PARTITION BOOT SECTOR INSTALLATION
content:
When using `grub-bios-setup`, you typically specify the entire disk (e.g., `/dev/sda`) to install GRUB to the Master Boot Record (MBR). This is the most common scenario for making a disk bootable. It is also possible to install GRUB to the boot sector of a specific partition (e.g., `/dev/sda1`), but this usually requires another bootloader in the MBR to chainload into that partition. For primary OS booting, installing to the MBR is the standard approach.


title: HISTORY
content:
The GRand Unified Bootloader (GRUB) emerged as a successor to the original GRUB Legacy, with GRUB 2 (also known simply as GRUB) becoming the standard since its release. GRUB 2 introduced significant improvements, including a more modular design, support for multiple firmware types (BIOS and UEFI), and a more robust configuration system. The <i>grub-bios-setup</i> command was introduced as part of the GRUB 2 ecosystem to simplify the installation process for the prevalent BIOS-based systems. It serves as an abstraction layer, allowing users to install GRUB to the MBR without needing to specify the exact target architecture (<i>i386-pc</i>), making it more user-friendly and reducing the chances of errors related to target selection, especially as UEFI systems became more common.


title: PARAMETERS
content:
<b>-v, --verbose</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Print verbose messages, showing more details about the operation being performed.<br><br><b>-h, --help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display a help message and exit. This provides a summary of the command's usage and available options.<br><br><b>-V, --version</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display version information about <i><b>grub-editenv</b></i> and exit.<br><br>


title: DESCRIPTION
content:
<i><b>grub-editenv</b></i> is a utility program designed to create, list, set, or unset variables within GRUB's persistent environment block file. This file, typically located at <i>/boot/grub/grubenv</i>, stores environment variables that GRUB can access during the boot process. It's crucial for functionalities like <i><b>grub-set-default</b></i> and <i><b>grub-reboot</b></i>, which use this block to store information about the default boot entry or a one-time boot selection. Unlike the main <i><b>grub.cfg</b></i> configuration file, which is often regenerated, the environment block provides a persistent, writable storage for dynamic settings. Administrators can use <i><b>grub-editenv</b></i> to manually inspect or modify these variables, though direct manipulation should be done with care to avoid boot issues. It provides a simple interface to manage the key-value pairs that influence GRUB's behavior across reboots.


title: CAVEATS
content:
<i><b>grub-editenv</b></i> comes with several caveats:<br><i>1. Direct manual editing of the GRUB environment block can lead to boot issues if not done carefully.</i><br><i>2. Ensure the correct environment block file path is specified. Typically, this is <i>/boot/grub/grubenv</i>.</i><br><i>3. Changes made manually might conflict with other GRUB tools that automatically manage this file (e.g., <i><b>grub-set-default</b></i>, <i><b>grub-reboot</b></i>).</i><br><i>4. The environment block has a limited size, usually 1024 bytes. Exceeding this limit will cause issues.</i>


title: COMMAND OPERATIONS
content:
<i><b>grub-editenv</b></i> supports several command operations to manage the GRUB environment block:<br><br><i><b>create</b></i>: Creates an empty GRUB environment block file. If the file already exists, it is truncated (emptied) and reinitialized.<br><i><b>list</b></i>: Displays all variables and their current values currently stored in the environment block file.<br><i><b>set VAR=VALUE [...]</b></i>: Sets one or more variables to specified values. If a variable already exists, its value is updated. New variables are added.<br><i><b>unset VAR [...]</b></i>: Removes one or more specified variables from the environment block.<br><i><b>delete VAR [...]</b></i>: An alias for <i><b>unset</b></i>, providing the same functionality to remove variables.<br><br>The <i>FILE</i> argument must always be specified before the command operation, pointing to the GRUB environment block (e.g., <i>/boot/grub/grubenv</i>).


title: GRUB ENVIRONMENT BLOCK FILE
content:
The GRUB environment block file (commonly <i>/boot/grub/grubenv</i>) is a small, dedicated file used by GRUB to store persistent environment variables. These variables are accessible to GRUB during the boot process and can influence its behavior. Unlike the main <i><b>grub.cfg</b></i> configuration file, which is often static or generated by a script, the environment block provides a writable area for dynamic settings that can persist across reboots, such as the <i>saved_entry</i> variable used by <i><b>grub-set-default</b></i>.


title: HISTORY
content:
<i><b>grub-editenv</b></i> is an integral part of GRUB 2, which superseded GRUB Legacy. Its introduction reflects a design philosophy in GRUB 2 to provide more dynamic and persistent control over boot behavior, allowing for changes to GRUB's environment variables without requiring a regeneration of the entire <i><b>grub.cfg</b></i> file. This command emerged as GRUB 2 matured, offering a robust method for other GRUB utilities and system administrators to manage boot-time preferences, like the default boot entry or one-time boot selections, in a persistent manner across reboots.


title: PARAMETERS
content:
<b><b>-r</b>, <b>--root</b>=<i>DEVICE</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set the root device for GRUB (e.g., <i>(hd0,msdos1)</i>). This specifies the device where GRUB should look for its root filesystem.<br><br><b><b>-p</b>, <b>--prefix</b>=<i>PATH</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the GRUB prefix path (e.g., <i>/boot/grub</i>). This indicates where GRUB modules and configuration files are located relative to the root device.<br><br><b><b>-d</b>, <b>--debug</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enable verbose debug messages during operation. Useful for troubleshooting filesystem driver issues.<br><br><b><b>-s</b>, <b>--skip-fs-probe</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Do not attempt to probe filesystems from the specified <i>DISK_IMAGE</i>. Useful if the filesystem is known or provided via <b>--root</b>, or to speed up startup.<br><br><b><b>-N</b>, <b>--no-grub-modules</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prevent loading GRUB modules. This can be used for basic testing or when module loading is not desired or causes issues.<br><br><b><b>-v</b>, <b>--verbose</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Print more detailed information about the command's execution, including progress and actions taken.<br><br><b><b>-V</b>, <b>--version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display version information about <b>grub-fstest</b> and exit.<br><br><b><b>-h</b>, <b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show a help message with usage instructions and available options, then exit.<br><br>


title: DESCRIPTION
content:
<b>grub-fstest</b> is a utility from the GRUB (GRand Unified Bootloader) project designed to test and debug GRUB's internal filesystem drivers. It allows users to "mount" a disk image file or a physical device and interact with the filesystems on it using GRUB's own filesystem handling code, rather than the host system's kernel. This makes it invaluable for verifying GRUB's ability to read from various filesystems (like ext2/3/4, FAT, NTFS, HFS+, Btrfs, XFS, etc.), troubleshooting GRUB boot issues, or even inspecting the contents of GRUB installations or problematic disk partitions from a GRUB perspective. It supports a range of subcommands similar to standard Linux utilities (e.g., <b>ls</b>, <b>cat</b>, <b>cp</b>, <b>stat</b>, <b>md5sum</b>), enabling comprehensive testing and inspection without requiring a full GRUB boot environment. It operates by simulating GRUB's environment to test its filesystem access capabilities directly.


title: CAVEATS
content:
<b>grub-fstest</b> operates with GRUB's own filesystem drivers, which might behave differently or support a distinct set of features compared to the host operating system's kernel. Therefore, results may not always perfectly mirror the host system's filesystem view. It is primarily a debugging and testing tool for GRUB's capabilities. While generally read-only for inspection, care should be taken when using it on live physical devices to avoid any unintended interference with system operation.


title: SUBCOMMANDS
content:
<b>grub-fstest</b> supports a variety of subcommands that mimic standard Linux utilities, allowing for file system interaction within the GRUB environment. These commands operate on the specified <i>DISK_IMAGE</i> using GRUB's internal filesystem drivers.<br><br>Examples include:<br><b>ls</b> <i>PATH</i>: List directory contents.<br><b>cat</b> <i>PATH</i>: Print file contents to standard output.<br><b>cp</b> <i>SRC DST</i>: Copy a file from source to destination within the GRUB context.<br><b>md5sum</b> <i>PATH</i>: Compute and check MD5 checksums of files.<br><b>stat</b> <i>PATH</i>: Display file or file system status, including size, type, and timestamps.<br><b>hexdump</b> <i>PATH</i>: Display file contents in hexadecimal, decimal, octal, or ASCII format.<br><b>cmp</b> <i>FILE1 FILE2</i>: Compare two files byte by byte.<br><b>diff</b> <i>FILE1 FILE2</i>: Output the differences between two files.<br>And many more, enabling comprehensive filesystem testing and inspection of GRUB-accessible data.


title: HISTORY
content:
<b>grub-fstest</b> is an integral part of the GRUB 2 development suite. Its primary purpose emerged from the need to rigorously test and ensure the robustness of GRUB's sophisticated filesystem handling capabilities independent of a full boot cycle. As GRUB 2 aimed to support a wider array of filesystems and partitioning schemes than its predecessor, a dedicated tool for isolated filesystem driver testing became essential for developers to debug and verify new implementations or regressions efficiently. Its usage grew among system administrators and power users for diagnosing boot issues related to filesystem access or for recovering data from unbootable systems by leveraging GRUB's unique filesystem perspective.


title: PARAMETERS
content:
<b>-o, --output=<I>FILE</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the path and filename for the resulting combined EFI executable. This option is typically mandatory as the command's primary function is to create a new file.<br><br><b><I>input_efi_file</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;One or more paths to the EFI executable files that need to be combined (e.g., <i>/usr/lib/grub/x86_64-efi/grubx64.efi</i>, <i>/usr/lib/grub/i386-efi/grubia32.efi</i>). At least one input file is required.<br><br>


title: DESCRIPTION
content:
The <i>grub-glue-efi</i> command is a specialized utility within the GRUB2 ecosystem designed to combine multiple EFI (Extensible Firmware Interface) executable files into a single, universal EFI image. This is particularly useful for creating a single bootloader file that can be used on systems with different EFI architectures (e.g., 64-bit UEFI firmware and 32-bit UEFI firmware, or when the system might switch between modes).<br><br>Typically, it merges a 64-bit GRUB EFI binary (like <i>grubx64.efi</i>) and a 32-bit GRUB EFI binary (like <i>grubia32.efi</i>) into a single output file (often named <i>BOOTX64.EFI</i> or <i>BOOTIA32.EFI</i>, depending on the target boot path). When the EFI firmware loads this combined file, the internal logic within the glued binary determines the correct architecture and executes the appropriate embedded EFI program. This simplifies bootloader deployment and ensures compatibility across a wider range of UEFI systems.


title: CAVEATS
content:
This command is highly specialized and generally not invoked directly by end-users. It's usually part of GRUB installation scripts or used by system administrators creating custom bootable media or unified EFI bootloaders. Improper use can lead to unbootable systems. It relies on the presence of the specific GRUB EFI binaries for different architectures. The actual behavior might vary slightly depending on the GRUB version and distribution.


title: UNIFIED EFI BOOTLOADERS
content:
The primary purpose of <i>grub-glue-efi</i> is to create a unified EFI bootloader. Modern EFI firmware often expects a specific file name (e.g., <i>BOOTX64.EFI</i> for x86_64 systems) in the EFI System Partition (ESP). By gluing 32-bit and 64-bit GRUB EFI binaries, a single <i>BOOTX64.EFI</i> file can be created that is capable of booting correctly on both 64-bit and certain 32-bit UEFI systems (if the 32-bit GRUB component is present and the firmware can execute it).


title: TYPICAL USAGE
content:
A common use case involves combining <i>grubx64.efi</i> and <i>grubia32.efi</i> located in the system's GRUB installation directories into a single <i>BOOTX64.EFI</i> file placed in the standard EFI boot path (e.g., <i>/boot/efi/EFI/BOOT/</i>). This allows a single boot entry to serve both 32-bit and 64-bit capable systems, particularly useful for USB drives or mixed environments.


title: HISTORY
content:
The <i>grub-glue-efi</i> utility emerged as part of the GRUB2 project, specifically with the increasing prevalence and complexity of UEFI (Unified Extensible Firmware Interface) booting. As systems began to feature different EFI architectures (32-bit and 64-bit) and the need arose for a single boot entry point that could handle both, tools like <i>grub-glue-efi</i> became essential. It provides a mechanism to create a 'fat' EFI binary, simplifying the distribution and deployment of GRUB across diverse UEFI hardware.


title: SYNOPSIS
content:
<b>grub-install</b> [<i>OPTION</i>...] [<i>INSTALL_DEVICE</i>]<br>or<br><b>grub-install</b> [<i>OPTION</i>...] <b>--target</b>=<i>TARGET</i> <b>--directory</b>=<i>DIR</i> [<i>INSTALL_DEVICE</i>]<br><br><i>Common usage example for BIOS:</i><br><b>grub-install</b> /dev/sda<br><br><i>Common usage example for UEFI:</i><br><b>grub-install</b> <b>--target</b>=x86_64-efi <b>--efi-directory</b>=/boot/efi


title: PARAMETERS
content:
<b><b>--target</b>=<i>TARGET</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the platform for which to install GRUB. Common targets include <i>i386-pc</i> for BIOS/CSM systems and <i>x86_64-efi</i> for UEFI systems.<br><br><b><b>--efi-directory</b>=<i>DIR</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;For UEFI systems, specify the path to the EFI System Partition (ESP) mount point, e.g., <i>/boot/efi</i>.<br><br><b><b>--boot-directory</b>=<i>DIR</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Install GRUB images under the specified directory instead of the default <i>/boot/grub</i>. Useful for custom setups or when <i>/boot</i> is not on the root partition.<br><br><b><b>--bootloader-id</b>=<i>ID</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Assign a unique identifier for the bootloader entry in UEFI NVRAM, e.g., <i>GRUB</i> or <i>Ubuntu</i>. This ID appears in the UEFI boot menu.<br><br><b><b>--removable</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;For UEFI installations, create a removable boot entry (<i>/EFI/BOOT/BOOT[ARCH].EFI</i>) that can be booted from USB drives or without relying on NVRAM entries.<br><br><b><b>--force</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Proceed with installation even if errors are detected. <i><br>Use with extreme caution, as it can lead to unbootable systems if underlying issues are not resolved.</i><br><br><b><i>INSTALL_DEVICE</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The device onto which GRUB will be installed, typically the whole disk (e.g., <i>/dev/sda</i>) for BIOS systems. For UEFI, this argument is often omitted or specifies the EFI System Partition itself.<br><br>


title: DESCRIPTION
content:
<i>grub-install</i> is a fundamental command-line utility used to install the GRUB (GRand Unified Bootloader) bootloader onto a specified disk device or partition. Its primary function is to write the GRUB core image and its modules to the target location, effectively making the system bootable. This command is indispensable for setting up new operating systems, recovering from bootloader corruption, or configuring complex multi-boot environments. It abstracts away the complexities of different boot modes, such as traditional BIOS/CSM and modern UEFI, and various disk layouts, ensuring the operating system kernel can be properly loaded upon system startup.


title: CAVEATS
content:
<i>grub-install</i> is a powerful command that can make a system unbootable if used incorrectly. Always double-check the target device to avoid overwriting the wrong bootloader.<br>For UEFI systems, ensure the EFI System Partition (ESP) is correctly mounted and specified with <b>--efi-directory</b>.<br>When repairing GRUB from a live environment, it is highly recommended to <b>chroot</b> into the target system before running <i>grub-install</i> to ensure it operates in the correct context.


title: COMMON USAGE SCENARIOS
content:
<ul><li><b>BIOS Systems</b>: To install GRUB to the Master Boot Record (MBR) of the first disk, use: <b>grub-install</b> /dev/sda</li><li><b>UEFI Systems</b>: First, mount your EFI System Partition (ESP), e.g., <b>mount</b> /dev/sdb1 /boot/efi. Then, install GRUB: <b>grub-install</b> <b>--target</b>=x86_64-efi <b>--efi-directory</b>=/boot/efi <b>--bootloader-id</b>=GRUB</li></ul>


title: USING IN A CHROOT ENVIRONMENT
content:
When repairing or installing GRUB from a live CD/USB, it's crucial to chroot into the target system. This involves mounting the root partition, then any separate <i>/boot</i> or <i>/boot/efi</i> partitions, and binding <i>/dev</i>, <i>/proc</i>, and <i>/sys</i> before executing <b>chroot</b>. This ensures <i>grub-install</i> sees the correct file system layout and device paths and installs GRUB for the correct architecture and location.


title: HISTORY
content:
GRUB (GRand Unified Bootloader) originated in 1999 as a replacement for the older <i>LILO</i> (Linux Loader). <i>grub-install</i> is an integral part of the GRUB project. GRUB 2, a complete rewrite, was released in 2007 and quickly became the default bootloader for many Linux distributions. <i>grub-install</i> evolved significantly with GRUB 2 to support modern features like UEFI, GPT partition tables, and various file systems, making it more robust and flexible than its GRUB Legacy counterpart.


title: SYNOPSIS
content:
<b>grub-kbdcomp</b> [<i>OPTIONS</i>] <i>KEYMAP</i>...<br><b>grub-kbdcomp</b> --output=<i>FILE</i> <i>KEYMAP</i>...


title: PARAMETERS
content:
<b><b>-o</b>, <b>--output</b>=<i>FILE</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the output <i>FILE</i> where the compiled keyboard layout will be written. If this option is not provided, <i>grub-kbdcomp</i> will write the output to standard output (stdout).<br><br><b><i>KEYMAP</i>...</b><br>&nbsp;&nbsp;&nbsp;&nbsp;One or more input files containing the keyboard layout definition. These text files describe the key bindings and assignments for the desired keyboard layout. The format of these files must conform to GRUB's specifications.<br><br>


title: DESCRIPTION
content:
<i>grub-kbdcomp</i> is a utility program part of the GRUB (Grand Unified Bootloader) suite. Its primary function is to compile keyboard layout definition files into a format that GRUB can understand and utilize. This compiled layout is then used by GRUB's <i>kbdcomp</i> module, enabling proper keyboard functionality, especially for non-US keyboard layouts, within the GRUB environment before the operating system has loaded. This is crucial for interacting with the GRUB prompt, entering commands, or selecting boot options using a keyboard layout different from the standard QWERTY (US). The input to <i>grub-kbdcomp</i> is a text file describing the key bindings and assignments, and the output is a binary file representing the compiled keyboard map. This compiled file can then be included in a GRUB image or installed separately to provide the necessary keyboard support during the boot process.


title: CAVEATS
content:
The keyboard layout definitions must be in a specific text format understood by GRUB, which may not be identical to keyboard layout formats used by the operating system (e.g., XKB).<br>The compiled keyboard layout is solely for the GRUB environment and does not affect the keyboard layout used by the operating system after it boots.<br>Familiarity with GRUB's architecture and keyboard layout file syntax is necessary for effective use of this command.


title: PURPOSE OF COMPILED LAYOUTS
content:
The compiled keyboard layouts produced by <i>grub-kbdcomp</i> are crucial for providing input capabilities within the GRUB command-line interface or menu navigation. This is particularly vital for users whose physical keyboards do not conform to the standard US QWERTY layout. Without such a compiled layout, entering commands or navigating menus with certain characters (e.g., national characters, symbols specific to a locale) would be impossible or highly inconvenient in the pre-OS boot environment.


title: INPUT FILE FORMAT
content:
The input <i>KEYMAP</i> files are plain text files that define the mapping between key codes and characters or actions. These files typically follow a specific syntax defined by GRUB, allowing for assignments of various keys, including modifiers (Shift, AltGr), and mapping them to Unicode characters or GRUB-specific actions. Users can create custom keymaps or adapt existing ones to suit their needs.


title: HISTORY
content:
The <i>grub-kbdcomp</i> utility is an integral part of the GRUB project, specifically within the GRUB 2 series, which succeeded GRUB Legacy. GRUB 2 was developed with a more modular and flexible design, introducing the concept of loadable modules for various functionalities, including keyboard support (<i>kbdcomp</i> module). <i>grub-kbdcomp</i> was created to compile keyboard layouts specifically for this modular GRUB 2 environment. Its development paralleled the expansion of GRUB's capabilities to support a wider range of hardware and internationalization needs, ensuring that users with non-US keyboard layouts could interact effectively with the bootloader's command line and menus.


title: SYNOPSIS
content:
grub-macbless [OPTIONS] <I>ESP_mount_point</I> <I>macOS_boot_file</I><br>Example: `grub-macbless -v /boot/efi /Volumes/Macintosh\ HD/System/Library/CoreServices/boot.efi`


title: PARAMETERS
content:
<b>ESP_mount_point</b><br>&nbsp;&nbsp;&nbsp;&nbsp;The mount point of the EFI System Partition (ESP), typically `/boot/efi` or `/efi`. This is where the EFI bootloaders reside.<br><br><b>macOS_boot_file</b><br>&nbsp;&nbsp;&nbsp;&nbsp;The full path to the `boot.efi` file (or equivalent) for the macOS installation you wish to bless. This file is usually found within `System/Library/CoreServices` on the macOS volume.<br><br><b>-v, --verbose</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enable verbose output, showing more details about the operations performed by the command.<br><br><b>-h, --help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display a help message and exit.<br><br>


title: DESCRIPTION
content:
`grub-macbless` is a utility included with GRUB that specifically addresses the boot requirements of macOS (previously OS X) on UEFI-based systems. On such systems, macOS requires its boot loader (typically `boot.efi` located within `System/Library/CoreServices`) to be "blessed" by the EFI firmware to be recognized as a valid bootable entry. This blessing process involves creating or modifying an EFI boot entry.<br><br>When GRUB is used to dual-boot Linux and macOS, it needs a way to tell the EFI firmware how to boot macOS. While GRUB can chainload directly, some EFI firmwares or macOS installations might require this explicit blessing. `grub-macbless` automates this process by interacting with the EFI System Partition (ESP) and updating the EFI boot variables, often by leveraging tools like `efibootmgr`. This ensures that macOS can be properly launched from the GRUB boot menu, providing a smoother dual-boot experience, especially in Hackintosh setups or on Apple hardware where GRUB is installed alongside macOS.


title: CAVEATS
content:
This command requires a UEFI-based system; it is not relevant for traditional BIOS systems.<br>It must be run with root privileges (e.g., using `sudo`).<br>The command relies on the availability and proper functioning of underlying EFI utilities, such as `efibootmgr`, to modify EFI boot variables.<br>Incorrectly specifying the ESP or the macOS boot file path can lead to boot failures.<br>macOS updates can sometimes reset or alter EFI boot entries, potentially requiring `grub-macbless` to be run again.<br>The exact behavior can vary between different EFI firmware implementations.


title: PURPOSE OF "BLESSING"
content:
In the context of macOS and EFI, "blessing" refers to marking a specific directory or file on a volume as the one that contains the boot loader. For EFI systems, this typically means creating an EFI boot entry that points to the `boot.efi` file on the EFI System Partition, allowing the firmware to find and execute the macOS boot loader.


title: UNDERLYING MECHANISM
content:
`grub-macbless` often achieves its goal by invoking `efibootmgr` (or similar EFI runtime tools) to create or modify `BootNext` or a permanent EFI boot entry that directs the firmware to the correct macOS `boot.efi` location on the ESP. This is crucial because macOS does not usually create its own EFI boot entry in the same way Windows or Linux might, instead relying on its own `bless` command or firmware detection.


title: HISTORY
content:
`grub-macbless` was introduced as part of the GRUB project to facilitate dual-booting Linux and macOS on Intel-based Macs or Hackintosh systems utilizing UEFI. As UEFI became the standard for modern computers, and with macOS exclusively using UEFI on Intel, a mechanism was needed within the GRUB ecosystem to properly prepare macOS for booting via EFI, complementing GRUB's chainloading capabilities. Its development reflects the increasing complexity of multi-boot environments on modern hardware.


title: PARAMETERS
content:
<b>--output=<I>FILE</I>, -o <I>FILE</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Redirects the generated GRUB 2 configuration to <i>FILE</i> instead of standard output.<br><br><b>--id=<I>ID</I>, -i <I>ID</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies a unique identifier for the converted menuentries, which can be useful in multi-boot scenarios.<br><br><b>--help, -h</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a help message and exits.<br><br><b>--version, -V</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints the version information and exits.<br><br>


title: DESCRIPTION
content:
<i>grub-menulst2cfg</i> is a utility designed to aid in the migration from GRUB Legacy (version 0.9x) to the newer GRUB 2 bootloader. Its primary function is to convert a GRUB Legacy configuration file, typically named <i>menu.lst</i>, into a GRUB 2-compatible configuration file, <i>grub.cfg</i>. <br><br>GRUB Legacy and GRUB 2 use vastly different configuration syntaxes. While <i>menu.lst</i> uses a simpler, line-based format, <i>grub.cfg</i> is a more powerful, script-like language. This command attempts to translate the entries and settings from the older format to the new one, helping users adapt their existing boot configurations without having to manually rewrite them from scratch. <br><br>It's particularly useful when upgrading a system that previously used GRUB Legacy to a distribution that now defaults to GRUB 2, or when setting up a dual-boot environment where one OS might still rely on the older GRUB. However, due to the complexity and differences between the two GRUB versions, the conversion may not always be perfect, and manual review of the generated <i>grub.cfg</i> is often necessary to ensure all boot entries and options are correctly translated.


title: CAVEATS
content:
This command is specific to converting configurations from the older GRUB Legacy to GRUB 2. It does not replace the primary GRUB 2 configuration generation tool, <i>grub-mkconfig</i>. <br><br>The conversion process is an approximation. Due to the significant differences in syntax and features between GRUB Legacy and GRUB 2, not all <i>menu.lst</i> constructs can be perfectly or automatically translated. Manual verification and potential adjustments of the resulting <i>grub.cfg</i> file are highly recommended to ensure correct boot behavior. <br><br>It's important to understand that this command only converts the <i>configuration file</i>; it does not install or update the GRUB bootloader itself.


title: INPUT AND OUTPUT
content:
By default, <i>grub-menulst2cfg</i> reads its input from standard input (<i>stdin</i>) if no <i>MENU_LST_FILE</i> is specified, and writes the converted <i>grub.cfg</i> content to standard output (<i>stdout</i>). This allows for flexible piping and redirection of data. The <i>--output</i> option can be used to direct the output to a specific file.


title: HISTORY
content:
The <i>grub-menulst2cfg</i> command emerged as part of the transition from GRUB Legacy (versions 0.9x) to GRUB 2 (versions 1.9x and newer), a significant rewrite of the GRUB bootloader. GRUB 2 introduced a modular design, a more powerful scripting language for configuration, and many new features, leading to a completely different configuration file format (<i>grub.cfg</i>) compared to GRUB Legacy's simpler <i>menu.lst</i>. <br><br>This utility was developed to ease the migration path for users and distributions. It provided a bridge, allowing existing GRUB Legacy configurations to be translated, albeit imperfectly, into the new GRUB 2 format, thus reducing the manual effort required to adapt to the new bootloader environment. Its relevance has diminished over time as GRUB 2 has become the standard, but it remains a useful tool for systems still transitioning or dealing with legacy setups.


title: PARAMETERS
content:
<b>-o FILE, --output=FILE</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Write the generated configuration to <i>FILE</i> instead of standard output.<br><br><b>-v, --verbose</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Print verbose debugging messages to standard error during the configuration generation process.<br><br><b>-V, --version</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display version information about <i>grub-mkconfig</i> and exit.<br><br><b>--help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display a help message listing all available options and exit.<br><br>


title: DESCRIPTION
content:
<i>grub-mkconfig</i> is a crucial utility for automatically generating the <i>grub.cfg</i> file, the primary configuration file for the GRUB 2 bootloader. It streamlines the complex process of identifying installed operating systems and their kernel images, then creating appropriate boot entries.<br><br>The command gathers configuration data from two main sources: user-defined settings in <i>/etc/default/grub</i> and a series of executable scripts located in <i>/etc/grub.d/</i>. These scripts are responsible for detecting various components, such as Linux kernels, initramfs images, and other installed operating systems (often with the help of <i>os-prober</i>).<br><br>The generated <i>grub.cfg</i> is typically saved to a location like <i>/boot/grub/grub.cfg</i> or <i>/boot/grub2/grub.cfg</i>. By automating this process, <i>grub-mkconfig</i> significantly reduces the risk of errors associated with manual configuration file editing. It ensures that GRUB's boot menu accurately reflects the system's current state, making system updates and multi-boot setups more manageable. Direct manual editing of <i>grub.cfg</i> is generally discouraged because changes will be overwritten the next time this command is run.


title: CAVEATS
content:
<b>Caveats and Limitations:</b><br><br><i>grub-mkconfig</i> requires <b>root</b> privileges to run and write the configuration file to system directories.<br><br>Manual edits made directly to <i>grub.cfg</i> are generally overwritten upon subsequent runs of <i>grub-mkconfig</i>. All customizations should primarily be made in <i>/etc/default/grub</i> or by adding custom scripts to the <i>/etc/grub.d/</i> directory.<br><br>The command's ability to detect other operating systems (such as Windows or alternative Linux distributions) is dependent on the <i>os-prober</i> package being installed and properly enabled on the system.<br><br>While generally safe, it's always prudent to consider backing up your existing <i>grub.cfg</i> before allowing <i>grub-mkconfig</i> to overwrite it, especially if you have a highly customized boot setup.


title: CONFIGURATION FILES
content:
<i>grub-mkconfig</i> relies on specific configuration files and directories to generate the final <i>grub.cfg</i>. These include:<br><br><b><i>/etc/default/grub</i></b>:<br>This file contains user-editable variables that define global GRUB settings, such as the default boot entry, timeout duration, appearance (theme), and kernel parameters to be passed to Linux. It's the primary location for general user customization.<br><br><b><i>/etc/grub.d/</i></b>:<br>This directory contains a series of executable scripts. Each script is responsible for generating a specific section or entry within the <i>grub.cfg</i> file. Examples include <i>10_linux</i> (for detecting Linux kernels), <i>30_os-prober</i> (for detecting other operating systems), and <i>40_custom</i> (for user-defined entries). These scripts are executed in alphanumeric order, and their output is concatenated to form the final configuration file.<br><br><b>Common Usage (update-grub)</b>:<br>On many Linux distributions, particularly Debian and Ubuntu, users commonly invoke `update-grub` instead of directly running `grub-mkconfig`. `update-grub` is typically a simple wrapper script or a symlink that executes `grub-mkconfig -o /boot/grub/grub.cfg` with the appropriate system-specific paths, making the process even simpler for end-users.


title: HISTORY
content:
The GRUB bootloader underwent a significant evolution from GRUB Legacy (version 0.9x) to GRUB 2. GRUB Legacy used a simpler <i>menu.lst</i> file which was often manually edited.<br><br>GRUB 2, initially released in 2009 and widely adopted in distributions post-2010, introduced a more robust and modular configuration system. With GRUB 2, direct manual editing of the main <i>grub.cfg</i> file became discouraged due to its complexity and the potential for errors.<br><br><i>grub-mkconfig</i> was developed as a core component of GRUB 2 to automate the generation of <i>grub.cfg</i>. It processes configuration fragments from <i>/etc/grub.d/</i> scripts and user settings from <i>/etc/default/grub</i>, ensuring a consistent and update-friendly boot configuration. This shift aimed to improve stability, facilitate automated updates of boot entries (e.g., when new kernels are installed), and reduce the burden of manual configuration for users.


title: SYNOPSIS
content:
<b>grub-mkdevicemap</b> [<i>OPTION</i>]... [<i>FILE</i>]<br>If <i>FILE</i> is specified, the device map is written to it. Otherwise, it is written to standard output.


title: PARAMETERS
content:
<b><i>FILE</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Optional argument. Specifies the path where the generated device map should be written. If omitted, the map is written to standard output.<br><br><b><b>-n</b>, <b>--no-floppy</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prevents <i>`grub-mkdevicemap`</i> from probing floppy disk devices when generating the map.<br><br><b><b>-s</b>, <b>--skip-missing</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Instructs the command to not generate entries for disks that are identified but currently missing from the system.<br><br><b><b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a help 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:
<i>`grub-mkdevicemap`</i> is a utility from the GRUB (GRand Unified Bootloader) suite designed to create or update the <i>`device.map`</i> file. This essential file serves as a crucial mapping between GRUB's internal device naming conventions (e.g., <i>`(hd0)`</i>, <i>`(hd1)`</i> for hard disks) and the operating system's device names (e.g., <i>`/dev/sda`</i>, <i>`/dev/sdb`</i>, <i>`/dev/nvme0n1`</i>).<br><br>The command scans all available block devices on the system and attempts to determine their corresponding GRUB device names. The generated map is vital for GRUB to correctly identify the physical disks and partitions it needs to access during the boot process, including the root filesystem and the GRUB installation partition. Without an accurate <i>`device.map`</i>, GRUB may fail to locate its configuration files or the operating system's kernel, leading to boot failures.<br><br>Typically, <i>`grub-mkdevicemap`</i> is run automatically during GRUB installation (e.g., via <i>`grub-install`</i>). However, it might need to be executed manually when significant hardware changes occur, such as adding or removing disks, or when the order of disks changes in the BIOS/UEFI settings, to ensure GRUB's continued ability to boot the system correctly. The generated file is usually placed at <i>`/boot/grub/device.map`</i> or <i>`/boot/grub2/device.map`</i>.


title: CAVEATS
content:
Requires <b>root privileges</b> to scan and identify block devices on the system.<br>An outdated or incorrect <i>`device.map`</i> can prevent GRUB from locating boot partitions, leading to <b>boot failures</b>.<br>The order of disks recognized by the operating system (e.g., <i>`/dev/sda`</i>, <i>`/dev/sdb`</i>) might not always match the order GRUB or the BIOS/UEFI expects (<i>`(hd0)`</i>, <i>`(hd1)`</i>).<br>Modifying the <i>`device.map`</i> manually without proper understanding can lead to an unbootable system.


title: USAGE EXAMPLE
content:
To generate and save the device map to the standard GRUB location (requires root privileges):<br><i><code>sudo grub-mkdevicemap -n > /boot/grub/device.map</code></i><br><br>To view the generated map without saving:<br><i><code>sudo grub-mkdevicemap</code></i>


title: IMPORTANCE OF <I>DEVICE.MAP</I>
content:
The <i>`device.map`</i> file is critical because GRUB uses its own syntax for identifying disks (e.g., <i>`(hd0)`</i> for the first hard disk) which may not directly correspond to the kernel's assigned device names (e.g., <i>`/dev/sda`</i>). This mapping ensures GRUB can correctly locate the boot partition and other necessary files, especially in systems with multiple disks or specific boot orders.


title: HISTORY
content:
<i>`grub-mkdevicemap`</i> is an integral part of the <b>GRUB 2</b> bootloader suite, which superseded the original GRUB Legacy. While the concept of a device map existed in GRUB Legacy, GRUB 2 introduced a more modular and robust architecture, and `grub-mkdevicemap` was developed as the dedicated utility to manage this crucial mapping.<br><br>Its development has been closely tied to the evolution of GRUB 2 itself, aiming to automate and simplify the process of mapping physical disks to GRUB's internal device names, thereby ensuring consistent boot behavior across various hardware configurations. It has remained a stable and essential component for managing GRUB's understanding of the system's disk topology.


title: PARAMETERS
content:
<b><b>-o</b>, <b>--output</b>=<I>FILE</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Write the generated GRUB font to <I>FILE</I>.<br><br><b><b>-s</b>, <b>--size</b>=<I>SIZE</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set the font size in pixels for the generated font.<br><br><b><b>-r</b>, <b>--range</b>=<I>RANGE</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify character ranges to include in the font. Ranges are given in Unicode hexadecimal notation (e.g., U+0000-U+00FF, U+0400-U+04FF). This option can be specified multiple times.<br><br><b><b>-b</b>, <b>--bold</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Render the font with bold styling.<br><br><b><b>-i</b>, <b>--italic</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Render the font with italic styling.<br><br><b><b>-a</b>, <b>--autohint</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enable FreeType's autohinter for improved rendering.<br><br><b><b>-f</b>, <b>--force</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Overwrite the output file if it already exists without prompting.<br><br><b><b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display a 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:
<b>grub-mkfont</b> is a utility included in the GRUB bootloader package, designed to convert <I>TrueType Font</I> (TTF) files into a format usable by GRUB. This command is essential for customizing the appearance of the GRUB boot menu, allowing users to incorporate specific fonts, including those required for internationalization or custom graphical themes.<br><br>It enables the display of a wider range of characters beyond the default console font, supporting various languages and symbols. The utility takes a TTF file, specifies character ranges to include, and outputs a GRUB-compatible font file (typically .pf2 or .pfw). This font file can then be referenced in the <I>grub.cfg</I> configuration to enhance the GRUB boot experience, creating a more visually appealing and accessible boot environment.


title: CAVEATS
content:
<b>grub-mkfont</b> strictly requires <I>TrueType Font</I> (TTF) files as input. The generated font files are optimized for GRUB's limited display capabilities, which means complex font features or very high resolutions might not render perfectly.<br><br>Users must carefully specify character ranges to ensure all required characters are included, as omitting ranges will result in missing characters in GRUB's display.


title: OUTPUT FILE FORMAT
content:
The output of <b>grub-mkfont</b> is typically a <I>GRUB Portable Font</I> file, often with a <I>.pf2</I> or <I>.pfw</I> extension. This compact format is specifically designed for efficient loading and rendering by the GRUB bootloader, ensuring minimal overhead during the boot process.


title: INTEGRATION WITH GRUB
content:
Once a font file is generated, it needs to be placed in an accessible location for GRUB (e.g., <I>/boot/grub/fonts/</I>). It is then loaded in the <I>grub.cfg</I> configuration file using the `loadfont` command, for example: <I>loadfont /boot/grub/fonts/myfont.pf2</I>.<br><br>Subsequently, the font can be applied to the graphical menu by setting the `gfxfont` variable: <I>set gfxfont=myfont</I>.


title: HISTORY
content:
<b>grub-mkfont</b> is a component of the GRUB 2 bootloader suite, which represents a significant rewrite and advancement over the original GRUB Legacy. Introduced with GRUB 2, this command provides the necessary utility for handling <I>TrueType fonts</I>, a feature crucial for improved internationalization and graphical boot menu capabilities.<br><br>Its development reflects GRUB's shift towards a more modular and feature-rich architecture, allowing greater customization of the boot environment beyond basic console text.


title: SYNOPSIS
content:
<b>grub-mkimage</b> [<i>OPTION</i>...] <b>-o</b> <I>OUTPUT_FILE</I> <b>-O</b> <I>FORMAT</I> [<i>MODULES</i>...]<br><i>Common invocation example:</i> <b>grub-mkimage</b> <b>-d</b> <I>/usr/lib/grub/i386-pc</I> <b>-O</b> <I>i386-pc</I> <b>-o</b> <I>core.img</I> <I>biosdisk part_msdos normal multiboot</I>


title: PARAMETERS
content:
<b>-o, --output=FILE</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the output file path for the generated GRUB image.<br><br><b>-d, --directory=DIR</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Use GRUB images and modules found in the specified directory. Defaults to <I>/usr/lib/grub/&lt;platform&gt;</I>.<br><br><b>-p, --prefix=DIR</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set the GRUB root directory (prefix) where GRUB looks for its modules and configuration files at boot time.<br><br><b>-c, --config=FILE</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Embed the content of the specified file as an early GRUB configuration script, executed before <I>grub.cfg</I> is loaded.<br><br><b>-O, --format=FORMAT</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the target platform and image format (e.g., <I>i386-pc</I>, <I>x86_64-efi</I>, <I>arm64-efi</I>). This is crucial for cross-platform compatibility.<br><br><b>-m, --memdisk=FILE</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Embed the specified file as a memdisk (initial RAM disk) within the GRUB image.<br><br><b>-v, --verbose</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Print verbose messages during image generation, useful for debugging.<br><br><b>-n, --dry-run</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Perform a dry run; don't actually generate the image, but print the modules and files that would be included.<br><br><b>-C, --compression=(xz|none|auto)</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Choose the compression algorithm for the core image. Options include <I>xz</I>, <I>none</I>, or <I>auto</I>.<br><br><b>--dtb=FILE</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Embed a Device Tree Blob (DTB) file into the GRUB image, primarily for ARM-based systems.<br><br>


title: DESCRIPTION
content:
The <b>grub-mkimage</b> command is a crucial utility within the GRUB (GRand Unified Bootloader) suite, responsible for generating custom GRUB boot images. It takes various GRUB modules, configuration files, and architecture-specific settings to produce a bootable image (e.g., <I>core.img</I> for BIOS or <I>bootx64.efi</I> for UEFI systems). This command is highly flexible, allowing administrators to tailor GRUB's capabilities, embed specific drivers, cryptographic keys, or initial ramdisks directly into the boot image. While typically invoked indirectly by tools like <I>grub-install</I>, understanding its options is essential for advanced GRUB customization, troubleshooting boot issues, or creating specialized bootable media like rescue disks or network boot images. It ensures that the minimal set of GRUB modules required for initial boot is packaged efficiently for the target system's firmware and architecture.


title: CAVEATS
content:
<b>grub-mkimage</b> is a low-level tool, and its direct use requires a good understanding of GRUB's architecture and the target system's boot process. Incorrect parameters, especially for <I>--format</I>, <I>--directory</I>, or <I>--prefix</I>, can result in unbootable images. Errors can be subtle and difficult to diagnose without using the <I>--verbose</I> option. It's often safer to rely on higher-level tools like <I>grub-install</I> unless specific customization is required.


title: HISTORY
content:
<b>grub-mkimage</b> is an integral part of GRUB 2, which superseded the original GRUB (now often referred to as GRUB Legacy). GRUB 2 was developed to address limitations of GRUB Legacy, offering a more modular and flexible design. The <I>mkimage</I> utility was introduced as a core component of this new architecture, allowing dynamic assembly of bootable GRUB images tailored to various hardware platforms, firmware types (BIOS, UEFI, PowerPC, SPARC, etc.), and desired functionalities. Its development reflects the need for a highly adaptable bootloader in a diverse computing landscape, moving away from monolithic boot images to a more component-based approach.


title: PARAMETERS
content:
<b><i>LAYOUT</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The XKB keyboard layout name to be converted (e.g., <I>de</I> for German, <I>fr</I> for French, <I>us</I> for US English). This name typically corresponds to the layout names used by <I>setxkbmap</I>.<br><br><b><b>-o</b> <I>FILE</I>, <b>--output=</b><I>FILE</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the path and filename for the generated GRUB keyboard layout (<i>.gkb</i>) file. If this option is omitted, the output will be written to standard output.<br><br><b><b>-v</b>, <b>--verbose</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enable verbose output, displaying additional information about the layout generation process.<br><br><b><b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display a help message and exit.<br><br><b><b>--version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Print version information and exit.<br><br>


title: DESCRIPTION
content:
The <b>grub-mklayout</b> command is a utility from the GRUB bootloader suite designed to convert standard XKB (X Keyboard Extension) keyboard layout definitions into a format understood by GRUB.<br><br>This is crucial for users with non-US keyboards who need to interact with the GRUB command line, for instance, when entering passwords, editing boot entries, or performing recovery operations before the operating system has fully loaded.<br><br>By creating a <i>.gkb</i> file specific to a language or region (e.g., German, French), <b>grub-mklayout</b> ensures that keystrokes typed at the GRUB prompt correspond to the expected characters on the user's physical keyboard, providing correct input for special characters, numbers, and symbols that might differ from a standard US layout.


title: CAVEATS
content:
The keyboard layout generated by <b>grub-mklayout</b> is only effective within the GRUB command-line environment and does not influence the keyboard layout used by the operating system once it has booted.<br><br>While it translates common XKB layouts, it may not support all complex or highly specialized features of the XKB system.


title: USAGE IN GRUB
content:
After generating a <i>.gkb</i> file, it must be placed in a GRUB-accessible location (e.g., <I>/boot/grub/layouts/</I>). To activate it in the GRUB command line or <I>grub.cfg</I>, use the following commands:<br><br>1. <I>insmod keylayout</I> (to load the keylayout module)<br>2. <I>keymap &lt;layout_name&gt;</I> (to apply the specific layout, e.g., <I>keymap de</I>)


title: EXAMPLE
content:
To generate a German keyboard layout file named <I>de.gkb</I> and place it in the <I>/boot/grub/layouts/</I> directory, you would typically run:<br><br><b>grub-mklayout -o /boot/grub/layouts/de.gkb de</b>


title: HISTORY
content:
<b>grub-mklayout</b> is an integral part of the GRUB 2 bootloader project, developed to enhance its internationalization capabilities. Its introduction addressed the critical need for robust keyboard layout support at the pre-boot stage, allowing users from diverse linguistic backgrounds to interact seamlessly with the GRUB command line for system maintenance and troubleshooting, a feature less robust in earlier bootloaders.


title: PARAMETERS
content:
<b>-d, --grub-mkimage-parameters=<I>PARAMETERS</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Passes additional <I>PARAMETERS</I> directly to the <b>grub-mkimage</b> command during the image generation process. This allows for fine-grained control over the modules included or other <b>grub-mkimage</b> options.<br><br><b>-a, --net-file-name=<I>FILENAME</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the default network boot filename that will be used by PXE clients (e.g., <I>grub.efi</I>, <I>pxelinux.0</I>). This name is typically placed in the architecture-specific subdirectory.<br><br><b>-s, --subdir=<I>SUBDIR</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies a custom <I>SUBDIR</I> within the target directory where the architecture-specific images will be installed. By default, GRUB uses architecture names (e.g., <I>i386-pc</I>, <I>x86_64-efi</I>) as subdirectories.<br><br><b>-r, --root-directory=<I>PATH</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Treats <I>PATH</I> as the root of the GRUB installation. This is useful when generating images from a chroot environment or when GRUB files are located in a non-standard prefix.<br><br><b>-v, --verbose</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints verbose messages during execution, showing details about the image generation process and files being created.<br><br><b>--version</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays version information and exits.<br><br><b>-h, --help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a help message describing command options and usage, then exits.<br><br>


title: DESCRIPTION
content:
The <b>grub-mknetdir</b> command is used to prepare a directory for network booting GRUB via TFTP. It automates the complex process of creating architecture-specific GRUB core images and placing them in a suitable subdirectory structure (e.g., <I>i386-pc</I>, <I>x86_64-efi</I>) within the specified target directory. These generated images include the necessary network modules for TFTP and PXE booting. <br><br>Essentially, this command simplifies the setup of a TFTP server's root directory by providing ready-to-serve GRUB boot files for various hardware platforms. It internally leverages <b>grub-mkimage</b> to create these bootable images, ensuring they contain the correct modules for network-based booting. This significantly streamlines the deployment of operating systems over a network, especially in environments with diverse client architectures.


title: CAVEATS
content:
The functionality of <b>grub-mknetdir</b> heavily depends on the GRUB modules and platforms installed on the system. If required modules or platform support files are missing, it may fail to generate bootable images for certain architectures. A functional TFTP server and, for PXE, a DHCP server configured to point to the TFTP server, are prerequisites for utilizing the generated network boot directory.


title: INTERNAL MECHANISM
content:
Under the hood, <b>grub-mknetdir</b> orchestrates multiple calls to <b>grub-mkimage</b> for each supported architecture (e.g., <I>i386-pc</I>, <I>x86_64-efi</I>, <I>arm64-efi</I>). For each architecture, it intelligently selects and bundles the necessary GRUB modules, including those required for network protocols like TFTP, HTTP, and DHCP, into a minimal boot image (e.g., <I>core.img</I> or <I>grub.efi</I>). These images are then placed into an organized directory structure, ready to be served by a TFTP server.


title: TFTP AND PXE SETUP
content:
To effectively use the output of <b>grub-mknetdir</b>, a TFTP server must be configured to serve the created directory. For PXE booting, a DHCP server also needs to be set up to provide clients with the IP address of the TFTP server and the boot filename (often specified using DHCP options like 66 and 67). Clients will then download the appropriate GRUB image and configuration files from the TFTP server to initiate the network boot process.


title: HISTORY
content:
<b>grub-mknetdir</b> is an integral part of the GRand Unified Bootloader (GRUB) project, specifically introduced in GRUB 2. Its development was driven by the increasing complexity of network booting scenarios, including support for multiple architectures (i386, x86_64, ARM, etc.) and firmware interfaces (BIOS, UEFI). Prior to this command, setting up a comprehensive GRUB netboot environment often required manual execution of <b>grub-mkimage</b> for each desired architecture and a deeper understanding of GRUB's module system. <br><br>The command aims to streamline and automate this process, making GRUB's powerful network boot capabilities more accessible and robust. Its existence reflects GRUB's continuous evolution to support diverse hardware and boot methods in modern computing environments.


title: PARAMETERS
content:
<b><b>-h</b>, <b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display a help message and exit.<br><br><b><b>-V</b>, <b>--version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display version information and exit.<br><br>


title: DESCRIPTION
content:
<p><code>grub-mkrelpath</code> is a utility from the <I>GRUB (GRand Unified Bootloader)</I> suite. Its primary function is to convert an absolute filesystem path into a path that is relative to GRUB's active root device and filesystem. This is crucial for GRUB configuration files (<code>grub.cfg</code>) and scripts, as GRUB often operates within its own abstracted filesystem view.</p><br><p>For instance, if GRUB has identified <code>/dev/sda1</code> as its root filesystem (e.g., <code>(hd0,msdos1)</code> which contains <code>/boot</code>), and a file is located at <code>/boot/grub/grub.cfg</code>, running <code>grub-mkrelpath /boot/grub/grub.cfg</code> might return <code>/grub/grub.cfg</code>. This relative path is then directly usable by GRUB commands like <I>configfile</I> or <I>chainloader</I> without needing to specify the device or partition, making GRUB configurations more robust and portable across different boot environments or system changes where the absolute mount points might vary. It simplifies path management within the GRUB environment.</p>


title: CAVEATS
content:
The "relative" path generated by <code>grub-mkrelpath</code> is specific to GRUB's internal understanding of its root filesystem. This might not always align with the host operating system's perspective of filesystem paths, especially if GRUB's root device differs from the OS's root. Misuse or misinterpretation of the output can lead to GRUB failing to locate essential boot files.


title: USAGE IN GRUB CONFIGURATION GENERATION
content:
This command is not typically run directly by users on the command line for everyday tasks. Instead, it is primarily employed by GRUB-related scripts, such as <code>grub-mkconfig</code>, during the automatic generation of the <code>grub.cfg</code> configuration file. Its purpose in this context is to ensure that all file paths referenced within the bootloader configuration are correctly resolved relative to GRUB's determined root filesystem, thereby contributing to the creation of robust and portable GRUB configuration files.


title: HISTORY
content:
<code>grub-mkrelpath</code> is an integral part of the <I>GRUB 2</I> bootloader project, which began development in the early 2000s as a complete rewrite of <I>GRUB Legacy</I>. This utility likely emerged during the development of GRUB 2's sophisticated filesystem handling capabilities, enabling more flexible and portable configuration files by standardizing path resolution within the GRUB environment itself. It has been a stable part of the GRUB 2 toolchain for many years.


title: PARAMETERS
content:
<b><b>-o</b>, <b>--output</b>=<i>FILE</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Write the generated image to <i>FILE</i>.<br><br><b><b>-d</b>, <b>--directory</b>=<i>DIR</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Use images and modules under <i>DIR</i> (usually <i>/usr/lib/grub/platform</i>).<br><br><b><b>-m</b>, <b>--modules</b>=<i>MODULES</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify a space-separated list of GRUB modules to embed.<br><br><b><b>-c</b>, <b>--config-file</b>=<i>FILE</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Embed <i>FILE</i> as the <i>grub.cfg</i> configuration.<br><br><b><b>-f</b>, <b>--fonts</b>=<i>FONTS</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Embed a space-separated list of GRUB fonts.<br><br><b><b>-t</b>, <b>--themes</b>=<i>THEMES</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Embed a space-separated list of GRUB themes.<br><br><b><b>--compress</b>=<i>no|xz|gz|lzo</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Choose compression method for GRUB modules.<br><br><b><b>--locales</b>=<i>LOCALES</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Embed a space-separated list of locales.<br><br><b><b>--sfs-path</b>=<i>PATH</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The path to the SquashFS image containing GRUB modules.<br><br><b><b>--grub-mkimage</b>=<i>PATH</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Path to the <i>grub-mkimage</i> binary to use.<br><br><b><b>--label</b>=<i>LABEL</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set the volume label for the ISO9660 filesystem.<br><br><b><b>--root-directory</b>=<i>DIR</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the root directory from which to read files.<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;Print version information and exit.<br><br>


title: DESCRIPTION
content:
<i>grub-mkrescue</i> is a utility from the GRUB bootloader suite designed to create a standalone, bootable GRUB image, typically an ISO file. This image can then be burned to a CD/DVD or written to a USB drive to create a rescue disk. It's invaluable for system administrators and users facing boot issues, as it allows booting into a GRUB shell or a basic environment where they can diagnose and repair problems, such as reinstalling GRUB, correcting <i>grub.cfg</i> errors, or accessing filesystems. The command works by bundling essential GRUB modules, kernel images, and configuration files into a self-contained image. It intelligently determines the necessary files based on the GRUB installation or specified modules, providing a flexible recovery tool.


title: CAVEATS
content:
<i>grub-mkrescue</i> typically requires <i>xorriso</i> (or <i>mkisofs</i> on older systems) to be installed on the system to create the final ISO image. The generated image provides a minimal GRUB environment; advanced hardware or specific filesystem support might require explicit inclusion of additional modules via the <b>--modules</b> option.<br><br>Creating the image often requires root privileges, especially when accessing system GRUB files.


title: DEPENDENCIES
content:
<i>grub-mkrescue</i> relies on external utilities like <i>xorriso</i> (or <i>mkisofs</i>) to create the ISO image and internally uses <i>grub-mkimage</i> to build the GRUB core image. These tools must be present and accessible in the system's PATH for <i>grub-mkrescue</i> to function correctly.


title: USAGE EXAMPLE
content:
To create a basic GRUB rescue ISO file named <i>grub_rescue.iso</i>:<br><br><b>grub-mkrescue -o grub_rescue.iso</b><br><br>To create a customized rescue ISO, embedding specific modules and a custom configuration file:<br><br><b>grub-mkrescue -o custom_rescue.iso --modules="part_gpt fat ext2 search normal configfile linux" --config-file=/path/to/custom_grub.cfg</b>


title: HISTORY
content:
GRUB (Grand Unified Bootloader) has been the de facto standard bootloader for many Linux distributions since the early 2000s. GRUB 2.0, a complete rewrite, introduced modularity and extensibility, including support for UEFI. <i>grub-mkrescue</i> emerged as part of the GRUB 2.0 suite, simplifying the creation of bootable rescue media, an essential tool for system recovery that was more cumbersome with GRUB Legacy. Its development is intertwined with the ongoing evolution and maintenance of the GRUB 2.0 project.


title: PARAMETERS
content:
<b><b>-o</b>, <b>--output=</b><i>FILE</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the output file path for the standalone GRUB image.<br><br><b><b>-d</b>, <b>--directory=</b><i>DIR</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Use GRUB images and modules from the specified directory. Defaults to GRUB's installation directory.<br><br><b><b>-C</b>, <b>--compress=</b><i>(gzip|lzma|xz|none)</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Compress the core image using the specified algorithm (gzip, lzma, xz) or none.<br><br><b><b>-c</b>, <b>--config-file=</b><i>FILE</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Embed a custom GRUB configuration file (e.g., grub.cfg) into the image.<br><br><b><b>-k</b>, <b>--kernel-file=</b><i>FILE</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Embed a kernel file (e.g., vmlinuz) into the image.<br><br><b><b>-i</b>, <b>--initrd-file=</b><i>FILE</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Embed an initramfs/initrd file into the image.<br><br><b><b>-M</b>, <b>--memdisk-image=</b><i>FILE</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Embed a memdisk image into the generated GRUB image.<br><br><b><b>-m</b>, <b>--modules=</b><i>MODULES</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Comma-separated list of GRUB modules to embed (e.g., 'linux,part_msdos,ext2').<br><br><b><b>-L</b>, <b>--locale-directory=</b><i>DIR</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the directory containing GRUB locale files.<br><br><b><b>-l</b>, <b>--locale=</b><i>LOCALE</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Embed a specific locale into the image (e.g., 'en_US').<br><br><b><b>-O</b>, <b>--format=</b><i>FORMAT</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the target platform and image format (e.g., 'i386-pc' for BIOS, 'x86_64-efi' for UEFI). This is crucial for compatibility.<br><br><b><b>--install-modules=</b><i>MODULES</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Similar to <b>-m</b>, but ensures these modules are installed as part of the core image for initial boot.<br><br><b><b>--modules-only</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Generate an image containing only specified modules, without a full core, useful for specific module testing or loading.<br><br><b><b>--themes=</b><i>THEMES</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Embed specified GRUB themes into the image.<br><br><b><b>--fonts=</b><i>FONTS</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Embed specified GRUB fonts into the image.<br><br><b><b>--debug</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enable debug messages during the image generation process, useful for troubleshooting.<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 a help message and exit.<br><br><b><i>FILES...</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Any additional files or directories to be included in the GRUB image. These will be accessible from the GRUB environment.<br><br>


title: DESCRIPTION
content:
<i>grub-mkstandalone</i> is a powerful utility from the GRUB (Grand Unified Bootloader) 2 project designed to generate a single, self-contained GRUB image. Unlike a full GRUB installation that relies on a specific file system structure, this command consolidates the necessary GRUB core, essential modules, custom configuration files, and optionally a kernel and initrd into one portable binary file. This standalone image can then be embedded into a Master Boot Record (MBR), a GUID Partition Table (GPT) boot sector, or used for creating bootable media such as USB drives, CD-ROMs, or network boot (PXE) images. It provides a convenient way to create a bootloader that does not depend on an existing GRUB installation on the target system, making it ideal for rescue disks, firmware updates, or specialized boot environments. Essentially, it streamlines the process of preparing GRUB for diverse and non-standard boot scenarios, ensuring all necessary components are bundled together for immediate use.


title: CAVEATS
content:
The generated standalone image is highly specific to the target architecture and firmware type (e.g., PC-BIOS, UEFI, ARM). Incorrectly chosen options for <b>--format</b> (<b>-O</b>) can lead to an unbootable image.<br><br>While <i>grub-mkstandalone</i> simplifies the process, a deep understanding of GRUB modules, file systems, and boot processes is often required for advanced or troubleshooting scenarios. Missing essential modules or incorrect paths can prevent the image from booting or recognizing necessary hardware/partitions.


title: TYPICAL USE CASES
content:
Creating custom bootable USB drives or CD-ROMs for system rescue, diagnostics, or minimal installations.<br>Generating images for network booting (PXE) environments, allowing multiple machines to boot from a central server.<br>Embedding a minimal GRUB bootloader into a custom device or firmware where a full OS installation is not present.<br>Preparing 'memdisk' images for specific boot requirements, allowing an entire system image to reside in RAM.


title: RELATIONSHIP WITH GRUB-MKIMAGE
content:
<i>grub-mkstandalone</i> often acts as a higher-level wrapper around <i>grub-mkimage</i>. While <i>grub-mkimage</i> focuses on generating the core GRUB image and basic modules for a specific platform, <i>grub-mkstandalone</i> adds the capability to embed additional user-specified files like configuration, kernels, initramfs, locales, themes, and arbitrary data, thus providing a more complete, 'standalone' boot package ready for deployment.


title: HISTORY
content:
<i>grub-mkstandalone</i> is a core component of GRUB 2, which superseded GRUB Legacy. GRUB 2 was developed to support a broader range of architectures, file systems, and firmware interfaces like UEFI, providing more flexibility and robustness. This specific utility emerged to address the growing need for easily deployable, self-contained bootloaders. Its development reflects the evolution of boot environments, moving beyond traditional hard disk installations to encompass USB drives, network boots (PXE), and embedded systems. It consolidates functionalities that previously might have required manual assembly of GRUB components, simplifying the creation of highly portable and adaptable boot solutions.


title: PARAMETERS
content:
<b>-r, --read-only</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Mount the filesystem in read-only mode.<br><br><b>-d, --debug</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Print debug messages to standard error.<br><br><b>-o, --offset=OFF</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify an offset in bytes into the device or image from where to start interpreting the filesystem. Useful for mounting partitions within disk images.<br><br><b>-s, --skip=NUM</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Skip NUM bytes from the device. Similar to --offset.<br><br><b>-t, --type=FSTYPE</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the filesystem type to be mounted (e.g., ext2, fat, ntfs). GRUB's internal drivers will be used.<br><br><b>-v, --verbose</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Print verbose messages.<br><br><b>--version</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Print program version information and exit.<br><br><b>--help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display a help message and exit.<br><br>


title: DESCRIPTION
content:
<b>grub-mount</b> is a utility from the GNU GRUB project that allows mounting filesystems understood by GRUB onto a regular Linux filesystem. This means it can interpret and mount various filesystems (like ext2/3/4, XFS, Btrfs, FAT, NTFS, HFS+, UFS, etc.) and even GRUB-specific constructs (like <i>loopback</i> devices or <i>raid</i> volumes) that might be part of a GRUB installation or disk image. It acts as a bridge, making GRUB's internal filesystem view accessible via the Filesystem in Userspace (FUSE) framework, enabling users to inspect or modify GRUB-related files (e.g., <i>grub.cfg</i>, GRUB modules) from a host operating system. It's particularly useful for debugging GRUB installations, examining bootable disk images, or managing GRUB modules without needing to boot into GRUB.


title: CAVEATS
content:
Requires root privileges for most operations as it interacts with low-level device files or disk images.<br>Relies on the FUSE kernel module being loaded and available.<br>Only mounts filesystems that GRUB itself can understand and process, using GRUB's own internal drivers.<br>Can be destructive if used incorrectly in read-write mode on a live system or important image, though read-only mode is safer.<br>May not correctly interpret all complex GRUB device mappings (e.g., specific RAID or LVM setups if not fully supported by GRUB's internal filesystem drivers).


title: FUSE-BASED UTILITY
content:
<b>grub-mount</b> utilizes the <i>Filesystem in Userspace</i> (FUSE) framework, which allows unprivileged users to create their own filesystems without modifying the kernel. This design choice makes <b>grub-mount</b> flexible and safe to operate in user space, while still providing the necessary low-level access to interpret GRUB-specific structures.


title: TYPICAL USAGE
content:
A common use case for <b>grub-mount</b> is to inspect the contents of a GRUB installation on a raw disk image (e.g., a <i>.img</i> file from a virtual machine or a disk clone) or directly on a physical drive. For example, to check the <i>grub.cfg</i> file or verify if specific GRUB modules are present within the boot partition.<br><br>Example: <i>sudo grub-mount /dev/sda1 /mnt/grub_root</i><br>Example with offset: <i>sudo grub-mount -o 1048576 disk_image.img /mnt/img_mount</i> (where 1048576 is an offset to a partition within the image).


title: HISTORY
content:
<b>grub-mount</b> is a component of the GNU GRUB (Grand Unified Bootloader) project, which has been in active development since the late 1990s. As GRUB evolved to support a wider array of filesystems, disk layouts, and complex boot scenarios, the need arose for tools that could inspect and manage GRUB's internal view of the boot environment from a running operating system. <b>grub-mount</b> was developed to fill this gap, leveraging the FUSE framework to provide a convenient interface for debugging and development. It became a standard utility within the GRUB toolkit, alongside <b>grub-mkimage</b> and <b>grub-install</b>, enabling deeper interaction with GRUB's boot logic without needing to restart the machine or use a live environment.


title: PARAMETERS
content:
<b>MENU_ENTRY</b><br>&nbsp;&nbsp;&nbsp;&nbsp;The title or numerical index of the GRUB menu entry to boot into for the next restart. For titles, the string must exactly match an entry in 'grub.cfg'.<br><br><b>-h, --help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display a help message and exit.<br><br><b>-V, --version</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display version information and exit.<br><br><b>--boot-directory=DIR</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Use 'DIR' as the boot directory instead of the default '/boot'.<br><br>


title: DESCRIPTION
content:
The `grub-reboot` command is a utility for the GRand Unified Bootloader (GRUB) that allows a user to specify the default menu entry for the <i>next</i> boot. Unlike `grub-set-default`, which makes a permanent change to GRUB's default boot entry, `grub-reboot`'s effect is temporary, applying only to the immediate subsequent system restart. After the system reboots once into the specified entry, GRUB reverts to its normal default boot behavior (as defined by `GRUB_DEFAULT` in `/etc/default/grub`).<br><br>This command is particularly useful for tasks such as testing a new kernel version, booting into a recovery mode, or temporarily switching to a different operating system installed on the same machine without having to manually select the entry at the GRUB menu or modify persistent configuration files. It operates by writing the chosen menu entry's index or title to the `next_entry` variable within GRUB's environment block, typically located at `/boot/grub/grubenv`. When GRUB starts, it checks for this variable and uses it to determine the boot entry for that specific session. Root privileges are required to execute `grub-reboot` successfully.


title: CAVEATS
content:
<b>Root Privileges Required</b>: This command must be run with superuser (root) privileges, typically using `sudo`.<br><b>Temporary Effect</b>: `grub-reboot` only affects the very next boot. After that, GRUB reverts to its regular default setting.<br><b>No Automatic Reboot</b>: This command only configures GRUB; it does not initiate a system reboot. You must manually issue a `reboot` command afterwards.<br><b>GRUB Configuration Dependency</b>: For `grub-reboot` to function correctly, GRUB must be configured to utilize the environment block and check for the `next_entry` variable. This is usually the case if `GRUB_DEFAULT` in `/etc/default/grub` is set to `0` or `saved`. If `GRUB_DEFAULT` is set to a specific fixed number greater than `0`, `grub-reboot` might not behave as expected as it tries to override the default for the <i>next</i> boot, but the <i>permanent</i> fixed default might take precedence or cause confusion.<br><b>Exact Menu Entry Match</b>: When using a menu entry title, it must be an exact string match (case-sensitive) to an entry found in your `grub.cfg` file. Minor discrepancies will lead to failure. Numeric indices are fragile as they can change after kernel updates or GRUB configuration changes.


title: HOW IT WORKS
content:
The `grub-reboot` command operates by writing the `MENU_ENTRY` value into a special GRUB environment block file, typically located at `/boot/grub/grubenv`. This file stores a set of key-value pairs that GRUB can read during the boot process. Specifically, `grub-reboot` sets the `next_entry` variable within this file. When GRUB initializes, it checks for the presence and value of `next_entry`. If found, GRUB uses this value to determine which menu item to boot into for that specific session, overriding the system's default `GRUB_DEFAULT` setting. After the system successfully boots using `next_entry`, GRUB (or the `grub-editenv` utility called during the boot process) automatically clears or decrements this variable, ensuring that on subsequent reboots, the normal `GRUB_DEFAULT` configuration is honored.


title: USAGE EXAMPLES
content:
Here are a few common examples of using `grub-reboot`:<br><br><i>Reboot into the first GRUB menu entry (index 0):</i><br>sudo grub-reboot 0 && sudo reboot<br><br><i>Reboot into a specific kernel version (assuming an 'Advanced options' submenu):</i><br>sudo grub-reboot "Advanced options for Ubuntu>Ubuntu, with Linux 5.15.0-52-generic" && sudo reboot<br><i>Note: The exact string 'Ubuntu, with Linux 5.15.0-52-generic' might vary based on your system. You can inspect your `grub.cfg` or use the `grub-customizer` tool to find exact entry names.</i><br><br><i>Reboot into a different operating system, e.g., Windows Boot Manager:</i><br>sudo grub-reboot "Windows Boot Manager" && sudo reboot<br><br><i>To see available GRUB menu entries, you can inspect `/boot/grub/grub.cfg` (look for `menuentry` lines) or use tools like `grub-customizer`.</i>


title: HISTORY
content:
The `grub-reboot` command is an integral part of the GRUB2 (GRand Unified Bootloader version 2) project. It was introduced to provide a convenient, programmatic way to manage the boot sequence for a single restart, leveraging GRUB2's improved environment block capabilities. Prior to such a command, temporarily changing the boot entry might have involved manual editing of configuration files or interaction with the GRUB prompt during boot, which was less user-friendly and more error-prone. Its development reflects a focus on enhancing usability and automation for system administrators and power users.


title: PARAMETERS
content:
<b>--output=FILE</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the path for the output image file. If not provided, the rendered image data is written to standard output.<br><br><b>--format=FORMAT</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the output image format (e.g., <I>png</I>, <I>tga</I>, <I>jpg</I>). The supported formats depend on the underlying image rendering libraries available to GRUB.<br><br><b>--font=FILE</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the font file (e.g., a TrueType font <I>.ttf</I> file) to use for rendering the text.<br><br><b>--fontsize=SIZE</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Defines the font size in pixels for the rendered text.<br><br><b>--color=COLOR</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the foreground color of the text. Colors can be specified as hexadecimal values (e.g., <I>#RRGGBB</I>) or by common color names (e.g., <I>red</I>, <I>blue</I>).<br><br><b>--bgcolor=COLOR</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the background color of the image. Defaults to transparent if the output format supports an alpha channel; otherwise, it defaults to black.<br><br><b>--width=WIDTH</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the desired width of the output image in pixels. If not specified, the width is determined by the text content.<br><br><b>--height=HEIGHT</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the desired height of the output image in pixels. If not specified, the height is determined by the text content.<br><br><b>--wrap</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables word wrapping for the input text, causing long lines to break into multiple lines within the specified <I>--width</I>.<br><br><b>--version</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints the version information of <b>grub-render-label</b> and exits.<br><br><b>--help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a help message detailing command usage and options, then exits.<br><br>


