# CommandSection

title: DESCRIPTION
content:
<b>git-receive-pack</b> is an essential <i>plumbing</i> command within Git, primarily responsible for handling incoming Git object data and reference updates during a <b>git push</b> operation. It runs on the remote server where the repository resides. When a client executes <b>git push</b>, it communicates with the server, which invokes <b>git-receive-pack</b> to receive the compressed pack-file containing new or updated Git objects (commits, trees, blobs, tags). This command validates the received objects and then attempts to update the corresponding references (branches, tags) in the remote repository.<br><br>It enforces various rules, such as ensuring fast-forward updates by default and executing server-side hooks (<b>pre-receive</b>, <b>update</b>, <b>post-receive</b>) to allow administrators to implement custom logic, security checks, or integrate with external systems. It’s a low-level component that users rarely invoke directly, instead relying on higher-level commands like <b>git push</b> to orchestrate its execution over various transport protocols like SSH or the native Git protocol.


title: CAVEATS
content:
<b>git-receive-pack</b> is a low-level <i>plumbing</i> command and is not intended for direct invocation by end-users; it's automatically called by <b>git push</b> on the remote server. Proper file system permissions are crucial for the repository directory. Server-side hooks (<b>pre-receive</b>, <b>update</b>, <b>post-receive</b>) are executed by this command and can abort a push based on custom logic or policies, making them vital for repository management and security.


title: TRANSPORT PROTOCOLS
content:
<b>git-receive-pack</b> operates over various transport protocols, including SSH, the native Git protocol (often via <b>git-daemon</b>), and the smart HTTP protocol. It handles the specific negotiation and data transfer mechanisms for each, making it adaptable to different deployment scenarios.


title: SERVER-SIDE HOOKS
content:
This command invokes three critical server-side hooks during a push operation:<br><b>pre-receive</b>: Executed once before any references are updated. It can be used to enforce project-wide policies, such as checking commit messages or preventing specific changes.<br><b>update</b>: Executed once for each reference being updated. It provides a per-reference control point, allowing administrators to restrict updates to certain branches or tags based on specific criteria.<br><b>post-receive</b>: Executed once after all references have been successfully updated. This hook is commonly used for integration tasks, such as triggering CI/CD pipelines, sending notifications, or deploying code.


title: REFERENCE UPDATES AND VALIDATION
content:
<b>git-receive-pack</b> is responsible for validating the integrity of the incoming pack-file and ensuring that reference updates (e.g., branch fast-forwards) adhere to Git's rules. By default, it only permits 'fast-forward' pushes, preventing non-linear history changes unless explicitly forced by the client using <b>git push --force</b>.


title: HISTORY
content:
As a core component of Git's distributed nature, <b>git-receive-pack</b> has been an integral part of the Git project since its early development. Its design evolved alongside the Git protocol and the <b>git push</b> command, enabling secure and efficient transmission of repository changes and reference updates across network boundaries. It underpins Git's ability to allow multiple developers to contribute to a shared repository.


title: SYNOPSIS
content:
<i>git reflog</i> [<I>show</I>] [<I>options</I>] [<I>ref</I>]<br><i>git reflog expire</i> [<I>options</I>] [--<I>all</I>]<br><i>git reflog delete</i> [<I>options</I>] [--<I>all</I>] [<I>reflog_entry</I>]


title: PARAMETERS
content:
<b><b>--all</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;For <i>expire</i> and <i>delete</i> subcommands, process reflogs of all references. For <i>show</i>, show all reflogs (equivalent to <i>--walk-reflogs --all</i>).<br><br><b><b>-n &lt;count&gt;</b> or <b>--max-count=&lt;count&gt;</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Limit the number of reflog entries to show for the <i>show</i> subcommand.<br><br><b><b>--relative-date</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show dates relative to the current time (e.g., "2 weeks ago").<br><br><b><b>--date=&lt;format&gt;</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the date format (e.g., 'local', 'iso', 'rfc2822', 'short', 'raw').<br><br><b><b>--expire=&lt;time&gt;</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;For <i>expire</i>, prune reflog entries older than the specified time. Defaults to `90 days` for reachable entries and `30 days` for unreachable.<br><br><b><b>--expire-unreachable=&lt;time&gt;</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;For <i>expire</i>, prune unreachable reflog entries older than the specified time.<br><br><b><b>--stale-fix</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;For <i>expire</i>, prunes entries that point to non-existent objects.<br><br><b><b>--dry-run</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;For <i>expire</i> or <i>delete</i>, don't actually modify the reflog; just show what would be done.<br><br><b><b>--rewriter</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Used with <i>expire</i> to filter which entries are considered.<br><br><b><b>--no-color</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Turn off colored output.<br><br><b><b>--color[=&lt;when&gt;]</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Turn on colored output.<br><br>


title: DESCRIPTION
content:
The <i>git-reflog</i> command is a powerful utility for viewing and managing the <i>reflog</i>, which is a local, chronological record of every change made to the tip of branches and other references in your repository. Unlike the commit history, which records actual commits, the reflog tracks actions like commits, checkouts, merges, resets, and rebases, even if they don't create new commits or if a commit is temporarily "lost" from the branch's history.<br><br>It acts as a safety net, allowing you to easily recover from operations that seem to have lost commits or moved your HEAD to an undesired state. For example, if you accidentally reset a branch or rebase incorrectly, <i>git-reflog</i> can show you the previous state of your HEAD or branch tip, enabling you to use <i>git reset</i> or <i>git checkout</i> to revert to a prior entry. Each entry in the reflog corresponds to a point in time when the reference was updated, along with a timestamp and the action that caused the update.


title: CAVEATS
content:
Reflogs are strictly local to your repository; they are not part of the shared history when you push or pull. Therefore, they cannot be used to recover work lost by others or to restore a branch on a remote server. Reflog entries are also subject to automatic expiration and pruning. By default, entries older than 90 days are pruned if they are reachable, and unreachable entries are pruned after 30 days. This means very old or long-lost changes might eventually be removed.


title: SUBCOMMANDS OF GIT-REFLOG
content:
<ul><li><b>show</b>: This is the default subcommand if none is specified. It displays the reflog of the specified reference (or HEAD by default). You can provide a specific reference like <i>main</i> or <i>HEAD</i>. Output format is similar to <i>git log</i>.</li><li><b>expire</b>: Used to prune old or unreachable entries from the reflog. This is often run automatically by Git's garbage collection (<i>git gc</i>). You can manually control the expiration policy.</li><li><b>delete</b>: Allows you to manually delete a specific entry from the reflog. This is a more drastic operation than <i>expire</i> and should be used with caution, typically after verifying with <i>show</i> and <i>dry-run</i>.</li></ul>


title: REFLOG ENTRY FORMAT
content:
Each reflog entry shows the old and new commit SHAs, the committer identity, a timestamp, and a message describing the action that caused the reflog update. For example: &lt;old_sha&gt; &lt;new_sha&gt; &lt;committer&gt; &lt;timestamp&gt; &lt;action_message&gt;. The action message is often very descriptive, like <i>commit: initial commit</i>, <i>checkout: moving from main to feature</i>, or <i>rebase: aborting rebase</i>. These messages are crucial for understanding the context of each change.


title: HISTORY
content:
The concept of a reference log (reflog) has been an integral part of Git since its early development. It was designed by Linus Torvalds to provide a robust safety net for local operations, allowing users to recover from various mistakes that might otherwise lead to data loss. The `git-reflog` command has been a stable and core component of the Git suite, evolving primarily in its options for filtering and managing reflog entries rather than its fundamental purpose. It underscores Git's philosophy of making it hard to accidentally lose data.


title: PARAMETERS
content:
<b>tagname</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Optional.</i> The name for the new release tag (e.g., "v1.0.0"). If omitted, the command will prompt the user to enter a tag name interactively.<br><br><b>commit</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Optional.</i> The specific commit hash or reference to be tagged. If omitted, the current <i>HEAD</i> commit will be tagged.<br><br>


title: DESCRIPTION
content:
<i>git-release</i> is an external Git command provided by the <i>git-extras</i> suite of utilities. It simplifies the process of creating and pushing a new release tag in a Git repository.<br><br>When invoked, it creates an <b>annotated tag</b>, which is generally preferred for releases as it includes metadata like the tagger's name, email, and date, along with a message. If a tag name is not provided on the command line, it will prompt the user for one. It can tag the current <i>HEAD</i> commit or a specific commit provided as an argument.<br><br>After creating the tag locally, it automatically pushes this new tag to the <i>origin</i> remote, making the release visible to collaborators. This command streamlines a common workflow of marking a specific point in history as a release, reducing manual steps involving `git tag` and `git push --tags`.


title: CAVEATS
content:
This command is not part of the core Git distribution and requires the <i>git-extras</i> package to be installed.<br><br>It provides a basic release tagging mechanism and does not include advanced features found in more comprehensive release management tools, such as changelog generation, automatic version incrementing, or integration with CI/CD pipelines. It primarily automates the `git tag -a` and `git push --tags origin` steps.


title: HISTORY
content:
The <i>git-release</i> command is a component of the <i>git-extras</i> project, an open-source collection of useful Git utilities. <i>git-extras</i> aims to enhance the default Git command-line experience by providing a variety of supplementary commands that automate common or repetitive tasks, extending Git's native capabilities. <i>git-release</i> was developed as part of this collection to simplify the frequent task of marking software releases with annotated tags.


title: SYNOPSIS
content:
<b>git-relink</b> [<b>--force</b>] [<b>--dry-run</b>] [<b>--verbose</b>] [<b>--list</b>] [<b>--relative</b>] [<i>&lt;path&gt;...</i>]


title: PARAMETERS
content:
<b><b>--force</b> or <b>-f</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Force relinking, potentially recreating symlinks even if they appear valid, or overwriting existing ones without prompt.</i><br><br><b><b>--dry-run</b> or <b>-n</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Perform a trial run with no changes made. This option will print what actions `git-relink` would take.</i><br><br><b><b>--verbose</b> or <b>-v</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Provide more detailed output, showing which symbolic links are being processed and their old/new targets.</i><br><br><b><b>&lt;path&gt;...</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Limit the relinking operation to symbolic links located within the specified paths or directories. If no paths are given, the entire Git working tree is scanned.</i><br><br><b><b>--list</b> or <b>-l</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>List all symbolic links tracked by Git in the current repository, along with their resolved targets, without attempting to modify them.</i><br><br><b><b>--relative</b> or <b>-r</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Attempt to convert all symbolic link targets to paths relative to the symlink's location, which is generally preferred for portability within Git repositories. This is often the default behavior or a primary objective of the command.</i><br><br>


title: DESCRIPTION
content:
<i>`git-relink` is an an external utility designed to manage and correct symbolic links within a Git repository. When a Git repository containing symbolic links is cloned, moved, or accessed from different environments, the target paths of these symlinks can become invalid or "broken." This often occurs if symlinks were originally created with absolute paths, or if relative paths become incorrect due to changes in the repository's base directory.<br><br>The `git-relink` command typically scans the Git index for symbolic link entries, evaluates their current targets, and attempts to resolve and recreate them with correct, often repository-relative, paths. This ensures that the codebase remains functional and that symbolic links point to their intended targets, irrespective of the repository's physical location on the filesystem. It is particularly useful in CI/CD pipelines or development setups involving shared repositories across multiple machines.</i>


title: CAVEATS
content:
<i>`git-relink` is not a standard Git command; its functionality and options may vary significantly depending on the specific implementation (user script, third-party tool).<br><br>Improper use, especially without first using `<b>--dry-run</b>`, can lead to unintended modification of symbolic links, potentially breaking build processes or application logic.<br><br>It might not correctly resolve complex symlink chains or symlinks pointing outside the repository root unless explicitly configured.<br><br>It primarily operates on symbolic links tracked by Git; untracked symbolic links are typically ignored.</i>


title: SYMBOLIC LINK BEST PRACTICES IN GIT
content:
<i>When working with Git, it is generally recommended to use relative paths for symbolic links whenever possible. Absolute paths cause issues when the repository is moved or cloned to a different location. `git-relink` attempts to enforce this best practice by converting absolute paths to relative ones, improving the portability of the repository.</i>


title: OPERATING SYSTEM COMPATIBILITY
content:
<i>The behavior of symbolic links can differ significantly across operating systems. While Unix-like systems (Linux, macOS) fully support them, Windows requires elevated privileges to create symlinks and older versions might not support them at all. `git-relink` typically operates on Unix-like filesystems and might not be effective or behave as expected in Windows environments without proper setup (e.g., Git Bash with symlink support enabled).</i>


title: HISTORY
content:
<i>As `git-relink` is not an official Git command, it doesn't have a formal history within the Git project. However, the need for such a utility arose from the challenges of managing symbolic links across different environments when using Git. Developers often commit symbolic links to repositories, but these can break when the repository is cloned to a different path or accessed on different operating systems (e.g., Windows typically handles symlinks differently than Unix-like systems). Consequently, various community-contributed scripts and tools have emerged over time to address this specific problem, aiming to automatically fix or convert symbolic link targets to ensure repository portability and functionality. These utilities typically leverage Git's internal commands and standard filesystem utilities to achieve their goal.</i>


title: SYNOPSIS
content:
<b>git remote</b> [<b>-v</b> | <b>--verbose</b>]<br><b>git remote add</b> [<b>-t</b> &lt;<i>branch</i>&gt;] [<b>-m</b> &lt;<i>master</i>&gt;] [<b>-f</b> | <b>--no-tags</b> | <b>--mirror=&lt;<i>fetch</i>|<i>push</i>&gt;</b>] &lt;<i>name</i>&gt; &lt;<i>url</i>&gt;<br><b>git remote rename</b> &lt;<i>old</i>&gt; &lt;<i>new</i>&gt;<br><b>git remote remove</b> &lt;<i>name</i>&gt;<br><b>git remote set-head</b> &lt;<i>name</i>&gt; (<b>-a</b> | <b>--auto</b> | <b>-d</b> | <b>--delete</b> | &lt;<i>branch</i>&gt;)<br><b>git remote set-branches</b> [<b>--add</b>] &lt;<i>name</i>&gt; &lt;<i>branch</i>&gt;...<br><b>git remote set-url</b> [<b>--push</b>] &lt;<i>name</i>&gt; &lt;<i>newurl</i>&gt; [&lt;<i>oldurl</i>&gt;]<br><b>git remote get-url</b> [<b>--push</b>] [<b>--all</b>] &lt;<i>name</i>&gt;<br><b>git remote show</b> [<b>-n</b>] &lt;<i>name</i>&gt;<br><b>git remote prune</b> [<b>-n</b> | <b>--dry-run</b>] &lt;<i>name</i>&gt;<br><b>git remote update</b> [<b>-p</b> | <b>--prune</b>] [&lt;<i>group</i>&gt; | <b>--all</b>]


title: PARAMETERS
content:
<b><b>-v</b> | <b>--verbose</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Be more verbose; show remote URLs when listing remotes.<br><br><b><b>add</b> &lt;<i>name</i>&gt; &lt;<i>url</i>&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Adds a remote named &lt;<i>name</i>&gt; for the repository at &lt;<i>url</i>&gt;.<br><br><b><b>-t</b> &lt;<i>branch</i>&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;When adding, track only &lt;<i>branch</i>&gt; (and its symlinks) from the remote.<br><br><b><b>-m</b> &lt;<i>master</i>&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;When adding, set the remote's <b>HEAD</b> (default branch) to &lt;<i>master</i>&gt;.<br><br><b><b>-f</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Immediately run <b>git fetch</b> on the new remote after adding it.<br><br><b><b>--no-tags</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;When adding with <b>-f</b>, do not fetch tags along with the remote.<br><br><b><b>--mirror=&lt;<i>fetch</i>|<i>push</i>&gt;</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets up a mirror of the remote for either fetching or pushing.<br><br><b><b>rename</b> &lt;<i>old</i>&gt; &lt;<i>new</i>&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Renames the remote named &lt;<i>old</i>&gt; to &lt;<i>new</i>&gt;.<br><br><b><b>remove</b> | <b>rm</b> &lt;<i>name</i>&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Removes the remote named &lt;<i>name</i>&gt;.<br><br><b><b>set-head</b> &lt;<i>name</i>&gt; &lt;<i>branch</i>&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the default branch (<b>HEAD</b>) for the remote to &lt;<i>branch</i>&gt;.<br><br><b><b>set-head</b> &lt;<i>name</i>&gt; <b>-a</b> | <b>--auto</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Auto-detects and sets the remote's <b>HEAD</b> to its default branch.<br><br><b><b>set-head</b> &lt;<i>name</i>&gt; <b>-d</b> | <b>--delete</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Deletes the configured default branch for the remote.<br><br><b><b>set-branches</b> &lt;<i>name</i>&gt; &lt;<i>branch</i>&gt;...</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Changes the list of branches tracked for the remote. Replaces existing list.<br><br><b><b>set-branches --add</b> &lt;<i>name</i>&gt; &lt;<i>branch</i>&gt;...</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Adds the specified branches to the list of branches tracked for the remote.<br><br><b><b>set-url</b> &lt;<i>name</i>&gt; &lt;<i>newurl</i>&gt; [&lt;<i>oldurl</i>&gt;]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Changes the URL for the remote &lt;<i>name</i>&gt;. If &lt;<i>oldurl</i>&gt; is specified, only that specific URL is changed if multiple exist.<br><br><b><b>set-url --push</b> &lt;<i>name</i>&gt; &lt;<i>newurl</i>&gt; [&lt;<i>oldurl</i>&gt;]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Changes the push URL for the remote &lt;<i>name</i>&gt;.<br><br><b><b>get-url</b> &lt;<i>name</i>&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Retrieves the fetch URL for the remote &lt;<i>name</i>&gt;.<br><br><b><b>get-url --push</b> &lt;<i>name</i>&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Retrieves the push URL for the remote &lt;<i>name</i>&gt;.<br><br><b><b>get-url --all</b> &lt;<i>name</i>&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Retrieves all URLs (fetch and push) for the remote &lt;<i>name</i>&gt;.<br><br><b><b>show</b> &lt;<i>name</i>&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays detailed information about the remote &lt;<i>name</i>&gt;.<br><br><b><b>show -n</b> &lt;<i>name</i>&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays information about the remote &lt;<i>name</i>&gt; without fetching remote heads or tags.<br><br><b><b>prune</b> &lt;<i>name</i>&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Deletes all stale remote-tracking branches for &lt;<i>name</i>&gt; (i.e., branches that no longer exist on the remote).<br><br><b><b>prune -n</b> | <b>--dry-run</b> &lt;<i>name</i>&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows which remote-tracking branches would be removed by <b>prune</b>, without actually removing them.<br><br><b><b>update</b> [&lt;<i>group</i>&gt; | <b>--all</b>]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Fetches updates for a specified remote group or all remotes.<br><br><b><b>update -p</b> | <b>--prune</b> [&lt;<i>group</i>&gt; | <b>--all</b>]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Fetches updates and prunes stale remote-tracking branches for a specified remote group or all remotes.<br><br>


title: DESCRIPTION
content:
<i>git-remote</i> is a Git porcelain command used to manage the set of remote repositories whose branches you track. Remotes are essentially aliases for repository URLs, making it easier to interact with other repositories. This command allows you to add new remotes, rename existing ones, remove them, change their URLs, and inspect their details. It's fundamental for collaborative workflows, enabling you to fetch, push, and pull changes from designated remote locations like GitHub, GitLab, or an internal server. It integrates closely with other <i>Git</i> commands like <i>fetch</i>, <i>push</i>, and <i>pull</i>. Understanding how to manage remotes is crucial for effective version control in a distributed environment, providing the necessary framework to interact with other contributors' work.


title: CAVEATS
content:
Adding a remote with <b>git remote add</b> only registers the remote; use <b>git fetch &lt;name&gt;</b> or <b>git pull</b> to retrieve its content. Removing a remote with <b>git remote remove</b> does not automatically delete corresponding local remote-tracking branches; these must be cleaned up manually (e.g., using <b>git remote prune</b> or <b>git branch -d -r</b>). Be cautious with the <b>--mirror</b> option as it significantly changes how Git interacts with the remote, making the local repository a bare clone.


title: REMOTE-TRACKING BRANCHES
content:
<i>git remote</i> implicitly manages "remote-tracking branches" (e.g., <i>origin/main</i>). These are local references to the state of branches on a remote repository. They serve as a snapshot of the remote's state at the last <b>git fetch</b> or <b>git pull</b> operation, allowing you to examine remote changes without merging them into your local branches.


title: FETCH VS. PUSH URLS
content:
A remote can have separate URLs configured for fetching from it and pushing to it. By default, both operations use the same URL. However, <b>git remote set-url --push</b> allows configuring distinct URLs, which is useful in advanced scenarios such as fetching from a public mirror but pushing to a private, authenticated repository, or interacting with a CI/CD system.


title: HISTORY
content:
<i>git-remote</i> has been a fundamental part of Git's architecture since its early days, essential for its distributed version control model. Its subcommands have been refined and extended over time to provide more granular control over remote interactions, adapting to complex collaborative workflows and diverse repository hosting environments. It remains a core utility for managing remote connections within a <i>Git</i> repository.


title: SYNOPSIS
content:
git remote add <I>name</I> ext::<I>command</I> [<I>arguments</I>]<br>git clone ext::<I>command</I> [<I>arguments</I>] [<I>directory</I>]


title: PARAMETERS
content:
<b>ext::</b><br>&nbsp;&nbsp;&nbsp;&nbsp;The literal prefix that signals Git to use the <b>git-remote-ext</b> helper for the subsequent part of the URL.<br><br><b><I>command</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The path to an executable program or script that implements the Git remote helper protocol. This can be a command found in the system's <I>PATH</I> (e.g., <I>my-custom-git-helper</I>) or an absolute path (e.g., <I>/usr/local/bin/my-helper</I>). If an absolute path is used, it often requires an additional slash after <I>ext::</I>, e.g., <I>ext:///path/to/command</I>.<br><br><b><I>arguments</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Optional, space-separated arguments to be passed directly to the <I>command</I>. These arguments are URL-decoded by <b>git-remote-ext</b> before being passed to the external helper.<br><br>


title: DESCRIPTION
content:
<b>git-remote-ext</b> is a specialized Git remote helper that enables Git to interact with repositories via arbitrary external programs. Instead of relying on built-in protocols like HTTP or SSH, this helper acts as a bridge, delegating all remote operations (like fetching, pushing, or listing references) to an executable specified in the remote URL. When a Git remote URL is prefixed with <I>ext::</I>, Git invokes <b>git-remote-ext</b>, which then executes the designated external command. This external command is expected to adhere to Git's remote helper protocol, communicating with Git via standard input and output.<br><br>This mechanism provides unparalleled flexibility, allowing Git to integrate with custom storage solutions, proprietary version control systems, or non-standard network protocols by simply writing a wrapper script or binary that conforms to the protocol. It is particularly useful for extending Git's reach into environments not natively supported, offering a powerful way to customize how Git interacts with various backends.


title: CAVEATS
content:
<b>Security Risk:</b> Using <b>git-remote-ext</b> with untrusted sources or specifying arbitrary commands can pose a significant security risk, as it executes external programs. Always ensure the specified <I>command</I> is trustworthy and secure.<br><b>Protocol Implementation:</b> The external <I>command</I> must correctly implement the Git remote helper protocol (as detailed in <I>git-remote-helpers(7)</I>) to function properly. Incorrect implementation will lead to errors or unexpected behavior.<br><b>Performance:</b> The performance of remote operations depends entirely on the efficiency and responsiveness of the external helper program and the underlying transport or system it interacts with.


title: THE GIT REMOTE HELPER PROTOCOL
content:
The core functionality of <b>git-remote-ext</b> relies on the external program implementing a specific communication protocol. This protocol defines how Git sends commands (like <I>capabilities</I>, <I>list</I>, <I>fetch</I>, <I>push</I>) to the helper via standard input and how the helper responds via standard output. A thorough understanding of this protocol, as documented in <I>git-remote-helpers(7)</I>, is essential for writing effective external helpers.


title: USAGE CONTEXT
content:
Unlike most Git commands, <b>git-remote-ext</b> is not invoked directly from the command line. Instead, it is implicitly used by Git when a remote URL starts with the <I>ext::</I> prefix. This makes it a powerful background mechanism for custom remote integrations.


title: HISTORY
content:
The concept of remote helpers is a foundational aspect of Git's extensibility model, designed to allow integration with various protocols and storage backends beyond its native capabilities. <b>git-remote-ext</b> specifically provides a generic mechanism to plug in *any* executable that conforms to the remote helper protocol. This flexibility allows users to integrate Git with highly customized systems, proprietary solutions, or niche network environments without requiring Git's core codebase to support them directly. It was introduced to maximize the adaptability and reach of Git's remote operations.


title: SYNOPSIS
content:
<b>git-remote-fd</b> <i>&lt;remote-name&gt;</i> <b>fd::</b><i>&lt;read-fd&gt;</i><b>::</b><i>&lt;write-fd&gt;</i>


title: PARAMETERS
content:
<b><remote-name></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The symbolic name given to the remote repository. This argument is passed by Git to all remote helpers.<br><br><b>fd::<read-fd>::<write-fd></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The special URL format understood by this helper. It specifies the file descriptors to use for communication.<br><br><b><read-fd></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The integer file descriptor number from which Git will read data from the remote.<br><br><b><write-fd></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The integer file descriptor number to which Git will write data destined for the remote.<br><br>


title: DESCRIPTION
content:
The <i>git-remote-fd</i> command serves as a specialized Git remote helper. Instead of communicating with a remote repository via traditional network protocols like HTTP or SSH, it operates entirely through pre-established Unix file descriptors. This mechanism allows a parent process to provide a child Git process with explicit file descriptors for reading from and writing to a remote. <br><br>This unique approach is invaluable for scripting, sandboxing, and integrating Git within other applications. It enables custom communication channels, facilitating scenarios where standard network access is restricted or where fine-grained control over Git's I/O is required. Developers can use <i>git-remote-fd</i> to build bespoke Git interfaces, manage operations in isolated environments, or pipe Git traffic through complex pipelines. It provides a low-level, highly flexible, and powerful method for orchestrating Git remote interactions programmatically.


title: CAVEATS
content:
<i>git-remote-fd</i> is a low-level helper intended primarily for developers and advanced scripting, not for direct end-user interaction. <br>It requires careful management of file descriptors by the invoking process. <br>Error handling can be complex, as issues might stem from the file descriptor setup rather than Git's internal operations. <br>Security considerations are paramount when exposing file descriptors to a child process, ensuring that only necessary permissions are granted.


title: HOW IT WORKS (PROTOCOL)
content:
The <i>git-remote-fd</i> helper communicates using the standard Git remote helper protocol. This protocol involves a series of commands (e.g., <i>capabilities</i>, <i>list</i>, <i>fetch</i>, <i>push</i>) exchanged line by line over the specified file descriptors. The parent process setting up the file descriptors is responsible for routing this protocol traffic to and from the actual remote source, effectively acting as a proxy or translator for Git's remote operations.


title: CONCEPTUAL USAGE
content:
A common use case involves a parent application spawning a Git command (like <i>git fetch</i>) that uses a URL like <b>fd::3::4</b>. The parent process would then map file descriptor 3 to its own read stream and file descriptor 4 to its own write stream, allowing it to mediate all communication between the Git client and the remote. This is particularly useful for implementing custom authentication, logging, or proxying behaviors directly within the application.


title: HISTORY
content:
While the exact initial commit for <i>git-remote-fd</i> is deep within Git's history, the concept of remote helpers and the ability to communicate over file descriptors have been fundamental parts of Git's design since its early days. This helper provides a core, flexible interface that has been stable and widely used for integrating Git into various systems and scripting environments, predating more recent remote protocol evolutions like `git-protocol-v2` but remaining relevant for its specific use case.


title: SYNOPSIS
content:
<code>git-remote-testgit &lt;command&gt; &lt;repository&gt;</code><br><i>Note: This command is invoked internally by Git during tests, not directly by users.</i>


title: PARAMETERS
content:
<b>capabilities</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Advertises the capabilities supported by this mock remote (e.g., fetch, push, options).<br><br><b>list</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Lists the references (branches, tags) available in the mock remote repository.<br><br><b>fetch &lt;commit-id&gt; &lt;object-id&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Simulates fetching objects from the mock remote, typically for testing fetch behavior.<br><br><b>push</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Handles simulated push operations, accepting or rejecting pushed refs based on test logic.<br><br><b>option &lt;key&gt; &lt;value&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Allows the main Git process to set specific options for the mock remote helper.<br><br><b>connect &lt;service&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Establishes a simulated connection to a specific Git service (e.g., 'git-upload-pack' for fetching, 'git-receive-pack' for pushing).<br><br><b>&lt;repository&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;The URL-like string representing the mock remote repository being tested. Its content is typically ignored or used for test-specific logic by <code>git-remote-testgit</code>.<br><br>


title: DESCRIPTION
content:
<code>git-remote-testgit</code> is an internal utility within the Git project, primarily designed to act as a mock remote helper for automated testing of Git's remote protocols. It is <i>not</i> intended for direct use by end-users. When Git needs to interact with a remote repository, it can invoke external "remote helper" programs (like <code>git-remote-http</code> or <code>git-remote-ssh</code>). <code>git-remote-testgit</code> simulates such a helper, allowing Git's test suite to verify correct behavior of commands like <code>git clone</code>, <code>git fetch</code>, and <code>git push</code> against a controlled, predictable, and artificial remote environment. <br><br>This utility helps developers test various scenarios, including error conditions, specific ref advertisements, and different remote capabilities, without requiring a live network connection or a real Git server. Its behavior is entirely driven by the test scripts that invoke it, making it a crucial component for ensuring the robustness and correctness of Git's network-related operations. It communicates with the main Git process via standard input/output, adhering to the well-defined Git remote helper protocol.


title: CAVEATS
content:
<b>Not for General Use</b>: <code>git-remote-testgit</code> is an internal testing tool and should <i>never</i> be invoked directly by users for real Git operations. Its behavior is unpredictable outside the controlled test environment.<br><b>Ephemeral and Test-Specific</b>: The "repository" it simulates is entirely artificial and exists only for the duration of a test run. It does not persist any data.<br><b>No Public Documentation</b>: As an internal utility, it does not have a dedicated man page or public documentation, requiring an understanding of Git's remote helper protocol to comprehend its function.


title: ROLE IN GIT'S TESTING INFRASTRUCTURE
content:
This command is crucial for Git's continuous integration and development. It enables developers to implement unit and integration tests for remote interactions, ensuring that changes to Git's core logic or remote protocols do not introduce regressions when communicating with various types of Git servers.


title: PROTOCOL COMMUNICATION
content:
Like all Git remote helpers, <code>git-remote-testgit</code> communicates with the main Git process using a simple, text-based protocol over standard input and output. Commands are sent on <code>stdin</code>, and responses (e.g., lists of refs, capability advertisements) are printed to <code>stdout</code>. Error messages are typically sent to <code>stderr</code>.


title: HISTORY
content:
<code>git-remote-testgit</code> has evolved as an integral part of Git's comprehensive test suite. Its development history is closely tied to the improvements and expansions of Git's remote protocol and its internal testing framework. It was introduced to provide a robust, isolated, and scriptable environment for verifying the correctness and resilience of Git's network operations, reducing reliance on external services during automated testing. It has been refined over time to support new remote capabilities and test more complex scenarios.


title: PARAMETERS
content:
<b><i><B><old-branch></B></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The <i>current</i> name of the branch you wish to rename. If omitted, the command renames the currently checked-out branch (HEAD).<br><br><b><i><B><new-branch></B></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The <i>desired new</i> name for the branch.<br><br><b><b>-f</b>, <b>--force</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;If the <i>new-branch</i> name already exists locally, this option forces the rename by deleting the existing branch and then performing the rename. This is equivalent to using <i><B>git branch -M</B></i> for the local rename part.<br><br><b><b>--local-only</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;If provided, the command will only rename the branch locally and will not attempt to update or delete branches on the remote repository. This bypasses any remote push or delete operations typically associated with a full rename workflow.<br><br>


title: DESCRIPTION
content:
The command <i><B>git-rename-branch</B></i> is not a native Git subcommand but represents a common operation or a user-created alias/script to streamline the process of renaming a Git branch. <br><br>Typically, renaming a Git branch involves several manual steps:<br>1.  Renaming the local branch using <i><B>git branch -m <old-name> <new-name></B></i> (or <i><B>git branch -m <new-name></B></i> for the current branch).<br>2.  Pushing the newly named branch to the remote repository (e.g., <i><B>git push origin <new-name></B></i>).<br>3.  (Optional but recommended) Deleting the old branch name from the remote repository (e.g., <i><B>git push origin --delete <old-name></B></i>).<br>4.  (Optional) Resetting the upstream tracking for the new branch (e.g., <i><B>git push origin -u <new-name></B></i>).<br><br>A hypothetical or user-defined <i><B>git-rename-branch</B></i> command aims to encapsulate these steps into a single, convenient execution, handling both local and remote aspects of the rename operation. Its primary purpose is to simplify workflow and reduce the chance of manual errors.


title: CAVEATS
content:
The command <i><B>git-rename-branch</B></i> is <b>not</b> a standard, built-in Git command. It commonly refers to a user-defined alias, a custom shell script, or a conceptual wrapper over the fundamental Git commands (<i><B>git branch -m</B></i>, <i><B>git push</B></i>).<br><br>Its exact behavior (e.g., whether it handles remote operations, force options, etc.) depends entirely on how it's implemented by the user or system administrator.<br><br>Renaming a branch that others are actively working on requires coordination, as their tracking branches and local copies will become outdated. They will need to adjust their setup (e.g., <i><B>git branch --unset-upstream</B></i> on old local branch, <i><B>git branch -m <new-name></B></i>, <i><B>git fetch origin</B></i>, and then <i><B>git branch -u origin/<new-name></B></i> or simply deleting and re-checking out the new branch).


title: MANUAL WORKFLOW FOR RENAMING A BRANCH
content:
If a <i><B>git-rename-branch</B></i> command is not available or preferred, the branch can be renamed manually using the following steps:<br><br>1.  <b>Rename your local branch:</b><br>    If you're on the branch you want to rename:<br>    <i><B>git branch -m <new-name></B></i><br>    If you're on a different branch:<br>    <i><B>git branch -m <old-name> <new-name></B></i><br><br>2.  <b>Push the new branch to remote:</b><br>    <i><B>git push origin -u <new-name></B></i><br><br>3.  <b>Delete the old branch from remote:</b><br>    <i><B>git push origin --delete <old-name></B></i><br><br>4.  <b>Inform collaborators (critical for shared branches):</b><br>    Let other team members know about the branch rename so they can update their local repositories and tracking branches accordingly. They might need to fetch, then delete their local old branch, and checkout/track the new one.


title: CREATING A CUSTOM ALIAS FOR RENAMING
content:
Users can create a Git alias to achieve similar functionality to a dedicated <i><B>git-rename-branch</B></i> command. For example, to rename a local branch and update its upstream:<br><i><B>git config --global alias.rename-branch '!f() { git branch -m "$1" "$2" && git push origin -u "$2" && git push origin --delete "$1"; }; f'</B></i><br><br>This alias would then be invoked as <i><B>git rename-branch <old-name> <new-name></B></i>.


title: HISTORY
content:
The need for a streamlined branch renaming process emerged as Git users frequently encountered the multi-step nature of renaming branches, especially when remote repositories were involved. While <i><B>git branch -m</B></i> handles the local aspect, updating the remote requires additional <i><B>git push</B></i> commands. This led to many users creating personal aliases or simple shell scripts (often named 'git-rename-branch', 'git-mv-branch', or 'git-move-branch') to automate these repetitive steps, improving efficiency and reducing potential errors during a rename operation. The concept of <i><B>git-rename-branch</B></i> thus evolved out of practical user demand rather than being a core Git development.


title: SYNOPSIS
content:
<code>git-rename-remote <I>old_name</I> <I>new_name</I></code><br><br><i>(Note: This typically wraps the standard Git command: <code>git remote rename <I>old_name</I> <I>new_name</I></code>)</i>


title: PARAMETERS
content:
<b><I>old_name</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The current name of the remote to be renamed.<br><br><b><I>new_name</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The desired new name for the remote. This name must not already exist as a remote.<br><br>


title: DESCRIPTION
content:
<code>git-rename-remote</code> is not a standard, official Git command. It most likely refers to the common action of renaming an existing remote repository's identifier in a local Git repository, which is officially performed using the command <b><code>git remote rename</code></b>. This command allows you to change the name by which you refer to a specific remote repository. For instance, if you initially added a remote named 'origin' and later decide to call it 'upstream', this functionality is used. Renaming a remote updates the local repository's configuration, including any local branches that were configured to track branches from the old remote name. This is useful for organization, correcting typos, or adapting to changes in project conventions.


title: CAVEATS
content:
The command <code>git-rename-remote</code> is not a built-in Git command and might refer to a custom script or an alias. The actual functionality is provided by <b><code>git remote rename</code></b>.<br>Renaming a remote updates the <code>.git/config</code> file. Any local branches that were configured to track branches from the <code>old_name</code> remote will automatically be updated to track from the <code>new_name</code> remote. However, this only affects your local repository; it does not change the remote repository itself or anyone else's local configuration. Ensure <code>new_name</code> does not conflict with an existing remote name.


title: IMPLEMENTATION NOTES
content:
A script named <code>git-rename-remote</code> would likely be implemented as a simple shell script that executes <code>git remote rename "$1" "$2"</code>, possibly with additional error handling or verbose output. Such scripts are commonly placed in a directory listed in the user's <code>PATH</code> environment variable, allowing them to be invoked like regular Git subcommands.


title: CONFIGURATION UPDATE
content:
When a remote is renamed using <code><b>git remote rename</b></code>, Git automatically updates the <code>remote."old_name"</code> section in the <code>.git/config</code> file to <code>remote."new_name"</code>. It also updates the <code>branch.<I>branch_name</I>.remote</code> setting for any tracking branches to point to the new remote name, ensuring seamless continued operation.


title: HISTORY
content:
The ability to rename Git remotes has been a core part of Git's remote management features since its early versions. The <b><code>git remote rename</code></b> subcommand was introduced to provide a straightforward way to manage remote aliases, ensuring flexibility in repository organization. While <code>git-rename-remote</code> itself is not part of Git's official history, the underlying functionality it would provide has been stable and consistently available.


title: PARAMETERS
content:
<b><I>OLD_TAG_NAME</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The name of the existing tag that you wish to rename.<br><br><b><I>NEW_TAG_NAME</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The desired new name for the tag.<br><br><b><b>-f</b>, <b>--force</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;If the <I>NEW_TAG_NAME</I> already exists locally, force Git to delete it and create the new tag. This option typically applies to local tag creation.<br><br><b><b>-l</b>, <b>--local-only</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Perform the tag rename only in the local repository. Do not interact with the remote repository (i.e., do not delete the old tag from remote or push the new tag).<br><br>


title: DESCRIPTION
content:
The <b>git-rename-tag</b> command is a conceptual helper script or alias commonly used to rename an existing Git tag. Git itself does not provide a direct 'rename tag' command. Instead, renaming a tag involves a sequence of operations: deleting the old tag locally, creating a new tag pointing to the same commit as the old one, deleting the old tag from the remote repository, and finally pushing the new tag to the remote.<br><br>This utility streamlines the process, ensuring both local and remote repositories reflect the name change, making it easier to manage release versions or milestones without performing multiple manual Git commands.


title: CAVEATS
content:
This command is <i>not</i> a built-in Git command. It is a commonly implemented shell script or Git alias created by users to simplify the process of renaming tags. Its exact behavior and available options might vary depending on its specific implementation.<br><br>Renaming tags that have already been published can be disruptive to other collaborators as their local repositories might still reference the old tag name. Communication with team members is highly recommended before renaming shared tags to avoid confusion or inconsistencies.


title: TYPICAL WORKFLOW
content:
A typical `git-rename-tag` script performs the following sequence of operations:<br>1. <I>Verification:</I> Checks if <I>OLD_TAG_NAME</I> exists locally and <I>NEW_TAG_NAME</I> does not (unless forced by <b>-f</b>).<br>2. <I>Create New Local Tag:</I> Executes `git tag <I>NEW_TAG_NAME</I> <I>OLD_TAG_NAME</I>` to create the new tag pointing to the same commit.<br>3. <I>Delete Old Local Tag:</I> Runs `git tag -d <I>OLD_TAG_NAME</I>` to remove the old tag locally.<br>4. <I>Push New Tag to Remote:</I> Performs `git push <I>origin</I> <I>NEW_TAG_NAME</I>` to publish the new tag.<br>5. <I>Delete Old Tag from Remote:</I> Executes `git push <I>origin</I> :refs/tags/<I>OLD_TAG_NAME</I>` to remove the old tag from the remote repository.


title: HISTORY
content:
The need for a `git-rename-tag` utility arose from Git's design, where tags are essentially immutable pointers to commits and are not designed to be directly renamed. Users frequently desire a straightforward way to correct typographical errors or standardize naming conventions for tags. As a result, various community-contributed scripts and aliases emerged to automate the underlying `git tag -d`, `git push :refs/tags/old_tag`, `git tag new_tag`, and `git push new_tag` operations, standardizing this common workflow for managing Git tags.


title: SYNOPSIS
content:
<b>git repack</b> [-a | -d | -f | -l | -n | -q | -b | --window=&lt;n&gt; | --depth=&lt;n&gt; | --unpack-unreachable=&lt;n&gt;]


title: PARAMETERS
content:
<b>-a, --all</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Repack all objects, combining existing packfiles into a new single one.<br><br><b>-d, --no-reuse-object</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Delete unreachable packfiles and loose objects after packing.<br><br><b>-f, --force</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Force repack even if the repository is already optimized.<br><br><b>-l, --local</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Do not reuse existing pack objects; implies --all.<br><br><b>-n, --dry-run</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Do not write a packfile, just report what would happen.<br><br><b>-q, --quiet</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Be quiet; suppress progress output.<br><br><b>-b, --write-midx</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Write a multi-pack index (MIDX) file for better performance.<br><br><b>--window=&lt;n&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set the maximum number of objects to consider for delta compression. Higher values improve compression but use more resources.<br><br><b>--depth=&lt;n&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set the maximum delta recursion depth. Higher values improve compression but use more resources.<br><br><b>--unpack-unreachable=&lt;n&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Unpack objects from packfiles that are unreachable for at least &lt;n&gt; days, allowing them to be pruned.<br><br>


title: DESCRIPTION
content:
<i>git-repack</i> is a low-level command used to optimize a Git repository's storage. It consolidates loose objects (individual files representing Git objects like commits, trees, or blobs) into efficient, compressed "packfiles." Packfiles improve performance by reducing the number of files on disk and enabling delta compression, which stores objects as differences from other objects.<br><br>This process significantly reduces disk space usage and speeds up Git operations such as cloning and object lookup. While often invoked automatically by <i>git gc</i> (garbage collection), <i>git-repack</i> can be run manually for fine-grained control over the packing process, allowing users to aggressively compress or rearrange objects within the repository to further optimize performance and disk footprint.


title: CAVEATS
content:
Can be computationally intensive and time-consuming for very large repositories.<br>Typically not needed manually, as <i>git gc</i> handles repacking automatically as part of its garbage collection process.<br>Aggressive compression settings (e.g., very high --window or --depth) significantly increase processing time and memory usage.


title: PACKFILE MECHANICS
content:
Git stores its objects (blobs, trees, commits, tags) efficiently in packfiles. A packfile is a single, often highly compressed file that contains multiple Git objects. Objects are typically stored as deltas (differences) against other objects, minimizing space. Each packfile has an accompanying index (<i>.idx</i>) file that allows Git to quickly locate any object within the pack. This structure is key to Git's performance and low disk usage for large repositories.


title: TYPICAL USAGE SCENARIOS
content:
Although <i>git gc</i> usually handles repacking, manual <i>git repack</i> can be beneficial in specific scenarios:<br><ul><li>After a large import or a series of operations that generated many loose objects.</li><li>When disk space is at a premium and a more aggressive optimization is desired than what <i>git gc</i> might provide by default.</li><li>For performance tuning, such as before pushing a repository to a server, ensuring the transferred pack is optimally compressed.</li><li>When experimenting with compression parameters like <i>--window</i> and <i>--depth</i> to find an optimal balance between compression and packing time.</li></ul>


title: HISTORY
content:
Git initially stored all objects as individual loose files. As repositories grew, this became inefficient in terms of disk space and performance. To address this, Git introduced "packfiles" to store multiple objects in a single, compressed file, leveraging delta compression. <i>git-repack</i> was developed as the primary utility to create and manage these packfiles, consolidating loose objects and optimizing existing packs. Its evolution is fundamental to Git's efficient storage and performance over time.


title: DESCRIPTION
content:
The <i>git-repl</i> command provides an interactive Read-Eval-Print Loop (REPL) environment specifically designed for Git operations. Instead of repeatedly typing `git` before each command, users can enter Git subcommands directly within the REPL prompt, such as `status`, `add .`, or `commit -m "Message"`. This tool simplifies the process of executing a series of Git commands, making it highly convenient for rapid prototyping, exploring Git's functionalities, or performing complex workflows interactively. It acts as a wrapper, automatically prepending `git` to every command entered and executing it in a subshell, then displaying the output back to the user. This interactive approach enhances productivity and provides a more fluid experience for Git users, especially when debugging, experimenting, or conducting repetitive tasks.


title: CAVEATS
content:
This command is not a part of the official Git distribution and requires separate installation. Its functionality relies on the `git` executable being available in the system's PATH. While it streamlines Git command execution, complex shell features or interactions with non-Git commands directly within a single REPL line might behave differently than in a standard shell. It is primarily designed for Git subcommands.


title: INSTALLATION
content:
As <i>git-repl</i> is not bundled with Git, it usually needs to be installed separately. This typically involves cloning its repository and placing the <i>git-repl</i> script into a directory included in your system's PATH, such as `/usr/local/bin` or `~/bin`. For example, you might use `pip install git-repl` if a Python package is available, or manually download the script.


title: INTERACTIVE USAGE
content:
Once started with <i>git-repl</i>, you can type any Git subcommand directly (e.g., `status`, `add .`, `commit -m "Initial commit"`). To exit the REPL, you can usually type `exit`, `quit`, or press <b>Ctrl+D</b> (EOF).


title: HISTORY
content:
The <i>git-repl</i> tool is an independent, community-driven project, typically implemented as a simple Python script. It emerged from the desire for a more fluid and interactive experience when working with Git, allowing users to rapidly execute multiple Git commands without the repetitive `git` prefix. Its development reflects a common need within the developer community for convenience and efficiency in Git command-line usage, rather than a formal specification or a long-standing project history.


title: SYNOPSIS
content:
<b>git replace</b> [<i>-f</i>] <i>&lt;object&gt; &lt;replacement&gt;</i><br><b>git replace</b> <i>-d &lt;object&gt;</i><br><b>git replace</b> <i>--list</i> [<i>&lt;pattern&gt;</i>]


title: PARAMETERS
content:
<b><i>&lt;object&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The SHA-1 hash or symbolic name of the Git object that you want to replace.<br><br><b><i>&lt;replacement&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The SHA-1 hash or symbolic name of the Git object that will take the place of the original <i>&lt;object&gt;</i>.<br><br><b><i>-f</i>, <i>--force</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;If a replacement for the specified <i>&lt;object&gt;</i> already exists, force Git to create a new replacement, overwriting the old one.<br><br><b><i>-d</i>, <i>--delete</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Delete an existing replacement for the specified <i>&lt;object&gt;</i>. This restores the visibility of the original object.<br><br><b><i>--list</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;List all existing replacements. If a <i>&lt;pattern&gt;</i> is provided, it filters the list to show only replacements whose original object matches the pattern.<br><br><b><i>&lt;pattern&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;An optional regular expression pattern used with <i>--list</i> to filter the displayed replacements based on the SHA-1 of the original object.<br><br>


title: DESCRIPTION
content:
The <b>git replace</b> command allows users to transparently substitute one Git object (commit, tree, blob, or tag) with another. This powerful feature is primarily used for <i>non-destructively</i> correcting history, testing changes, or temporarily masking problematic objects without rewriting the original Git history. When a replacement is created, Git operations that traverse the object database (such as <b>git log</b>, <b>git blame</b>, or <b>git show</b>) will see the replacement object instead of the original one. The original object remains in the repository, and the replacement is stored as a special reference under <b>refs/replace/</b>.<br><br>This mechanism is particularly useful for fixing issues like bad commits that may contain sensitive data or large files, without forcing a history rewrite on shared repositories, as the replacements are local by default. However, it's crucial to understand that replacements are not automatically propagated by standard <b>git push</b> or <b>git fetch</b> operations, requiring explicit handling for sharing.


title: CAVEATS
content:
Replacements are stored as <i>loose references</i> under <b>refs/replace/</b> and are not part of Git's packed objects, which can slightly affect performance for very large numbers of replacements.<br><br>They are <b>not</b> automatically transferred during typical <b>git push</b> or <b>git fetch</b> operations. To share replacements, you must explicitly push them using commands like <b>git push --all</b> or <b>git push --mirror</b>, which includes `refs/replace/` references.<br><br>Replacements only affect <i>object traversal</i>. The original objects remain in the repository and are still accessible directly by their SHA-1. While useful for temporary fixes or local testing, replacements do not permanently alter the commit history. To make changes permanent and remove the original objects, tools like <b>git filter-repo</b> or <b>git filter-branch</b> are typically used after confirming the replacement.


title: <B>STORAGE MECHANISM</B>
content:
Replacements are stored as ordinary Git references in a special namespace: <b>refs/replace/<i>&lt;SHA-1-of-original-object&gt;</i></b>. The content of this reference is the SHA-1 of the replacement object. This decentralized storage allows for easy creation and deletion of replacements.


title: <B>ENVIRONMENT VARIABLE</B>
content:
The base directory for replacement references can be overridden by setting the <b>GIT_REPLACE_REF_BASE</b> environment variable. By default, it is <b>refs/replace/</b>. This can be useful for advanced or custom Git setups.


title: HISTORY
content:
The <b>git replace</b> functionality was introduced early in Git's development to provide a robust way to modify how Git traverses the object graph without resorting to destructive history rewriting. This addresses scenarios where a user might want to correct a problematic commit (e.g., one containing sensitive information or an erroneously large file) without forcing a history rewrite for all collaborators. It acts as a lightweight, non-destructive overlay, offering a flexible alternative to more aggressive history-rewriting tools for certain use cases. Its core mechanism of using <b>refs/replace/</b> has remained a stable and integral part of Git.


title: PARAMETERS
content:
<b><i>&lt;start&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The commit-ish (e.g., commit ID, branch name, or tag) that defines the common ancestor or starting point of the changes. This commit should ideally be present in the recipient's repository.<br><br><b><i>&lt;url&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The URL of the Git repository that contains the changes you are requesting to be pulled from. This URL must be accessible to the recipient.<br><br><b><i>[&lt;branch&gt;]</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Optional. The name of the branch in the specified <i>&lt;url&gt;</i> from which the changes should be pulled. If omitted, the command defaults to the <i>HEAD</i> of the remote repository.<br><br>


title: DESCRIPTION
content:
The <b>git-request-pull</b> command generates a summary of changes suitable for emailing to a project maintainer, instructing them on how to pull contributions from a specified repository. It calculates the diff between a <i>start</i> commit (typically one already known to the maintainer) and the <i>HEAD</i> of a <i>branch</i> within a given <i>URL</i>.<br><br>The output includes the exact <b>git pull</b> command for the maintainer to use, a concise shortlog of the changes, and a diffstat. This functionality is crucial for facilitating contributions in a distributed, email-centric workflow, allowing contributors to easily package and present their changes for integration without requiring the maintainer to manually inspect diffs or fetch the entire remote repository beforehand.


title: CAVEATS
content:
<b>git-request-pull</b> produces an informational summary for an email-based workflow, not an interactive pull request mechanism found on web platforms like GitHub or GitLab. It assumes the specified <i>&lt;url&gt;</i> is publicly accessible or accessible to the recipient for a successful pull. The <i>&lt;start&gt;</i> commit must be an ancestor of, or reachable from, the specified <i>&lt;branch&gt;</i> (or <i>HEAD</i> if <i>&lt;branch&gt;</i> is omitted) in the remote repository.


title: OUTPUT FORMAT
content:
The command's output is structured to provide all relevant information for a maintainer to perform a pull operation. It typically includes:<br><br> - The exact <b>git pull</b> command the recipient can execute.<br> - A summary of commits (similar to <b>git shortlog</b>).<br> - A statistical summary of file changes (diffstat).<br><br>This format is designed to be easily copy-pasted into an email.


title: HISTORY
content:
The <b>git-request-pull</b> command reflects Git's origins as a decentralized version control system primarily designed for email-based patch exchange and integration. It predates and serves a different purpose than modern web-based 'pull request' interfaces. It automates the generation of the necessary information (the <b>git pull</b> command, shortlog, and diffstat) for a maintainer to manually integrate changes sent via email. While still functional, its direct usage for submitting contributions has largely been overshadowed by the convenience of integrated web platforms.


title: SYNOPSIS
content:
<b>git rerere</b> [clear|forget <pathspec>...]<br><b>git rerere</b> [diff|status|remaining]<br><b>git rerere</b> gc


title: PARAMETERS
content:
<b>clear</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Clears the conflict resolution cache, effectively forgetting all recorded resolutions.<br><br><b>forget <pathspec>...</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Forgets the recorded resolution for specific paths. Useful if a previous resolution is no longer desired or correct for a particular file.<br><br><b>diff</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows the difference between the conflicted state and the recorded resolution for the current conflict.<br><br><b>status</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows paths that have recorded resolutions applied, or are awaiting recording.<br><br><b>remaining</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Lists paths that still have unresolved conflicts after attempting to apply recorded resolutions.<br><br><b>gc</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Performs garbage collection on the rerere cache, removing old and unreachable resolution records to save disk space.<br><br>


title: DESCRIPTION
content:
<i>git-rerere</i> (re-use recorded resolution) is a powerful Git feature designed to remember how merge conflicts were resolved, and then automatically apply those resolutions if the same conflict arises again. When <i>rerere.enabled</i> is configured to true (e.g., via <code>git config --global rerere.enabled true</code>), Git records the pre-image and post-image of conflicted files in the <code>.git/rr-cache/</code> directory whenever you manually resolve a conflict and stage the result. If Git encounters a conflict that matches a previously recorded resolution, it will automatically apply the stored resolution, saving significant time and effort. This is especially useful in workflows involving frequent rebasing, merging diverging branches, or cherry-picking, where the same conflicts might re-appear multiple times. It helps maintain consistency in conflict resolution and reduces manual intervention, streamlining repetitive integration tasks. While it doesn't prevent conflicts, it intelligently automates their resolution based on past experience.


title: CAVEATS
content:
While highly beneficial, <i>git-rerere</i> is not without its considerations. It consumes disk space to store conflict resolutions, though <code>git rerere gc</code> can help manage this. More importantly, it relies on the context of the conflict remaining consistent; if the surrounding code or the nature of the conflict changes significantly, an automatically applied resolution might be incorrect, requiring manual override. It's crucial to review the outcome of automatic resolutions, especially in complex scenarios. It only automates resolution based on prior experience; it does not prevent conflicts from occurring.


title: CONFIGURATION
content:
The behavior of <i>git-rerere</i> is primarily controlled via Git configuration variables. The most important is <code>rerere.enabled</code>, which when set to <code>true</code> (e.g., <code>git config --global rerere.enabled true</code>), enables automatic recording and reuse of resolutions. Other relevant configurations include <code>rerere.autoupdate</code> (automatically stage the conflict resolution after applying) and <code>rerere.autoreuse</code> (automatically reuse recorded resolutions if found).


title: AUTOMATIC OPERATION
content:
When <i>rerere.enabled</i> is true, <i>git-rerere</i> operates largely in the background. After you manually resolve a conflict (e.g., during a merge or rebase) and stage the resolved file (<code>git add &lt;file&gt;</code>), Git automatically records the resolution. If the same conflict later reappears, Git will attempt to automatically apply the recorded resolution, marking the file as resolved in the index. You can then continue the operation (e.g., <code>git commit</code> or <code>git rebase --continue</code>).


title: HISTORY
content:
The <i>rerere</i> functionality was introduced into Git around version 1.5.1 in 2007. It originated from a series of discussions and patches by Junio C Hamano, the long-time Git maintainer, and others. The primary motivation was to address the common pain point of repeatedly resolving the same merge conflicts, especially when merging a topic branch multiple times into a main branch or during complex rebase operations. Initially, it might have existed as separate scripts or configurations, but it was soon integrated as a core Git feature, enhancing its capabilities for handling complex repository histories and frequent integrations.


title: SYNOPSIS
content:
<b>git reset</b> [--soft | --mixed | --hard | --merge | --keep] [<I>commit</I>] [--] [<I>path</I>...]


title: PARAMETERS
content:
<b><I>commit</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The target commit to reset to. This can be a commit hash, branch name, tag, or a relative reference like <I>HEAD~1</I>. If omitted, it defaults to <I>HEAD</I>.<br><br><b>--soft</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Moves the <I>HEAD</I> pointer to the target commit. The index (staging area) and working directory are left completely untouched. Changes from the reset commits appear as staged changes, ready to be committed again.<br><br><b>--mixed</b><br>&nbsp;&nbsp;&nbsp;&nbsp;(Default behavior) Moves the <I>HEAD</I> pointer to the target commit and updates the index to match it. The working directory remains unchanged. Changes are now in the working directory but unstaged.<br><br><b>--hard</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Moves the <I>HEAD</I> pointer, updates the index, <I>and</I> overwrites the working directory to match the target commit. All uncommitted changes and staged changes are irrevocably lost. Use with extreme caution.<br><br><b>--merge</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Resets the <I>HEAD</I> and index to the target commit, but keeps local changes in the working directory. Attempts a merge of the changes into the working directory; fails if there are conflicts.<br><br><b>--keep</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Resets the <I>HEAD</I> and index to the target commit, but only if the working directory has no uncommitted changes for the files that are tracked by the reset target. Useful for discarding some changes while preserving others.<br><br><b>--</b><br>&nbsp;&nbsp;&nbsp;&nbsp;A separator used to distinguish between options and file paths. It's often used when a path might be mistaken for an option (e.g., if a file name starts with a hyphen).<br><br><b><I>path</I>...</b><br>&nbsp;&nbsp;&nbsp;&nbsp;One or more file or directory paths. When paths are specified, <I>git reset</I> typically operates only on the index, unstaging the specified files to match the <I>commit</I> (or <I>HEAD</I> if no commit is given), without moving the <I>HEAD</I> pointer.<br><br>


title: DESCRIPTION
content:
<b>git reset</b> is a powerful and versatile Git command used to undo changes, move the <I>HEAD</I> pointer, and manipulate the staging area (index) and the working directory. It operates primarily on "three trees" of Git: the <I>HEAD</I> commit (the last commit), the index (the staging area), and the working directory (your current files).<br><br>The command has three main modes, each affecting these trees differently: <br><br><I><b>--soft</b></I>: This mode moves the <I>HEAD</I> pointer to the specified commit but leaves the index and working directory unchanged. This effectively unstages the commits that were "reset" off <I>HEAD</I>, making their changes appear as pending, ready to be restaged and recommitted.<br><br><I><b>--mixed</b></I> (default): This mode, the default behavior, moves the <I>HEAD</I> pointer to the specified commit and then updates the index to match that commit. The working directory remains untouched. Changes that were part of the "reset" commits are now in your working directory but unstaged, allowing you to re-examine, modify, and re-add them.<br><br><I><b>--hard</b></I>: This is the most drastic and destructive mode. It moves the <I>HEAD</I> pointer, updates the index, <I>and</I> overwrites the working directory to match the specified commit. All uncommitted changes in the working directory and the staging area are irrevocably lost. Use with extreme caution.<br><br><b>git reset</b> can also be used with a <I>pathspec</I> to unstage specific files, leaving <I>HEAD</I> unchanged. It's an essential tool for managing changes before committing, correcting mistakes, and navigating through commit history.


title: CAVEATS
content:
<b><I>git reset --hard</I> is destructive:</b> It irrevocably discards all uncommitted changes in your working directory and staging area. If you haven't committed the changes, they are lost forever unless you can recover them via the reflog (which is not guaranteed).<br><br><b>Rewriting shared history:</b> Using <I>git reset</I> to move <I>HEAD</I> on a branch that has already been pushed to a remote repository (i.e., shared history) will rewrite that history. This can cause significant problems for collaborators who have based their work on the old history. In such cases, <I>git revert</I> is generally the preferred and safer method for undoing commits.<br><br><b>Understanding 'The Three Trees':</b> Misunderstanding how <I>git reset</I> interacts with <I>HEAD</I>, the index, and the working directory can lead to unintended data loss or confusion. Always be clear about which mode you are using and its implications.


title: THE THREE TREES OF GIT
content:
To effectively use <b>git reset</b>, it's crucial to understand Git's core concept of "three trees" (or states):<br><br><I><b>HEAD</b></I>: Represents the last commit on the current branch. It's the immutable history of your repository. This is where <I>HEAD</I> (the current branch tip or detached <I>HEAD</I>) points.<br><br><I><b>Index (Staging Area)</b></I>: Also known as the cache or staging area, this is a virtual snapshot of what your <I>next commit</I> will look like. When you run <I>git add</I>, you're updating the index.<br><br><I><b>Working Directory</b></I>: These are the actual files and directories on your local filesystem that you are currently editing. This is where you make your changes.<br><br>Each mode of <I>git reset</I> specifically targets how these three trees are updated or left untouched, allowing precise control over your repository's state.


title: HISTORY
content:
<b>git reset</b> has been a fundamental command since the early days of Git, providing a versatile way to manipulate commits, the index, and the working directory. Its different modes (<I>--soft</I>, <I>--mixed</I>, <I>--hard</I>) were designed to cover various "undo" scenarios. Over time, some of its functionalities, particularly those related to restoring files, have been refined and split into more specialized commands like <I>git restore</I> and <I>git switch</I> (starting from Git 2.23) to make the command set clearer and safer, reducing the "overload" of <I>git checkout</I> and <I>git reset</I>. Despite these newer commands, <b>git reset</b> remains central for managing <I>HEAD</I> and unstaging changes.


title: PARAMETERS
content:
<b><I>file</I>...</b><br>&nbsp;&nbsp;&nbsp;&nbsp;One or more files to be reset. These paths are relative to the project root.<br><br><b><I>tree-ish</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Optional. The commit or tree from which to restore the file's content. If omitted, it typically defaults to <I>HEAD</I> (the latest commit on the current branch). This can be a branch name, commit hash, tag, etc.<br><br><b>--staged</b><br>&nbsp;&nbsp;&nbsp;&nbsp;When used, it implies resetting the file in the staging area (index) to match the specified <I>tree-ish</I> (or <I>HEAD</I>), while keeping the working tree file unchanged. Effectively unstages the file.<br><br><b>--worktree</b><br>&nbsp;&nbsp;&nbsp;&nbsp;When used, it implies resetting the file in the working directory to match the staging area (index) or the specified <I>tree-ish</I> (or <I>HEAD</I>). This action discards local modifications.<br><br><b>--source=<I>tree-ish</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;An explicit way to specify the <I>tree-ish</I> (commit, branch, tag, etc.) from which to restore the file. This clarifies the source for the file content.<br><br>


title: DESCRIPTION
content:
The command <b>git-reset-file</b> is not a standard, officially distributed Git command. <br>However, the concept it implies – restoring a single file to a previous state – is a fundamental Git operation. This functionality is typically achieved using the standard Git commands <B>git restore</B> or <B>git checkout</B>.<br><br>Conceptually, <b>git-reset-file</b> would allow users to:<br><ul><li>Unstage changes for a specific file, moving it from the Git index (staging area) back to the working directory without discarding local modifications. This is analogous to `git reset HEAD <file>`.</li><li>Discard local modifications in the working directory for a file, reverting it to its state in the Git index or the <I>HEAD</I> commit. This is analogous to `git restore <file>` (or `git checkout -- <file>`).</li><li>Restore a file to its state from an arbitrary commit. This is analogous to `git restore --source=<commit> <file>` (or `git checkout <commit> -- <file>`).</li></ul><br>The primary purpose is to selectively revert changes to individual files without affecting other files or the overall repository history.


title: CAVEATS
content:
The command name <B>git-reset-file</B> is not a standard part of the official Git distribution. Users typically achieve this functionality using <B>git restore</B> (recommended for newer Git versions) or <B>git checkout --</B> for discarding working directory changes, and <B>git reset HEAD</B> for unstaging. Direct usage of <B>git-reset-file</B> would imply a custom script or alias defined by the user or a third-party tool.


title: DIFFERENCE FROM 'GIT RESET'
content:
It's crucial to differentiate this conceptual `git-reset-file` operation from the general <B>git reset</B> command without a path. <B>git reset</B> (without file paths) typically moves the <I>HEAD</I> pointer and potentially rewrites history, affecting commits, branches, and potentially requiring a force push if pushed to a shared remote. <B>git-reset-file</B> (or its functional equivalents like <B>git restore</B> or <B>git reset HEAD <I>file</I></B>) only affects the state of specific files in the working directory or staging area, without altering the commit history.


title: HISTORY
content:
The ability to restore or unstage individual files has been a core Git feature since its inception. Historically, <B>git checkout -- <I>file</I></B> was the primary command for discarding working directory changes to a file, and <B>git reset HEAD <I>file</I></B> for unstaging. <br><br>With Git version 2.23 (released August 2019), the new command <B>git restore</B> was introduced to provide a clearer and safer interface for these operations, separating the concerns of restoring files from switching branches (which <B>git checkout</B> also does). <br><br>While <B>git-reset-file</B> itself does not have a formal history, its implied functionality evolved significantly with the introduction of <B>git restore</B>, making the process of individual file restoration more intuitive and less ambiguous.


title: SYNOPSIS
content:
<b>git restore</b> [<options>] [--source=<tree>] [--staged] [--worktree] [--pathspec-from-file=<file> [--pathspec-file-nul]] [--] <pathspec>...


title: PARAMETERS
content:
<b>--source=<tree></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Restore files from the specified <i>&lt;tree&gt;</i> (e.g., commit hash, branch name, tag name). If not specified, <b>HEAD</b> is used for <b>--staged</b> and the index is used for <b>--worktree</b>.<br><br><b>-s, --staged</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Restore files into the index. This effectively unstages changes, reverting the index to match the <b>HEAD</b> commit or the specified <b>--source</b>.<br><br><b>-W, --worktree</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Restore files into the working tree. This is the default action if neither <b>--staged</b> nor <b>--worktree</b> is specified, or if <b>--staged</b> is not specified. It discards working tree changes, reverting files to match the index or the specified <b>--source</b>.<br><br><b>--pathspec-from-file=<file></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Read pathspecs from <i>&lt;file&gt;</i> instead of from the command line. Pathspecs are usually one per line.<br><br><b>--pathspec-file-nul</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Only meaningful with <b>--pathspec-from-file</b>. Pathspecs in the file are separated by NUL characters instead of newlines.<br><br><b>-p, --patch</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Interactively select hunks of changes to restore. This allows reviewing and selecting specific parts of changes to be reverted.<br><br><b>--dry-run</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Don't actually restore anything, just show what would be done.<br><br><b>-q, --quiet</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Suppress all output.<br><br><b>-v, --verbose</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Be verbose.<br><br><b><pathspec>...</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Optional path(s) to restore. If omitted, the entire working tree and/or index (depending on flags) is affected.<br><br>


title: DESCRIPTION
content:
The <b>git restore</b> command is used to restore specified paths in the working tree or the index from a given source. Introduced in Git 2.23, it aims to clarify the functionality previously overloaded by <b>git checkout</b>.<br><br>While <b>git checkout</b> could switch branches, restore files, and restore files from a specific commit, <b>git restore</b> focuses solely on file restoration. This separation of concerns (<b>git switch</b> for branch switching, <b>git restore</b> for file restoration) makes Git's command line interface more intuitive and less prone to user error.<br><br>It can be used to discard uncommitted changes in the working directory, unstage changes from the index, or revert a file to an earlier state from any commit in the repository history.


title: CAVEATS
content:
<b>git restore</b> only operates on file paths; it does <i>not</i> switch branches or update <b>HEAD</b>. For branch switching, use <b>git switch</b>. It can restore files from the index (to working tree) or from <b>HEAD</b> (to index), or from any specified commit. Be aware that restoring changes will overwrite local modifications unless <b>--patch</b> is used.


title: DEFAULT BEHAVIOR
content:
When no <b>--source</b> is explicitly provided:<br><i>1.</i> <b>git restore &lt;pathspec&gt;...</b> (without <b>--staged</b>): Restores the working tree files to match the state of the index.<br><i>2.</i> <b>git restore --staged &lt;pathspec&gt;...</b>: Restores the index to match the state of the <b>HEAD</b> commit.<br><i>3.</i> <b>git restore --staged --worktree &lt;pathspec&gt;...</b>: Restores both the index and the working tree to match the state of the <b>HEAD</b> commit.


title: RESTORING FROM A SPECIFIC COMMIT
content:
To restore a file or set of files to their state at a particular commit, use the <b>--source</b> option:<br><b>git restore --source=<i>&lt;commit-hash&gt;</i> &lt;file&gt;</b><br>This command will take the version of <i>&lt;file&gt;</i> from <i>&lt;commit-hash&gt;</i> and place it into your working tree. If you also want to stage it, add <b>--staged</b>.


title: HISTORY
content:
The <b>git restore</b> command was introduced in Git version 2.23 (released August 2019). Its primary motivation was to address the overloaded nature of the <b>git checkout</b> command. Historically, <b>git checkout</b> performed three distinct operations: switching branches, restoring working tree files, and restoring files from a specific commit. This multi-functionality often led to confusion. To improve clarity and user experience, the Git project decided to split these responsibilities. <b>git switch</b> was introduced for branch operations, and <b>git restore</b> for file restoration, allowing <b>git checkout</b> to remain for backward compatibility but encouraging users to adopt the more explicit new commands.


title: SYNOPSIS
content:
<b>git rev-list</b> [<I>options</I>] <I>&#60;commit-ish>...</I><br><b>git rev-list</b> --walk-reflogs [<I>options</I>] <I>&#60;refname>...</I>


title: PARAMETERS
content:
<b>--walk-reflogs</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Walk reflogs instead of the commit graph. Requires <i>&#60;refname></i> instead of <i>&#60;commit-ish></i>.<br><br><b><I>&#60;commit-ish>...</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify starting points for the traversal. These can be commit SHAs, branch names, tags, or other references.<br><br><b>--all</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show all reachable commits from all refs (branches, tags, remotes).<br><br><b>--branches[=<I>pattern</I>]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Include all local branches (or those matching a specified pattern).<br><br><b>--tags[=<I>pattern</I>]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Include all tags (or those matching a specified pattern).<br><br><b>--remotes[=<I>pattern</I>]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Include all remote-tracking branches (or those matching a specified pattern).<br><br><b>--not <I>&#60;commit></I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Exclude commits reachable from the specified commit.<br><br><b>--since=<I>&#60;date></I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Limit commits to those newer than a specified date.<br><br><b>--until=<I>&#60;date></I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Limit commits to those older than a specified date.<br><br><b>--author=<I>&#60;pattern></I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Limit commits to those whose author matches the pattern.<br><br><b>--committer=<I>&#60;pattern></I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Limit commits to those whose committer matches the pattern.<br><br><b>--grep=<I>&#60;pattern></I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Limit commits to those whose log message matches the pattern.<br><br><b>--max-count=<I>&#60;number></I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Limit the number of commits to output.<br><br><b>--skip=<I>&#60;number></I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Skip a specified number of commits before starting to show the output.<br><br><b>--objects</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Print object IDs of referenced objects (trees, blobs) along with commit IDs.<br><br><b>--parents</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Print parent commit IDs after each commit ID.<br><br><b>--children</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Print child commit IDs after each commit ID (implies --topo-order).<br><br><b>--topo-order</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Output commits in topological order (parents before children).<br><br><b>--date-order</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Output commits in date order (newest first within common ancestors).<br><br><b>--reverse</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Output commits in reverse order (oldest first).<br><br><b>--left-right</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Mark which side of a symmetric difference the commit is on (< for left, > for right).<br><br>


title: DESCRIPTION
content:
<b>git-rev-list</b> is a low-level <i>plumbing</i> command in Git that lists commit objects, typically in reverse chronological order, starting from the specified points. It forms the core of many Git commands, most notably <b>git log</b>. Unlike <b>git log</b>, which is a <i>porcelain</i> command focused on user-friendly output, <b>git-rev-list</b> primarily outputs commit SHAs and is designed for scripting and internal Git operations. It offers extensive options for filtering, ordering, and selecting commits based on various criteria like author, committer, date ranges, commit message patterns, and reachability. Its power lies in its ability to precisely control which commits are included or excluded, making it invaluable for advanced repository analysis, custom logging, and complex merge strategies.


title: CAVEATS
content:
<b>git-rev-list</b> is a <i>plumbing</i> command, meaning its output is designed for programmatic consumption, not human readability. For user-friendly output, consider using <b>git log</b>, which builds upon <b>git-rev-list</b> but provides rich formatting and filtering options. Using options like `--objects` can produce very verbose output.


title: PLUMBING VS. PORCELAIN
content:
<b>git-rev-list</b> exemplifies a "plumbing" command, providing a low-level interface for internal Git operations. This contrasts with "porcelain" commands like <b>git log</b>, which are user-friendly interfaces built upon these plumbing commands. Understanding this distinction is key to leveraging Git effectively for scripting and automation.


title: SYMMETRIC DIFFERENCE
content:
When comparing two branches, <b>git-rev-list</b> can be used to show commits unique to each side. For example, `git rev-list A...B` will show commits reachable from A or B but not from their common ancestor. This is often used with `--left-right` to distinguish which branch a commit originates from.


title: HISTORY
content:
<b>git-rev-list</b> has been a fundamental component of Git since its early days, predating the more user-friendly <b>git log</b>. It was designed by Linus Torvalds as part of the initial Git toolkit, providing the core mechanism for traversing and filtering commit graphs. Its continued importance highlights Git's modular design, where complex <i>porcelain</i> commands are built upon simpler, powerful <i>plumbing</i> tools.


title: PARAMETERS
content:
<b>--quiet, -q</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Only output SHA-1 on stdout; suppress all error messages.<br><br><b>--verify</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Ensure that the arguments are valid Git object names. If not, exit with a non-zero status.<br><br><b>--short[=<I>length</I>]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shortens the object names to a unique prefix. If <I>length</I> is specified, it tries to shorten to that length.<br><br><b>--symbolic-full-name</b><br>&nbsp;&nbsp;&nbsp;&nbsp;If the argument is a symbolic ref (e.g., `HEAD`), output its full name (e.g., `refs/heads/master`) instead of the SHA-1.<br><br><b>--abbrev-ref[=<I>length</I>]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Abbreviates references. For example, `refs/heads/master` becomes `master`.<br><br><b>--is-bare-repository</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Checks if the current repository is a bare repository (no working tree). Exits with 0 if true, 1 otherwise.<br><br><b>--is-inside-git-dir</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Checks if the current working directory is inside the `.git` directory. Exits with 0 if true, 1 otherwise.<br><br><b>--is-inside-work-tree</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Checks if the current working directory is inside the Git work tree. Exits with 0 if true, 1 otherwise.<br><br><b>--show-cdup</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows the path from the current directory to the top-level directory of the work tree.<br><br><b>--show-prefix</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows the path from the top-level directory of the work tree to the current directory.<br><br><b>--show-toplevel</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows the absolute path to the top-level directory of the work tree.<br><br><b>--glob=<I>glob-pattern</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Expands glob patterns into a list of matching refs. Useful for finding all branches or tags that match a pattern.<br><br><b>--sq-quote</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Quote all arguments for use in a shell. Useful for passing complex arguments safely.<br><br><b>--default <I>arg</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;If no arguments are given or they do not specify a revision, output <I>arg</I>.<br><br>


title: DESCRIPTION
content:
The <b>git rev-parse</b> command is a low-level "plumbing" command in Git, primarily used for converting various human-friendly revision expressions into their corresponding Git object SHA-1 hashes. It is a powerful tool for scripting and internal Git operations, enabling programs to reliably determine the Git object ID for a given reference (like a branch name, tag, or HEAD).<br><br>Beyond resolving object names, it can also parse command-line options, resolve paths relative to the Git repository, and provide information about the repository's state (e.g., whether it's bare, or if the current directory is within the `.git` directory). Its output is typically machine-readable, making it invaluable for building robust Git-aware scripts that need to interact directly with Git's object database.


title: CAVEATS
content:
<b>git rev-parse</b> is a low-level command; its output is primarily intended for machine consumption (e.g., scripts). Its behavior can sometimes be subtle, especially when dealing with ambiguous references or paths. Relying on its output directly in user-facing contexts without proper validation is generally not recommended. Internal Git behavior that `rev-parse` reflects may change in future versions.


title: SPECIFYING REVISIONS
content:
<b>git rev-parse</b> supports a rich set of revision notations, including:<br><ul><li>SHA-1 object names (full or abbreviated).</li><li>Branch names (e.g., `master`, `main`).</li><li>Tag names (e.g., `v1.0`).</li><li>`HEAD` (the current commit of the active branch).</li><li>Relative revisions (e.g., `HEAD~3` for the 3rd ancestor, `HEAD^` for the first parent).</li><li>References to remote branches (e.g., `origin/master`).</li><li>@{<I>date</I>} or @{<I>n</I>} for looking up refs by time or position in reflog.</li><li>@{u} or @{upstream} for the upstream branch.</li><li>Ranges like `A..B` for commits reachable from B but not A.</li><li>Paths combined with revisions (e.g., `HEAD:path/to/file` to get the blob ID).</li></ul><br>This flexibility is central to its utility, allowing precise targeting of Git objects.


title: OUTPUT FORMATS
content:
The command's output varies significantly depending on the options used:<br><ul><li>By default, it outputs the full 40-character SHA-1 hash for the resolved object.</li><li>With `--short`, it outputs an abbreviated SHA-1.</li><li>With `--symbolic-full-name` or `--abbrev-ref`, it outputs the symbolic name of the reference if applicable.</li><li>Options like `--show-cdup`, `--show-prefix`, `--show-toplevel` output paths relative to the current directory or the work tree root.</li><li>Boolean options like `--is-bare-repository` simply set the exit status (0 for true, 1 for false) and typically produce no standard output, or optionally a `true`/`false` line if combined with other options.</li><li>`--glob` expands patterns into a list of matching full ref names, one per line.</li></ul><br>Understanding the expected output for specific options is crucial for effective scripting.


title: HISTORY
content:
<b>git rev-parse</b> has been a fundamental "plumbing" command since the early days of Git, forming a core part of its internal machinery for resolving and understanding revisions. Its robust ability to translate various human-readable inputs into unambiguous object IDs has made it indispensable for Git's own commands and for external scripting. It has evolved with Git, incorporating new ways to specify revisions and providing more utilities for path resolution and repository state queries, solidifying its role as a bedrock utility in the Git ecosystem.


title: PARAMETERS
content:
<b>--edit, -e</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Invoke the editor before committing the revert. This is the default behavior.<br><br><b>--no-edit</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Do not invoke the editor. The commit message will be generated automatically.<br><br><b>--no-commit, -n</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Do not automatically commit the revert; instead, leave the changes in the working tree and index. This allows for further modifications before committing manually.<br><br><b>--mainline <parent-number>, -m <parent-number></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Revert a merge commit. This option specifies which parent's history should be considered the 'mainline' and thus which side of the merge to revert. Required for merge commits.<br><br><b>--signoff, -s</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Add a 'Signed-off-by:' line to the commit message, indicating that the committer certifies the commit.<br><br><b>--gpg-sign[=<keyid>], -S[<keyid>]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;GPG-sign the revert commit. An optional keyid can be specified to use a particular key.<br><br><b><commit-ish>...</b><br>&nbsp;&nbsp;&nbsp;&nbsp;One or more commit hashes, branch names, tags, or other references pointing to the commits to revert. You can specify multiple commits to revert them in reverse chronological order.<br><br>


title: DESCRIPTION
content:
<i>git revert</i> is a powerful command used to undo changes introduced by a specific commit or a series of commits. Unlike <i>git reset</i>, which modifies the project history by removing commits, <i>git revert</i> creates a <br><br><b>new commit</b> that reverses the effects of the target commit(s). This approach is non-destructive, making it ideal for shared repositories where preserving history is crucial.<br><br>When you revert a commit, Git calculates the inverse of the changes and applies them as a new commit. If the original commit added a line, the revert commit removes it; if it removed a line, the revert adds it back. This command is particularly useful for undoing accidental changes in public branches without rewriting history, maintaining a clean and accurate record of all modifications, including their reversals. It's a safe way to backtrack from erroneous commits in a collaborative environment.


title: CAVEATS
content:
Reverting a commit might lead to <br><br>merge conflicts if subsequent changes in the repository overlap with the changes being reverted. You will need to resolve these conflicts manually before committing.<br><br>When reverting merge commits, the <i>-m</i> or <i>--mainline</i> option is mandatory to specify which parent's changes are being undone, as a merge commit has multiple parents.<br><br>Reverting a commit that was already reverted will reintroduce the original changes, effectively undoing the previous revert. <br><br>Always ensure your working directory is clean or stash changes before performing a revert to avoid losing work or complicating the revert process.


title: NON-DESTRUCTIVE NATURE
content:
<i>git revert</i> is designed to be non-destructive, meaning it does not alter the existing commit history. Instead, it adds new commits that explicitly undo the changes of previous ones. This makes it a safer option for shared and published branches compared to commands like <i>git reset</i>, which can rewrite history and cause problems for collaborators.


title: HANDLING MERGE COMMITS
content:
Reverting a merge commit requires special attention because a merge commit incorporates changes from two or more parent branches. You must use the <i>-m</i> or <i>--mainline</i> option to specify which parent's perspective should be preserved as the 'mainline' and which side of the merge introduced the changes you want to revert. For example, 'git revert -m 1 <merge-commit-hash>' to undo changes from the merged branch while preserving the main branch's history.


title: SYNOPSIS
content:
<b>git rm</b> [--cached] [-r | --recursive] [-f | --force] [-n | --dry-run] [--ignore-unmatch] &lt;pathspec&gt;...


title: PARAMETERS
content:
<b>--cached</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Only remove from the index. The file remains in the working tree. This is useful for untracking files that are mistakenly added to the repository.<br><br><b>-r, --recursive</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Allow recursive removal of directories. This option is mandatory when removing a directory.<br><br><b>-f, --force</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Override the up-to-date check. Use this option to force removal of a file that has different content in the working tree than in the index or has uncommitted changes.<br><br><b>-n, --dry-run</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Don't actually remove any file(s). Instead, just show what would be removed. This is useful for testing the command's effect before committing changes.<br><br><b>--ignore-unmatch</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Exit with a zero status even if no files match the provided &lt;pathspec&gt;. By default, <b>git rm</b> exits with a non-zero status if a pathspec does not match any files.<br><br><b>&lt;pathspec&gt;...</b><br>&nbsp;&nbsp;&nbsp;&nbsp;The file(s) or directory(ies) to remove. Wildcards (e.g., *.txt) can be used, but require proper shell quoting to prevent shell expansion.<br><br>


title: DESCRIPTION
content:
The <b>git rm</b> command removes files from the working tree and from the Git index (staging area). This command is used to record the removal of a file in your Git repository. Unlike the standard <b>rm</b> command, <b>git rm</b> not only deletes the file from your filesystem but also stages the deletion for the next commit. If a file has uncommitted changes (i.e., it's modified in the working tree and differs from the version in the index), <b>git rm</b> will refuse to remove it unless you explicitly use the <b>--force</b> option to prevent accidental data loss. This ensures that you don't inadvertently discard valuable work. The command can also be used to remove files only from the Git index, leaving them in the working tree, which is useful for untracking files without deleting them from your local disk.


title: CAVEATS
content:
<b>git rm</b> only affects files tracked by Git. It cannot remove untracked files; for those, use the filesystem <b>rm</b> command. Files removed with <b>git rm</b> are removed from the *current* state and will be absent in future commits, but they remain in the repository's history and can be recovered using commands like <b>git log</b> or <b>git restore</b> on previous commits. If you accidentally <b>git rm</b> a file before committing, you can typically recover it using <b>git restore --staged &lt;file&gt;</b> to undo the staging and <b>git restore &lt;file&gt;</b> to restore the working tree file.


title: UNTRACKING FILES WITH --CACHED
content:
The <b>--cached</b> option is crucial for untracking files that were accidentally committed or should no longer be tracked by Git (e.g., large data files, build artifacts). Using <b>git rm --cached &lt;file&gt;</b> removes the file from the Git index without deleting it from your local filesystem. After running this command, you typically add the file to your <b>.gitignore</b> file to prevent it from being re-added in subsequent <b>git add .</b> operations, thus effectively untracking it for all future commits.


title: SAFETY MECHANISMS
content:
<b>git rm</b> incorporates built-in safety mechanisms. By default, it will prevent you from removing a file that has uncommitted changes in your working tree (i.e., modifications not yet staged or committed) or if the file in the working tree differs from the version in the index. This prevents accidental loss of data. To override this safety, you must explicitly use the <b>--force</b> (or <b>-f</b>) option, indicating that you understand and accept the potential data loss and wish to proceed with the removal despite inconsistencies.


title: HISTORY
content:
The <b>git rm</b> command has been a foundational part of Git since its inception. It was designed as a core utility to manage the lifecycle of files within a Git repository, specifically handling deletions. Its fundamental behavior of removing files from both the working directory and the index, coupled with safety checks against accidental data loss, has remained consistent throughout Git's development. The introduction of options like <b>--cached</b> further enhanced its utility, allowing for more granular control over tracking files, especially for managing repository size and accidental inclusions.


title: SYNOPSIS
content:
<B>git rscp</B> <I>command</I> [<I>options</I>] [<I>arguments</I>]<br><br>Example hypothetical usage:<br><B>git rscp push</B> <I>remote</I> <I>branch</I><br><B>git rscp fetch</B> <I>remote</I><br><B>git rscp clone</B> <I>user@host:/path/to/repo.git</I> [<I>local-path</I>]


title: PARAMETERS
content:
<b><I>command</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The specific Git operation to perform (e.g., <B>push</B>, <B>fetch</B>, <B>clone</B>).<br><br><b><I>remote</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The name of the remote repository configured in Git.<br><br><b><I>branch</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The specific branch to push or fetch.<br><br><b><I>user@host:/path/to/repo.git</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The full SCP-style path to the remote Git repository for operations like cloning.<br><br><b><I>local-path</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The local directory where the repository should be cloned.<br><br><b>-p <I>port</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the port to connect to on the remote host for SCP.<br><br><b>-i <I>identity_file</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Selects a file from which the identity (private key) for public key authentication is read.<br><br><b>-q</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Quiet mode: Suppresses non-error messages during the operation.<br><br><b>-r</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Recursively copy directories (relevant for clone operations).<br><br>


title: DESCRIPTION
content:
The command <i>git-rscp</i> is <B>not a standard Git command</B> or a widely recognized Linux utility. If such a command existed, it would likely be a custom script or an alias designed to facilitate Git repository transfers and operations over the Secure Copy Protocol (SCP). This would involve pushing or pulling repository data between local and remote machines using SCP, potentially wrapping standard Git commands like <B>git push</B> or <B>git fetch</B> to use SCP as the transport layer, similar to how SSH is commonly used.<br><br>A more common, though still unofficial, utility with similar intent is <B>git-scp</B>, which allows for Git repository transfers using SCP instead of SSH directly. The functionality of a hypothetical <B>git-rscp</B> would aim to simplify interactions where SCP is the preferred or only available secure file transfer mechanism for Git.


title: CAVEATS
content:
This command is <B>not a standard part of Git</B> nor a recognized standalone utility in most Linux distributions. Its existence would likely be as a custom script developed for specific environments or personal use. Therefore, its behavior, options, and security implications could vary greatly. Users should exercise caution and thoroughly review any such custom script before execution, especially concerning sensitive data or credentials. Relying on SCP for Git transport generally requires more manual setup and can be less efficient than Git's native smart protocols (like SSH or HTTP/S).


title: CUSTOM SCRIPT IMPLEMENTATION
content:
A command named <B>git-rscp</B> would typically be implemented as a shell script (or other programming language script) placed in the user's PATH or a directory accessible by Git (e.g., `~/bin` or `~/.git/hooks`). It would parse arguments and then execute appropriate <B>scp</B> and <B>git</B> commands in sequence to achieve its purpose.


title: ALTERNATIVE TRANSPORTS
content:
Git primarily uses the `ssh` protocol (via `git@github.com:user/repo.git` style URLs) or `http`/`https` for remote operations. SCP, while file-transfer focused, could theoretically be wrapped for Git, though it's less optimized for repository synchronization than Git's native smart protocols, which are designed for efficient delta transfers.


title: HISTORY
content:
As <B>git-rscp</B> is not a standard Git command, there is no official development history or widespread adoption to document. Any tool bearing this name would likely be a bespoke solution, originating from specific user needs or project requirements where standard Git remote protocols were not viable or preferred. Its "history" would thus be confined to individual development efforts.


title: PARAMETERS
content:
<b><i>&lt;SOURCE&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The path to the source repository. This can be a local directory (e.g., <i>.</i> or <i>/path/to/repo</i>) or a remote path (e.g., <i>user@host:/path/to/repo.git</i>).<br><br><b><i>&lt;DESTINATION&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The path to the destination location. This can be a local directory or a remote path. The behavior (push/pull) depends on whether <i>&lt;SOURCE&gt;</i> or <i>&lt;DESTINATION&gt;</i> is remote.<br><br><b><b>--bare</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>(Optional)</i> When used, treats the source as a bare repository or creates a bare repository at the destination. A bare repository contains the Git history but no working tree.<br><br><b><b>--mirror</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>(Optional)</i> Similar to <b>--bare</b>, but sets up a mirror of the repository, including all references (branches, tags, remotes) exactly as they are in the source.<br><br><b><b>--tags</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>(Optional)</i> Transfers all tags from the source to the destination during the copy operation.<br><br><b><b>--all</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>(Optional)</i> Transfers all branches and tags from the source to the destination. This is often implied or part of <b>--mirror</b> functionality.<br><br><b><b>--dry-run</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>(Optional)</i> Performs a simulation of the transfer without actually copying any data. It shows what actions would be taken.<br><br><b><b>--verbose</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>(Optional)</i> Enables verbose output, showing the underlying <b>scp</b> and <b>git</b> commands executed by the script.<br><br>


title: DESCRIPTION
content:
<b>git-scp</b> is a non-standard Git helper command that facilitates the transfer of Git repositories or objects between local and remote hosts using the Secure Copy Protocol (SCP). It is particularly useful in environments where standard Git protocols (SSH, HTTP/S, Git protocol) are not configured, are restricted, or when a quick, direct copy is needed without setting up a full Git server.<br><br>Instead of relying on daemons like <b>git-daemon</b> or <b>git-http-backend</b>, <b>git-scp</b> leverages <b>scp</b> to copy necessary Git objects, references (refs), and packed files. This command is typically implemented as a shell script that wraps core <b>git</b> commands (such as <b>git bundle</b>, <b>git push</b>, or <b>git fetch</b>) and the <b>scp</b> utility for the actual data transfer.<br><br>It can be used to push changes from a local repository to a bare repository on a remote server, or to pull updates from a remote bare repository. While it simplifies the manual process of bundling and transferring repositories, it's important to note that <b>git-scp</b> is not part of the official Git distribution, and its exact functionality can vary depending on the specific script implementation.


title: CAVEATS
content:
<b>git-scp</b> is not a standard, officially distributed Git command. Its availability, exact feature set, and behavior depend entirely on the specific third-party script implementation you are using.<br><br>It requires <b>scp</b> and <b>ssh</b> to be installed and properly configured on both the local and remote hosts involved in the transfer. This often means SSH keys need to be set up for passwordless access.<br><br>While data is transferred securely over SSH, the script itself is a wrapper. Its reliability and security depend on the quality of its implementation. For very large repositories, native Git protocols (like SSH or HTTP) are generally more efficient than <b>git-scp</b>, as it may involve bundling/unbundling steps.


title: EXAMPLES
content:
<b>Push a local repository to a remote bare repository:</b><br><i>git scp . user@remote.com:/srv/git/my-project.git</i><br><br><b>Clone a remote bare repository to a local directory:</b><br><i>git scp --bare user@remote.com:/srv/git/another-project.git ./local-clone</i><br><br><b>Perform a dry run to see what would be copied:</b><br><i>git scp --dry-run ~/my_repo user@remote.com:/tmp/test_repo.git</i>


title: INSTALLATION
content:
Since <b>git-scp</b> is a standalone script, its installation is straightforward:<br><br>1. <b>Download the script:</b> Obtain the <b>git-scp</b> script from a trusted source (e.g., a community repository or a personal gist).<br>2. <b>Place it in PATH:</b> Copy the script to a directory that is included in your system's <b>PATH</b> environment variable (e.g., <i>/usr/local/bin/</i>, <i>~/bin/</i>).<br>3. <b>Make it executable:</b> Ensure the script has execute permissions: <i>chmod +x /path/to/git-scp</i><br><br>After these steps, Git will automatically recognize and allow you to invoke the script as <i>git scp</i>, as Git looks for executable files named <i>git-*</i> in your <b>PATH</b>.


title: HISTORY
content:
<b>git-scp</b> does not have a centralized or official development history like core Git commands. It emerged organically as a community-driven solution to specific challenges, particularly for users needing to transfer Git repositories when standard Git protocols were difficult or impossible to set up.<br><br>Many independent developers have created their own versions of <b>git-scp</b> scripts, often sharing them as gists or part of larger collections of Git helper utilities (e.g., <i>git-extras</i>). Its usage became prominent in scenarios involving strict firewall rules or limited server configurations where setting up <b>git-daemon</b> or <b>git-http-backend</b> was not feasible.<br><br>While not a primary Git workflow tool, it continues to serve as a niche, practical utility for specific deployment, backup, or ad-hoc repository transfer scenarios.


title: SYNOPSIS
content:
<b>git secret</b> <command> [options] [arguments]<br><br>Common commands include:<br><i>git secret init</i><br><i>git secret tell &lt;gpg-id&gt;...</i><br><i>git secret hide</i><br><i>git secret reveal</i><br><i>git secret add &lt;file-path&gt;...</i><br><i>git secret remove &lt;file-path&gt;...</i>


title: PARAMETERS
content:
<b>init</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Initializes a Git repository for <b>git-secret</b> management. This creates the <i>.gitsecret</i> directory and its essential configuration files.<br><br><b>tell <gpg-id>...</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Adds one or more GPG public key IDs to the list of authorized users who can encrypt and decrypt the repository's secrets.<br><br><b>hide</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Encrypts all files currently tracked by <b>git-secret</b> and prepares their encrypted versions for committing to Git. The plaintext files are removed (unless configured otherwise).<br><br><b>reveal</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Decrypts all tracked secret files, making their plaintext content available in the working directory for use.<br><br><b>add <file-path>...</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Marks specified files or directories to be managed as secrets by <b>git-secret</b>. Their paths are added to the <i>.gitsecret/paths</i> file.<br><br><b>remove <file-path>...</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Unmarks specified files or directories from <b>git-secret</b> management. They will no longer be encrypted/decrypted by the tool.<br><br><b>whoknows</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a list of GPG key IDs for all users who are authorized to decrypt the secrets in the current repository.<br><br><b>whoami</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows the GPG key ID that <b>git-secret</b> will use for the current user to encrypt or decrypt files.<br><br><b>clean</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Removes all plaintext versions of secret files from the working directory, leaving only their encrypted counterparts.<br><br><b>status</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows the current encryption status of tracked secret files (e.g., encrypted, unencrypted, or unknown).<br><br><b>diff [file-path]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a diff between the plaintext and encrypted versions of a secret file. If no path is given, it shows diffs for all tracked secrets.<br><br>


title: DESCRIPTION
content:
<b>git-secret</b> is a powerful bash tool that leverages <b>gpg</b> (GNU Privacy Guard) to securely manage sensitive files within a Git repository. It enables development teams to store confidential data like API keys, database credentials, or configuration files directly alongside their codebase without exposing the plaintext in version control history. The fundamental principle is that only the encrypted versions of these files are committed to Git, while developers can locally decrypt and access the plaintext content using their personal GPG keys. This ensures that sensitive data remains encrypted at rest and during transit through Git operations. <b>git-secret</b> supports collaborative environments by allowing multiple users to be authorized, each identified by their GPG public key ID, granting them decryption capabilities. It offers intuitive commands to initialize a repository for secret management, specify which files to track as secrets, encrypt (hide) them, and decrypt (reveal) them, seamlessly integrating into typical Git workflows to prevent accidental plaintext commits and streamline secure collaboration.


title: CAVEATS
content:
<b>git-secret</b> relies heavily on a properly installed and configured <b>gpg</b> environment, including users having their GPG keys set up and trusted. Key management (generation, revocation, distribution) is external to <b>git-secret</b>. Users must be diligent to avoid accidentally committing plaintext files; while <b>git-secret</b> includes protective measures, manual overrides like <code>git add -f</code> can bypass them. It does not provide integrity checks beyond what Git offers for version control. Diffing encrypted binary files can be unhelpful as the encrypted output is itself binary.


title: KEY CONFIGURATION FILES
content:
<b>git-secret</b> uses two primary files within the <i>.gitsecret/</i> directory to manage secrets:<br><ul><li><i>.gitsecret/paths</i>: This file lists all the relative paths to the files that <b>git-secret</b> is currently tracking and managing as secrets.</li><li><i>.gitsecret/keys</i>: This file stores the GPG public key IDs of all authorized users who have the ability to encrypt and decrypt the secrets in the repository.</li></ul>Both of these files are designed to be committed to the Git repository, allowing the secret configuration to be version-controlled and shared among collaborators.


title: WORKFLOW INTEGRATION
content:
<b>git-secret</b> is designed to integrate smoothly into a standard Git development workflow. After adding files to be managed with <code>git secret add</code> and encrypting them with <code>git secret hide</code>, the encrypted versions are ready to be staged and committed using standard <code>git add</code> and <code>git commit</code> commands. When a new developer clones the repository, they can run <code>git secret reveal</code> (after being added to the <i>.gitsecret/keys</i> file and having their GPG key imported) to decrypt the files for local development. This approach ensures that only the encrypted versions of sensitive data are ever pushed to remote repositories, significantly reducing the risk of accidental data leaks.


title: HISTORY
content:
<b>git-secret</b> emerged as an open-source solution to the persistent challenge of securely storing sensitive configuration data within Git repositories. It offers a straightforward and Git-native approach to managing secrets using the well-established GPG standard. Its development has consistently emphasized simplicity, seamless integration into existing Git workflows, and robust encryption. Over the years, it has gained popularity among developers seeking a lightweight, command-line tool to keep secrets out of their plaintext Git history, benefiting from regular updates and community contributions.


title: SYNOPSIS
content:
<b>git sed</b> [<i>-i</i>] [<i>-E</i> | <i>-r</i>] [<i>-f &lt;scriptfile&gt;</i>] <i>&lt;sed-expression&gt;</i> [<i>&lt;rev-list-options&gt;</i>]


title: PARAMETERS
content:
<b><i>&lt;sed-expression&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The <i>sed</i> script or command to apply to each file blob. For example, <b>"s/old_text/new_text/g"</b>.<br><br><b><i>-i</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Indicates that the changes should be applied 'in-place' to the blobs. This is the implicit behavior for history rewriting operations.<br><br><b><i>-E</i> | <i>-r</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Use extended regular expressions in the <i>sed</i> command (similar to <b>sed -E</b> or <b>sed -r</b>).<br><br><b><i>-f &lt;scriptfile&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Read the <i>sed</i> script from the specified <i>&lt;scriptfile&gt;</i> instead of directly from the command line.<br><br><b><i>&lt;rev-list-options&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Options passed to <i>git rev-list</i> to specify the range of commits whose blobs should be processed. Examples include <b>HEAD</b>, <b>master^..HEAD</b>, <b>--all</b>, or specific paths like <b>--all -- filename.txt</b>.<br><br>


title: DESCRIPTION
content:
<i>git-sed</i> is a conceptual utility, often implemented as a standalone script or wrapper, that allows users to apply <i>sed</i> (stream editor) commands to the content of files (blobs) across Git history. Unlike simple file editing, <i>git-sed</i> operates directly on Git objects, enabling systematic modifications to past commits, branches, or the entire repository history.<br><br>It's commonly used for tasks such as globally renaming variables, updating file paths, or scrubbing sensitive information (like passwords or tokens) that might have been accidentally committed. Because it rewrites history, <i>git-sed</i> creates new commit SHAs, fundamentally altering the repository's past. This operation often leverages Git's internal history-rewriting capabilities like <i>git filter-branch</i> or <i>git filter-repo</i>, providing a more focused interface for text-based transformations. Due to its powerful nature, it must be used with caution, especially in collaborative environments.


title: CAVEATS
content:
<b>1. Not a Built-in Command:</b> <i>git-sed</i> is typically a third-party script or a user-contributed utility, not a command officially shipped with Git itself.<br><b>2. History Rewriting:</b> This command fundamentally alters Git history by creating new commit objects. This changes commit SHAs and can lead to significant problems if not handled carefully.<br><b>3. Collaboration Impact:</b> Rewriting shared history requires coordination with collaborators, as it necessitates force-pushing (e.g., <b>git push --force-with-lease</b>) and may invalidate their local branches.<br><b>4. Performance:</b> On large repositories with extensive history or many files, the operation can be very time-consuming and resource-intensive.<br><b>5. Destructive Potential:</b> Incorrect usage can lead to data loss or a corrupted repository state. Always back up your repository before performing such operations.


title: HOW IT WORKS (CONCEPTUAL)
content:
Conceptually, <i>git-sed</i> iterates through the specified commits. For each commit, it identifies the relevant file blobs. It then applies the provided <i>sed</i> expression to the content of these blobs. If the content changes, a new blob object is created, and subsequently, a new tree object and a new commit object are generated to reflect this change. This process continues through the history, effectively rebuilding the affected portion of the commit graph with the new content.


title: TYPICAL USE CASES
content:
<b>Removing Sensitive Data:</b> Eradicating passwords, API keys, or other confidential information inadvertently committed to history.<br><b>Global Refactoring:</b> Changing variable names, function names, or package paths across an entire project's history.<br><b>Standardizing Content:</b> Enforcing consistent headers, footers, or license blocks in all relevant files.<br><b>Bulk Text Replacement:</b> Any scenario requiring a systematic search-and-replace operation across many versions of a file.


title: HISTORY
content:
<i>git-sed</i> doesn't have a single, official development history as a standalone project. Instead, it emerged as a common pattern and practical solution among Git users who needed to apply consistent text transformations across their repository's history. Various implementations exist as community-contributed scripts, often wrapping Git's built-in history-rewriting commands like <i>git filter-branch</i> (and more recently, <i>git filter-repo</i>) to streamline the process of applying <i>sed</i>-based changes to blobs. Its widespread use reflects a common need in Git workflows for systematic content modification that goes beyond simple commit amendments.


title: SYNOPSIS
content:
git send-pack [--all] [--dry-run] [--force] [--atomic] [--[no-]recurse-submodules] [--thin] [--[no-]verbose] [--[no-]progress] &lt;repository&gt; [&lt;refspec&gt;...]


title: PARAMETERS
content:
<b><b>&lt;repository&gt;</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The URL or path of the remote repository to send objects to.<br><br><b><b>&lt;refspec&gt;...</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;One or more refspecs indicating which local references (e.g., branches or tags) should be sent to the remote, and optionally, which remote reference should be updated. A common format is <code>&lt;local_ref&gt;:&lt;remote_ref&gt;</code>.<br><br><b><b>--all</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Push all branches under <code>refs/heads/</code>, <code>refs/tags/</code> and <code>refs/for/</code> by updating the same name on the remote side.<br><br><b><b>--dry-run</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Perform all operations as if pushing, but do not actually send any data or update remote references.<br><br><b><b>--force</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Override checks that prevent non-fast-forward updates. This can lead to losing data on the remote.<br><br><b><b>--atomic</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Use an atomic transaction on the remote side if the remote repository supports it, ensuring either all references are updated or none are.<br><br><b><b>--[no-]recurse-submodules</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Control whether pushed submodule commits are also pushed to their configured remotes. <code>--no-recurse-submodules</code> overrides the <code>push.recurseSubmodules</code> configuration.<br><br><b><b>--thin</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Request the remote to send a "thin" pack, which omits objects that are already expected to exist on the remote.<br><br><b><b>--[no-]verbose</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Be more verbose (or less verbose) during the operation, showing more details about the negotiation and transfer.<br><br><b><b>--[no-]progress</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show (or hide) progress status messages on the standard error stream during the transfer.<br><br>


title: DESCRIPTION
content:
<code>git-send-pack</code> is a low-level <i>plumbing</i> command in Git, primarily used internally by <code>git push</code> and <code>git fetch</code> for communicating with a remote repository. It's responsible for sending <b>pack files</b>, which are compressed archives of Git objects (commits, trees, blobs, tags), along with reference updates, to a remote <code>git-receive-pack</code> process.<br><br>This command operates on the client side during a push operation. It reads the desired references and objects from the local repository, negotiates with the remote to determine which objects are missing, creates a pack file containing those objects, and then transmits the pack file and reference updates over the network. Users typically interact with the higher-level <code>git push</code> command, which orchestrates the call to <code>git-send-pack</code> behind the scenes. Its direct use is rare, mostly for scripting or debugging advanced Git protocols.


title: CAVEATS
content:
This is a <i>plumbing</i> command, intended for low-level Git operations and scripting, not for typical end-user interaction. <br>Direct use requires a deep understanding of Git's internal protocol and object model. <br>It relies on a compatible <code>git-receive-pack</code> process running on the remote side.


title: PROTOCOL COMMUNICATION
content:
<code>git-send-pack</code> communicates with <code>git-receive-pack</code> on the remote side using Git's "smart protocol". This involves an initial capabilities negotiation, followed by a phase where the local side informs the remote about its current references and desired updates, and then the actual transfer of missing objects within a <b>pack file</b>.


title: PACK FILES
content:
The command's name highlights its primary function: sending <b>pack files</b>. These are highly efficient, compressed archives of Git objects. By sending only the objects that are missing on the remote and grouping them into a single file, Git minimizes network traffic and improves transfer speed significantly.


title: HISTORY
content:
<code>git-send-pack</code> has been a fundamental component of Git's network protocol since its early inception. It's integral to how Git synchronizes repositories over the network efficiently, particularly for push operations. Its development has focused on refining the underlying protocol for robustness and performance, including improvements in pack formats and capabilities negotiation. While the details of the protocol have evolved, its core function as the client-side sender of pack data and reference updates remains consistent.


title: SYNOPSIS
content:
As `git-setup` is not a standard Git command, there is <b>no universal synopsis</b>. <br><br>If it exists on your system, its syntax would depend entirely on its implementation, which could be a simple script or an alias. <br><br>A common pattern for a custom script might be `<i>git-setup [options] [arguments]</i>`, but this is purely speculative and requires local investigation.


title: DESCRIPTION
content:
The `git-setup` command is <b>not a standard Git command</b> distributed with the official Git SCM package. <br><br>It is most likely a <i>custom script</i> or <i>alias</i> created by a user, system administrator, or a particular software distribution to streamline common Git initialization and configuration tasks. As such, its exact functionality, syntax, and options are <b>highly dependent on the specific system</b> where it is found. <br><br>Typically, a script named `git-setup` might automate processes like setting global Git configurations (e.g., user name and email using `git config`), initializing new repositories (`git init`), cloning repositories with specific defaults (`git clone`), or setting up common Git hooks or `.gitignore` rules. <br><br>Users encountering `git-setup` should inspect their local system's aliases, shell scripts in their PATH, or package documentation to understand its specific implementation and usage. Due to its non-standard nature, there are no universal parameters or syntax.


title: CAVEATS
content:
The primary caveat is that `git-setup` is <b>not a standard Git command</b>. Its presence and behavior are entirely specific to the system where it is found. <br><br>Users should exercise caution and ideally inspect the script's source code before executing it, as custom scripts can potentially perform unintended or malicious actions. <br><br>There is no official documentation or support for `git-setup` from the Git project itself.


title: LOCAL SYSTEM INVESTIGATION
content:
If `git-setup` exists on your system, you can often find its definition by checking your shell's aliases (`<i>alias</i>`), looking in your `$PATH` for executables named `git-setup`, or examining common locations for custom scripts like `<i>/usr/local/bin/</i>` or `<i>~/bin/</i>`. Viewing the script's content directly (e.g., `<i>cat $(which git-setup)</i>`) is the most reliable way to understand its specific functionality and usage.


title: HISTORY
content:
There is <b>no specific development history</b> for a standard `git-setup` command, as it does not exist as an official part of the Git project. <br><br>However, the concept of streamlining Git setup — particularly initial configuration (`user.name`, `user.email`), repository creation, and common defaults — has been a recurring theme in the Git community. This often leads users and system administrators to create custom shell scripts or aliases to automate these repetitive tasks, which might be named `git-setup` or similar.


title: SYNOPSIS
content:
This script is not intended for direct user invocation. It is internally sourced by other Git shell scripts.


title: PARAMETERS
content:
<b>(None directly)</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>git-sh-i18n</i> does not accept command-line parameters in the traditional sense, as it is designed to be sourced rather than executed directly. Its functionality is exposed through the shell functions it defines upon sourcing.<br><br>


title: DESCRIPTION
content:
<i>git-sh-i18n</i> is an internal helper script within the Git project, designed to provide internationalization (i18n) capabilities for Git's various shell-based scripts. Instead of being executed directly by the user, it is typically <b>sourced</b> by other Git shell scripts, such as <I>git-sh-setup.sh</I>, to enable message translation for command output and prompts. <br><br>The script defines a set of functions, including <I>gettext_init</I>, <I>gettext_noop</I>, <I>eval_gettext</I>, <I>gettextln</I>, and <I>gettext_printf</I>, which allow shell scripts to retrieve translated strings based on the user's locale settings. Its primary purpose is to integrate GNU <i>gettext</i> functionality into the shell environment that Git commands operate within, ensuring that Git's messages can be presented in multiple languages and improving the user experience for non-English speakers.


title: CAVEATS
content:
<b>Caveats:</b><br><b>1. Internal Use Only:</b> This script is not meant for direct user interaction or execution. Attempting to run it directly will not produce meaningful results for an end-user.<br><b>2. Dependency:</b> Relies on the GNU <i>gettext</i> utilities being installed and accessible on the system for effective internationalization.<br><b>3. Context Dependent:</b> Its functions are designed to operate within the specific context of Git's shell environment.


title: USAGE AND SOURCING
content:
Instead of being executed directly, <i>git-sh-i18n</i> is 'sourced' into other Git shell scripts. This means its functions and variables become available in the environment of the sourcing script. For example, <I>git-sh-setup.sh</I> often sources it to provide i18n capabilities to a wide range of Git commands implemented as shell scripts.


title: KEY FUNCTIONS PROVIDED
content:
Upon sourcing, <i>git-sh-i18n</i> defines several crucial shell functions for internationalization:<br><b>gettext_init:</b> Initializes the <i>gettext</i> text domain and locale for translations.<br><b>gettext_noop:</b> A no-operation function used to mark strings for potential translation without actually translating them at that point.<br><b>eval_gettext:</b> Translates a given string using the established text domain and then evaluates the result.<br><b>gettextln:</b> Translates a string and prints it followed by a newline.<br><b>gettext_printf:</b> Similar to <i>printf</i>, but translates the format string first.<br>These functions streamline the process of displaying localized messages within Git's shell-based commands.


title: HISTORY
content:
<i>git-sh-i18n</i> is part of Git's ongoing efforts to enhance internationalization support for its command-line interface. It was integrated to provide a consistent and robust mechanism for translating messages across various Git shell components, ensuring that users can interact with Git in their preferred language.


title: PARAMETERS
content:
<b>None directly</b><br>&nbsp;&nbsp;&nbsp;&nbsp;This internal command does not expose user-facing command-line parameters. It typically operates on standard input and output, processing all environment variables for substitution. If it acts as a wrapper around the <B>envsubst(1)</B> utility, any parameters would implicitly be passed to the underlying utility, but <B>git-sh-i18n--envsubst</B> itself does not define them as user options.<br><br>


title: DESCRIPTION
content:
The <B>git-sh-i18n--envsubst</B> command is an internal utility within the Git version control system, primarily used by Git's own shell scripts. It is <I>not</I> intended for direct invocation by end-users. Its core function is to perform environment variable substitution, similar to the standalone <B>envsubst(1)</B> utility. This means it reads a stream (typically standard input), identifies patterns like <B>$VARIABLE</B> or <B>${VARIABLE}</B>, and replaces them with the values of the corresponding environment variables. If an environment variable is not set, it's replaced with an empty string.<BR><BR>This helper is crucial for Git's internationalization (<B>i18n</B>) framework. When Git scripts need to display localized messages or paths that contain dynamic information (like user names, repository paths, or specific values), <B>git-sh-i18n--envsubst</B> ensures these placeholders are correctly substituted after the base string has been translated. It often acts as a lightweight wrapper around an available <B>envsubst</B> utility or provides a fallback implementation if <B>envsubst</B> is not present on the system, ensuring portability and consistent behavior across different environments where Git operates.


title: CAVEATS
content:
This command is an internal component of Git's shell scripting infrastructure. It is <B>not</B> designed or supported for direct use by end-users. Its behavior, arguments, and even existence may change without notice between Git versions. Relying on it for external scripting is strongly discouraged, as it could lead to breakage with future Git updates. Its primary purpose is to ensure robust and consistent variable substitution within Git's own internationalization and scripting logic, potentially providing a fallback if the system's native <B>envsubst</B> utility is unavailable or behaves differently.


title: INTERNAL USE CASE
content:
Within Git's source code, <B>git-sh-i18n--envsubst</B> is often called by other Git shell scripts, particularly those involved in displaying messages or generating paths where internationalization is a factor. For instance, after a translated string is retrieved via <B>gettext</B> utilities, this command might be used to substitute any remaining placeholders (e.g., <B>$GIT_DIR</B>, <B>$USER</B>) with their current environment values, ensuring the final output is both localized and contextually accurate.


title: PORTABILITY AND FALLBACK
content:
A key aspect of this command's design is its role in Git's portability. Not all systems have the <B>envsubst(1)</B> utility installed by default, or its behavior might differ slightly. <B>git-sh-i18n--envsubst</B> provides a consistent interface for this crucial operation, either by calling the system's <B>envsubst</B> if available and suitable, or by implementing a simplified version of the substitution logic directly within a shell script. This ensures Git's internal scripts function reliably across a wide range of environments.


title: HISTORY
content:
The functionality encapsulated by <B>git-sh-i18n--envsubst</B> is part of Git's broader efforts to improve internationalization (i18n) and portability across diverse operating systems and shell environments. As Git's codebase matured and its global user base expanded, the need for robust localization and consistent shell scripting became paramount. Components like this were introduced to abstract away system-specific differences in tools like <B>envsubst</B>, ensuring that Git's internal scripts could correctly process and display localized strings with dynamic content regardless of the underlying system utilities available. It reflects a commitment to making Git accessible and stable for users worldwide.


title: PARAMETERS
content:
<b>-c <I>command</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Executes a specific Git command supplied directly on the command line, typically used when invoked by SSH to perform a Git operation (e.g., <i>git-upload-pack</i>, <i>git-receive-pack</i>), rather than waiting for interactive input from the user.<br><br>


title: DESCRIPTION
content:
<i>git-shell</i> is a restricted login shell program designed to provide a secure and controlled environment for users accessing Git repositories via SSH. Its primary function is to prevent arbitrary shell access while allowing legitimate Git operations. When a user's login shell is set to <i>git-shell</i> (typically in <i>/etc/passwd</i> or via the <i>command=</i> option in <i>~/.ssh/authorized_keys</i>), they are limited to executing only Git-specific commands. These include common operations like <i>git push</i> and <i>git pull</i>, as well as the underlying Git transfer protocols such as <i>git-upload-pack</i>, <i>git-receive-pack</i>, and <i>git-upload-archive</i>.<br><br>Any attempt to execute other shell commands or arbitrary programs is rejected by <i>git-shell</i>, ensuring that the server remains secure and only permitted Git activities take place. This makes <i>git-shell</i> an essential component for hosting Git repositories where security and restricted access are paramount. It also offers a mechanism for controlled extensibility by allowing specific custom commands.


title: CAVEATS
content:
<i>git-shell</i> is intended to be a highly restrictive shell. Users whose login shell is set to <i>git-shell</i> will not have access to a general interactive shell prompt and cannot execute arbitrary system commands.<br><br>While it's possible to whitelist custom commands by placing executables in <i>~/git-shell-commands/</i>, this should be done with extreme caution to maintain the security integrity of the server. Misconfigured custom commands can expose vulnerabilities.


title: CUSTOM COMMANDS
content:
Administrators can enable specific non-Git commands to be executed by users configured with <i>git-shell</i>. This is achieved by placing executable files within the <i>~/git-shell-commands/</i> directory. These commands will then be callable by users, either as <i>git <I>command-name</I></i> or directly by their name if invoked via the SSH <i>command=</i> option.


title: INTERACTIVE LOGIN PREVENTION
content:
To prevent users from establishing an interactive shell session with <i>git-shell</i>, an empty file named <i>no-interactive-login</i> can be created within the <i>~/git-shell-commands/</i> directory. The presence of this file forces users to only execute commands via the SSH <i>command=</i> mechanism, ensuring that only Git push/pull operations or explicitly allowed custom commands are possible, and no general interactive user login is permitted.


title: HISTORY
content:
<i>git-shell</i> has been an integral part of the Git ecosystem since its early development. It was conceived to address the crucial need for secure, SSH-based access to Git repositories, a common and preferred method for remote Git operations. Its design has consistently focused on providing a robust mechanism to limit user access to only Git-related commands, thereby mitigating potential security risks associated with granting full shell access on repository hosting servers.


title: PARAMETERS
content:
<b><b>-n</b>, <b>--numbered</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show the number of commits next to the author's name.<br><br><b><b>-s</b>, <b>--summary</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Suppress commit descriptions and show only author names and commit counts.<br><br><b><b>-e</b>, <b>--email</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show the author's email address alongside their name.<br><br><b><b>-w</b>[<i>width</i>], <b>--wrap</b>[=<i>width</i>]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Wrap the second line of the commit description to a specified <i>width</i> (default 76). The <i>width</i> argument is optional.<br><br><b><b>-c</b>, <b>--committer</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Group commits by committer instead of author.<br><br><b><b>--no-merges</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Do not list merge commits.<br><br><b><b>--sort</b>=<key></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sort authors by <i>key</i>. Valid keys include: <b>name</b> (default), <b>email</b>, <b>committerdate</b>, <b>authordate</b>, or <b>commits</b>.<br><br><b><b>-i</b>, <b>--ignore-case</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Ignore case when sorting or filtering authors.<br><br><b><i><revision-range></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Limit the commits to the specified range (e.g., <i>HEAD~5..HEAD</i>, <i>v1.0..master</i>).<br><br><b><b>--</b> <i><path></i>...</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Limit the commits to those that affect the specified paths. Use <b>--</b> to separate paths from revisions.<br><br>


title: DESCRIPTION
content:
<b>git shortlog</b> is a Git command that provides a concise summary of <b>git log</b> output, primarily used for generating release notes or changelogs.<br><br>Unlike <b>git log</b>, which displays individual commit details chronologically, <b>git shortlog</b> groups commits by author, presenting each author's contributions followed by a brief summary of their respective commit messages. This makes it incredibly useful for quickly seeing who contributed what and how much, within a specified revision range.<br><br>By default, authors are sorted alphabetically, and each commit message is displayed on a new line. It supports various options to customize the output, such as showing the number of commits per author (<b>-n</b>), suppressing individual commit messages to show only author names and counts (<b>-s</b>), including email addresses (<b>-e</b>), or sorting authors by their commit count rather than alphabetically (<b>--sort=commits</b>). It can also filter commits by date, author, or message content, similar to <b>git log</b>. This command is invaluable for understanding team contributions and generating high-level project summaries.


title: CAVEATS
content:
By default, <b>git shortlog</b> only considers authors and not committers, unless the <b>-c</b> or <b>--committer</b> option is used.<br>The command's output is optimized for human readability, making it less suitable for direct scripting unless parsing for specific patterns.<br>Sorting by date (<b>--sort=committerdate</b> or <b>--sort=authordate</b>) sorts authors by the date of their <i>first</i> commit, not their <i>last</i> or <i>most recent</i> commit, which might lead to unexpected ordering if not understood.


title: OUTPUT FORMAT
content:
By default, <b>git shortlog</b> outputs a header with the author's name (and optional email/count), followed by a list of their commit messages. Each commit message is typically truncated to its first line.


title: DEFAULT RANGE
content:
Without specifying a <i><revision-range></i>, <b>git shortlog</b> processes all commits reachable from <b>HEAD</b>.


title: INTEGRATION WITH GIT LOG
content:
Many options accepted by <b>git log</b> (like <b>--since</b>, <b>--until</b>, <b>--grep</b>, <b>--author</b>) are also accepted by <b>git shortlog</b> to filter the set of commits before summarization.


title: HISTORY
content:
<b>git shortlog</b> has been a core utility within Git since its early days, designed to provide a quick and meaningful overview of project contributions. Its fundamental purpose of summarizing commit history by author has remained consistent. It evolved alongside Git's logging capabilities, inheriting and enhancing options for filtering and formatting commit information. Its simplicity and effectiveness for generating changelogs or team contribution reports quickly made it a widely used command for project managers and developers alike.


title: PARAMETERS
content:
<b><I>object</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The object(s) to show. This can be a commit hash, a branch name, a tag name, or a path within a tree (e.g., <I>HEAD:path/to/file.txt</I>). If omitted, it defaults to <I>HEAD</I>.<br><br><b>-s, --no-patch</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Suppress the diff output. Only show the commit log message (for commits) or raw object content (for other types).<br><br><b>-p, --patch</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Generate a patch (diff). This is the default when showing a commit object.<br><br><b>--pretty[=<I>format</I>]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Pretty-print the commit log message in a user-specified format. Common formats include <I>oneline</I>, <I>short</I>, <I>medium</I>, <I>full</I>, <I>fuller</I>, <I>email</I>, <I>raw</I>, <I>format:<string></I>.<br><br><b>--stat</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Generate a diffstat output. This shows a summary of changes: files changed, insertions, and deletions.<br><br><b>--name-only</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show only the names of the files that were changed.<br><br><b>--name-status</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show only the names and status (Added, Copied, Deleted, Modified, Renamed, etc.) of changed files.<br><br><b>--oneline</b><br>&nbsp;&nbsp;&nbsp;&nbsp;A shorthand for <I>--pretty=oneline --abbrev-commit</I>, displaying each commit on a single line.<br><br><b>--decorate[=<I>auto|short|full|no</I>]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show ref names (branches, tags) that point to the shown commit.<br><br><b>--notes[=<I>ref</I>]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show notes (if any) associated with the commit.<br><br><b>--color[=<I>when</I>]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Colorize the output. <I>when</I> can be <I>always</I>, <I>never</I>, or <I>auto</I>.<br><br><b>--unified[=<I>n</I>]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Generate diffs with <I>n</I> lines of context instead of the default 3.<br><br><b>-w, --ignore-all-space</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Ignore whitespace when comparing lines.<br><br><b>--binary</b><br>&nbsp;&nbsp;&nbsp;&nbsp;In addition to <I>--patch</I>, output a binary diff that can be applied with <I>git-apply</I>.<br><br><b>--diff-filter=<I>filter</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Limit the files shown in the diff output to those matching the specified filter (e.g., <I>A</I> for Added, <I>D</I> for Deleted, <I>M</I> for Modified, <I>R</I> for Renamed).<br><br>


title: DESCRIPTION
content:
The <b>git-show</b> command is used to display various types of Git objects, including <br><i>commits</i>, <i>trees</i>, <i>blobs</i>, and <i>tags</i>. <br>When given a commit object, it typically shows the log message and the diff that introduces the changes of that commit. <br>For a tree object, it lists the contents of the directory. <br>For a blob (file content) object, it prints the raw content of the file. <br>For an annotated tag object, it shows the tag message and the object it points to. <br><br>It's a versatile command that provides a human-readable way to inspect the state and history of your repository at different points, often used for quickly reviewing changes introduced by a specific commit or examining file contents from the past without checking them out.


title: CAVEATS
content:
When showing a <I>merge commit</I>, <B>git-show</B> by default shows a combined diff against its first parent. To see the diff against other parents or a combined diff, additional <I>--diff-merges</I> options are required. <br>Binary files are usually represented as "Binary files differ" in the output, unless <I>--text</I> or <I>--patch-with-binary</I> is used to force textual or binary diffs.


title: COMMON USAGE EXAMPLES
content:
<b>git show HEAD</b>: Show the latest commit on the current branch.<br><b>git show &lt;commit-hash&gt;</b>: Display details of a specific commit.<br><b>git show &lt;branch-name&gt;</b>: Show the tip commit of a named branch.<br><b>git show &lt;tag-name&gt;</b>: Show an annotated tag object and the commit it points to.<br><b>git show &lt;commit-hash&gt;:path/to/file.txt</b>: Display the content of a specific file at a given commit.<br><b>git show --stat &lt;commit-hash&gt;</b>: Show a summary of changes for a commit without the full diff.<br><b>git show --pretty=oneline --abbrev-commit &lt;commit-hash&gt;</b>: Display a commit on a single line with an abbreviated hash.


title: OBJECT TYPES DISPLAYED
content:
<b>git-show</b> can display information about four primary Git object types:<br><b>Commit objects</b>: Shows commit message, author, date, and diff.<br><b>Tree objects</b>: Lists the names and modes of the files and subdirectories contained within that tree.<br><b>Blob objects</b>: Displays the raw content of the file (blob).<br><b>Tag objects</b>: For annotated tags, shows the tag message, tagger, and the object it points to (usually a commit).


title: HISTORY
content:
The <B>git-show</B> command has been a fundamental part of Git since its early days, serving as a high-level interface to inspect objects, building upon lower-level commands like <B>git-cat-file</B>. Its core functionality for displaying commit details and diffs has remained consistent, with ongoing enhancements focused on adding more options for output formatting and diff presentation.


title: SYNOPSIS
content:
<b>git show-branch</b> [--topic] [--independent] [--date-order] [--list] [--merge-base] [--stdin | &lt;rev&gt;...]


title: PARAMETERS
content:
<b>-r, --rev-output-reverse</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show commits in reverse order of output.<br><br><b>-g, --more</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show more commits than the default limit (usually 20). Can be specified multiple times.<br><br><b>-a, --all</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show all refs, not just heads.<br><br><b>-c, --color</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show colored output (default is to use color when outputting to a TTY).<br><br><b>--no-color</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Turn off colored output, even if default is color.<br><br><b>-i, --independent</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show only branches that are not merged into any other specified branches.<br><br><b>-t, --topic</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show only topic branches (those not merged into any other specified branch).<br><br><b>-s, --sparse</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show a more concise output, omitting commit messages and focusing on ancestry.<br><br><b>-m, --merge-base</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Find and show the common merge base of the specified revisions.<br><br><b>--list</b><br>&nbsp;&nbsp;&nbsp;&nbsp;List the branches that contain current HEAD, or the given revision if specified. Does not show history.<br><br><b>--stdin</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Read revisions from standard input, one per line.<br><br><b>--date-order</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sort commits by commit date. Default is topological order.<br><br><b>--topo-order</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sort commits by topological order (parent before child). This is the default.<br><br><b>--no-name</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Do not show branch names in the output.<br><br><b>--sha1-name</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show SHA1 of the branch head instead of the name.<br><br><b>--current</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Mark the current branch (HEAD) specially in the output.<br><br><b>--reflog</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Include reflog entries in the displayed revisions.<br><br><b>&lt;rev&gt;...</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify one or more revisions (e.g., branch names, commit SHAs) to display. If none are specified, all local heads are shown.<br><br>


title: DESCRIPTION
content:
The <i>git-show-branch</i> command is a powerful tool for visualizing the commit ancestry of multiple branches, making it easier to understand how they diverge and merge. It displays a summary of the commits on the named branches that are not found on the default branch (or common ancestor).<br><br>Instead of showing a linear log, <i>git-show-branch</i> provides a columnar output, where each column represents a specified branch. Commits are marked with symbols to indicate their presence and relationship:<br><b>!</b> indicates the tip of a topic branch.<br><b>*</b> indicates a common commit reachable from multiple branches.<br><b>+</b> indicates a commit unique to a specific branch.<br> (space) indicates the commit is not present or not unique to that column.<br><br>It's particularly useful for reviewing proposed merges, identifying commits unique to a feature branch before integration, or understanding complex repository histories with many active branches.


title: CAVEATS
content:
The output of <i>git-show-branch</i> can become dense and difficult to read when dealing with a very large number of branches or a deep commit history. Its primary strength lies in visualizing divergence from a common ancestor, rather than a full chronological log of all commits. For detailed commit information, <i>git log</i> is more appropriate.


title: OUTPUT FORMAT
content:
The output uses a specific format to convey information:<br>Each column represents a specified branch.<br>An <b>!</b> in a column indicates the tip of that branch.<br>A <b>*</b> indicates a common commit reachable from multiple specified branches.<br>A <b>+</b> indicates a commit unique to the branch represented by that column.<br>A blank space indicates the commit is not reachable from that branch or is not unique to it.<br>The commit subject line is preceded by the names of the branches whose tips are ancestors of the commit and, if applicable, the commit SHA-1 (if --sha1-name is used) and a short summary of the commit message.


title: EXAMPLES
content:
<b>git show-branch master develop feature/x</b><br>Shows the commits on 'master', 'develop', and 'feature/x' branches, highlighting their common history and unique commits.<br><br><b>git show-branch --merge-base HEAD origin/master</b><br>Displays the common merge base commit between the current HEAD and 'origin/master'.<br><br><b>git show-branch --list</b><br>Lists all branches that contain the current HEAD commit.


title: HISTORY
content:
The <i>git-show-branch</i> command has been a fundamental part of Git since its early days, addressing the crucial need for developers to visually understand the relationships and divergence points between different lines of development. Its design emphasizes a clear, column-based representation of commit ancestry, making it an invaluable tool for complex branching workflows, even as other visualization tools have emerged.


title: PARAMETERS
content:
<b><i>pack-index-file</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The path to the binary pack index file (<code>.idx</code>) whose contents are to be displayed. This file is read from standard input (stdin).<br><br>


title: DESCRIPTION
content:
The <i>git-show-index</i> command is a low-level <b>plumbing</b> command within Git, primarily used for inspecting the binary contents of a Git pack index file (<code>.idx</code>).<br><br>Pack index files accompany Git packfiles (<code>.pack</code>), which are highly compressed archives storing multiple Git objects (commits, trees, blobs, tags). The <code>.idx</code> file serves as an index, mapping object IDs (SHA-1 or SHA-256 hashes) to their respective offsets within the corresponding <code>.pack</code> file. This allows Git to quickly locate and decompress specific objects without scanning the entire packfile.<br><br>As a plumbing command, <i>git-show-index</i> is not intended for general daily use by end-users. Instead, it's a tool for Git developers, scripting, or debugging repository corruption or packfile issues. It reads the raw index data from standard input and typically outputs the SHA-1 or SHA-256 hashes of the objects contained within that index.


title: CAVEATS
content:
This is a <b>plumbing</b> command, meaning it's an internal tool primarily for Git's own operations or for developers debugging Git itself. It reads binary data from standard input and its output is typically just a list of object SHAs, which might require further processing for human readability or advanced analysis. It does not accept command-line options for filtering or formatting beyond what its internal logic provides.


title: INPUT
content:
The command expects the raw, binary content of a Git pack index file (<code>.idx</code>) to be piped to its standard input. For example, to inspect <code>objects/pack/pack-&lt;hash&gt;.idx</code>, you would typically use: <code>cat objects/pack/pack-&lt;hash&gt;.idx | git-show-index</code> or <code>git-show-index &lt; objects/pack/pack-&lt;hash&gt;.idx</code>.


title: OUTPUT
content:
For each object listed in the provided pack index, <i>git-show-index</i> outputs its object ID (SHA-1 or SHA-256 hash) on a new line. The output is a plain list of hashes, suitable for piping to other commands or for programmatic processing.


title: HISTORY
content:
The <i>git-show-index</i> command emerged early in Git's development, specifically around the time packfiles and their corresponding index files were introduced (roughly 2005-2006). Packfiles were a crucial innovation for Git, vastly improving storage efficiency and transfer performance by consolidating multiple objects into a single compressed file. As Git's internal data structures became more complex, tools like <i>git-show-index</i> became necessary for low-level inspection, debugging, and verification of these new formats. Its design as a simple stdin-to-stdout plumbing command reflects its role as a fundamental building block in Git's core toolkit.


title: SYNOPSIS
content:
<tt>git show-merged-branches [<I>target_branch</I>] [<I>options</I>]</tt><br><br><i>Note: As this is a user-defined script, the exact syntax and available options are implementation-dependent.</i>


title: PARAMETERS
content:
<b><tt>[<I>target_branch</I>]</tt></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Optional</i>. The name of the branch to check against. If omitted, the command typically defaults to the current <tt>HEAD</tt> branch.<br><br><b><tt>--remote</tt> or <tt>-r</tt></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Optional</i>. Includes remote-tracking branches in the output, showing which remote branches have been merged into the specified <tt>target_branch</tt>.<br><br><b><tt>--dry-run</tt> or <tt>-n</tt></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Optional</i>. When the script includes deletion capabilities, this option shows which branches would be deleted without actually performing the deletion.<br><br><b><tt>--delete</tt> or <tt>-d</tt></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Optional</i>. Some advanced implementations include this option to automatically delete the identified merged branches. <i>Use with caution.</i><br><br>


title: DESCRIPTION
content:
The <b><tt>git-show-merged-branches</tt></b> command is not a built-in Git command but rather a commonly found user-defined script or Git alias. Its primary purpose is to identify and display local or remote branches that have already been merged into a specified target branch (by default, the current <tt>HEAD</tt>). This utility is invaluable for repository cleanup, as it helps developers quickly pinpoint branches that are safe to delete because their changes have been integrated into the main development line. <br><br>While its exact implementation can vary, it typically leverages Git's native <tt>git branch --merged</tt> functionality, often combined with filtering to exclude protected branches like <tt>main</tt>, <tt>master</tt>, or <tt>develop</tt>. Its widespread use highlights a common need within Git workflows to maintain a clean and manageable branch history, preventing clutter from stale, already-integrated feature or hotfix branches.


title: CAVEATS
content:
This command is <i>not</i> a standard Git command distributed with Git itself. Its existence, behavior, and available options depend entirely on whether a user or system administrator has created it as a custom script or Git alias. Therefore, it may not be available on all systems or in all Git environments, and its output or functionality might differ significantly between implementations. Users should verify its presence and examine its source code if in doubt.


title: TYPICAL IMPLEMENTATION
content:
A common way to implement <tt>git-show-merged-branches</tt> involves piping the output of <tt>git branch --merged</tt> through <tt>grep</tt> to filter out the current branch and protected branches (like <tt>main</tt>, <tt>master</tt>, <tt>develop</tt>). For remote branches, <tt>git branch -r --merged</tt> might be used. An example alias definition could look like: <br><br> <tt>git config --global alias.sbm '!git branch --merged | egrep -v "(^\*|main|master|develop)"'</tt> <br><br> More sophisticated scripts might include options for deleting branches after listing them, often incorporating <tt>xargs git branch -d</tt> or <tt>git push origin --delete</tt> for remote branches.


title: HISTORY
content:
The concept behind <tt>git-show-merged-branches</tt> emerged organically within the Git community as a response to the need for efficient branch management and repository hygiene. As Git repositories grow and feature branches proliferate, the manual tracking of merged branches becomes tedious. Developers frequently shared personal scripts and aliases to automate this cleanup, leading to a de facto standard functionality, even without a formal inclusion in the Git core. Its evolution is thus a testament to community-driven problem-solving in the Git ecosystem, with various slightly different implementations addressing the same core problem of identifying stale, merged branches.


title: SEE ALSO
content:
<tt>git-branch(1)</tt>: For listing, creating, and deleting branches. The underlying mechanism for identifying merged branches., <tt>git-merge(1)</tt>: For integrating changes from one branch into another, which is the prerequisite for a branch to be considered merged., <tt>git-config(1)</tt>: For configuring Git aliases, which is a common way this command is defined (e.g., <tt>git config --global alias.show-merged-branches '!f() { git branch --merged "${1:-HEAD}" | grep -v "\*|main|master|develop" ...; }; f'</tt>).


title: SYNOPSIS
content:
<br><b>git show-ref</b> [--head] [--dereference] [--abbrev[=&lt;n&gt;]] [--hash] [--exclude-existing[=&lt;pattern&gt;]] [--verify] [--quiet] [--no-warn] [--print-names] [&lt;pattern&gt;...]


title: PARAMETERS
content:
<b>--head</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show the HEAD reference, if it exists, even if it does not match a pattern.<br><br><b>-d | --dereference</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Dereference tags into object IDs. This shows the object ID that a tag points to, in addition to the tag itself.<br><br><b>-s | --sha1</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Only show the SHA-1 hash, not the full reference name. (This is often the default behavior without --print-names).<br><br><b>--verify</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Verify that each ref passed as a pattern exists and is a valid object. Exits with non-zero status if any ref is not found or invalid.<br><br><b>-q | --quiet</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Do not print any error messages or warnings to stderr, useful when used with --verify.<br><br><b>--no-warn</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Suppress warnings when a specified pattern does not match any reference.<br><br><b>--print-names</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show the names of the refs even if they are not matching a pattern. (This implies --verify if patterns are given).<br><br><b>--hash</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Only show the hash, not the name (opposite of --print-names). Implies --abbrev=40 unless --abbrev is specified.<br><br><b>--abbrev[=&lt;n&gt;]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Abbreviate the object names (SHA-1 hashes) to &lt;n&gt; characters, or the default length if &lt;n&gt; is omitted.<br><br><b>--exclude-existing[=&lt;pattern&gt;]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Only show refs that do not exist locally. If a pattern is provided, it must match the refname exactly for it to be excluded.<br><br><b>--no-exclude-existing</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Do not exclude existing refs. Useful for overriding a global config or previous --exclude-existing.<br><br><b>&lt;pattern&gt;...</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Optional patterns to filter the references. Only refs matching any of the given patterns will be shown. Patterns typically start with 'refs/heads/', 'refs/tags/', 'refs/remotes/', etc.<br><br>


title: DESCRIPTION
content:
<br>The <i>git show-ref</i> command is a low-level utility used to display the references (branches, tags, remote-tracking branches, etc.) and their corresponding object IDs (SHA-1 hashes) in a Git repository. It's primarily designed for scripting and internal Git operations, offering a raw view of the repository's reference structure.<br>By default, it lists all references found under <i>refs/</i>, including loose references (files) and packed references (in <i>.git/packed-refs</i>). The output format is typically a SHA-1 hash followed by the full reference name.<br>Unlike higher-level commands like <i>git branch</i> or <i>git tag</i>, <i>git show-ref</i> provides direct access to the underlying reference data, making it suitable for tasks that require parsing reference information without additional formatting or filtering. It can be used to check for the existence of specific references or to retrieve their associated commit, tag, or tree IDs.


title: CAVEATS
content:
<br><i>git show-ref</i> only displays references known locally by the repository. It does not communicate with remote repositories to fetch or update reference information; for remote references, consider using <i>git ls-remote</i>.<br>The output format is highly stable, making it ideal for parsing in scripts, but generally less human-readable than higher-level commands like <i>git branch -v</i>.<br>Without specific patterns, it can list a very large number of references in a busy repository, which might be slow.


title: OUTPUT FORMAT
content:
By default, <i>git show-ref</i> outputs lines in the format: <br><i>&lt;SHA-1&gt; &lt;refname&gt;</i> <br>For example: <br><i>a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0 refs/heads/main</i> <br>When <i>--dereference</i> is used, for an annotated tag, a second line is added with the object it points to: <br><i>a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0 refs/tags/v1.0</i> <br><i>b0a9f8e7d6c5b4a3e2d1c0b9a8f7e6d5c4b3a210 refs/tags/v1.0^{}</i> (where the second hash is the object the tag points to).


title: PATTERN MATCHING
content:
Patterns provided to <i>git show-ref</i> are typically full or partial reference names, often starting with standard Git prefixes like <i>refs/heads/</i>, <i>refs/tags/</i>, <i>refs/remotes/</i>, etc. For example, <i>git show-ref refs/heads/</i> will list all local branches. Patterns can also be full refnames like <i>refs/heads/main</i>. The patterns are implicitly anchored to the beginning, meaning 'foo' will match 'refs/heads/foo' but not 'refs/heads/foobar'.


title: HISTORY
content:
<br><i>git show-ref</i> has been a core part of Git since its early days, serving as a fundamental building block for scripting and internal operations that require direct access to Git's reference infrastructure. It provides a simple, consistent interface to list and verify references, complementing higher-level commands that offer more user-friendly interactions. Its design prioritizes machine readability and robustness, making it a reliable tool for automating Git workflows.


title: PARAMETERS
content:
<b><I>&lt;tree-ish&gt;</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The object to inspect. This can be a tree object's hash, or a commit or tag object that ultimately resolves to a tree. It specifies which tree's contents should be displayed.<br><br><b>-d</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Only show tree entries (subdirectories) and do not show blob entries (files). This helps in focusing on the directory structure itself.<br><br><b>-r</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Recursively list the contents of sub-trees. This option allows for a deep listing of all files and directories nested within the specified <I>tree-ish</I>.<br><br><b>--name-only</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show only the names of the entries, one per line. This omits mode, type, and object hash for a more concise output, useful for scripting.<br><br><b>--full-name</b><br>&nbsp;&nbsp;&nbsp;&nbsp;When used with <I>-r</I>, show the full path of the entries from the root of the repository, rather than just their base names within their respective sub-directories.<br><br><b>-t</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show the type of object ('blob', 'tree', or 'commit') alongside its mode and name, providing more context about each entry.<br><br><b>-l</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show the size of blob entries in bytes. This option is useful for understanding the disk space consumed by files within the tree, especially for large repositories.<br><br><b>-z</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Terminate entries with a NUL character instead of a newline. This is highly beneficial for scripting, particularly when handling paths that may contain unusual characters (like spaces or newlines), by allowing unambiguous parsing.<br><br>


title: DESCRIPTION
content:
The <I>git-show-tree</I> command was an early, low-level Git plumbing command used to inspect the contents of a Git tree object. A tree object in Git represents a directory's state at a specific point in time, containing references to other tree objects (subdirectories) and blob objects (files).<br><br>Historically, <I>git-show-tree</I> served a purpose similar to the <I>ls</I> command in a filesystem, listing the entries within a given tree object. This included displaying their mode (permissions), type (blob, tree, or commit), Git object SHA-1 hash, and name. However, for consistency with other Git commands, particularly <I>git ls-files</I>, this command was officially renamed to <I>git ls-tree</I>.<br><br>In modern Git versions, <I>git-show-tree</I> is no longer a directly callable command and will typically result in an error or 'command not found'. Its functionality has been fully superseded by <I>git ls-tree</I>, which provides identical and enhanced capabilities, serving as the standard method for listing tree contents.


title: CAVEATS
content:
<I>git-show-tree</I> is a deprecated and internal Git command. It is not available for direct use in modern Git distributions, having been fully replaced by <I>git ls-tree</I>. Attempting to run <I>git-show-tree</I> directly on a current Git installation will almost certainly result in a 'command not found' or similar error. Users interested in listing tree contents should always use <I>git ls-tree</I>.


title: PLUMBING COMMAND
content:
<I>git-show-tree</I> (and its modern successor <I>git ls-tree</I>) is categorized as a 'plumbing' command within Git. Plumbing commands are low-level operations that directly interact with Git's internal data structures, such as tree objects, blob objects, and commit objects. They are primarily designed for scripting, automation, or advanced debugging purposes, offering granular control over the repository's components. This stands in contrast to 'porcelain' commands (e.g., <I>git commit</I>, <I>git status</I>), which are high-level, user-friendly commands built upon these underlying plumbing functionalities for everyday repository management.


title: HISTORY
content:
The <I>git-show-tree</I> command was one of the earliest plumbing commands in Git, a foundational tool for inspecting the repository's object database. It was an integral part of Git from its inception, developed by Linus Torvalds himself. The renaming to <I>git ls-tree</I> occurred to standardize Git's command-line interface, aligning its nomenclature with other list-related commands like <I>git ls-files</I> and making it more intuitive for users familiar with Unix-like <I>ls</I> utilities. Despite the change in name, its core functionality of listing tree contents remains a vital component of Git's plumbing layer.


title: SYNOPSIS
content:
<i>git branch</i> [-r | -a] [--no-merged [<I>&#60;commit&#62;</I>]] [--sort=<I>&#60;key&#62;</I>] [--color[=<I>&#60;when&#62;</I>]] [--column[=<I>&#60;options&#62;</I>]]


title: PARAMETERS
content:
<b><b>--no-merged [<I>&#60;commit&#62;</I>]</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Lists branches whose tips are not reachable from the specified <i><I>&#60;commit&#62;</I></i> (or HEAD if omitted) via a merge. These are branches that contain commits not yet integrated into the target.<br><br><b><b>-r</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Lists remote-tracking branches instead of local ones.<br><br><b><b>-a</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Lists both remote-tracking and local branches.<br><br><b><b>--sort=<I>&#60;key&#62;</I></b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sorts the output branches by the specified <i><I>&#60;key&#62;</I></i> (e.g., 'committerdate', 'refname').<br><br><b><b>--color[=<I>&#60;when&#62;</I>]</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables colored output. <i><I>&#60;when&#62;</I></i> can be 'always', 'never', or 'auto'.<br><br><b><b>--column[=<I>&#60;options&#62;</I>]</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays branches in columns. <i><I>&#60;options&#62;</I></i> can include 'always', 'never', 'auto', 'row', 'dense', 'clear', etc.<br><br>


title: DESCRIPTION
content:
<i>git-show-unmerged-branches</i> is <i>not a standard Git command</i>. The functionality implied by this name—identifying branches that have not yet been fully integrated into another branch—is natively provided by the <i>git branch</i> command using its <i>--no-merged</i> option. <br><br>When executed as <i>git branch --no-merged</i> (or <i>git branch --no-merged <I>&#60;commit&#62;</I></i>), the command lists all branches whose tips are not reachable from the specified <i><I>&#60;commit&#62;</I></i> (or the current HEAD if no commit is specified) via merge commits. This effectively shows branches that contain unique work that has not yet been incorporated into the target branch. It is a crucial tool for developers to track ongoing feature work, identify stale branches, or clean up completed branches in a repository.


title: CAVEATS
content:
<i>git-show-unmerged-branches</i> itself is <i>not a standard Git command</i> distributed with Git. Any command with this exact name is likely a custom script or an alias created by a user or distribution. <br><br>The behavior of <i>git branch --no-merged</i> depends on the current HEAD or the explicitly provided <i><I>&#60;commit&#62;</I></i>. It lists branches that have commits <i>not yet merged</i> into the target branch. A branch might appear in the list even if parts of it were merged, as long as its tip has unmerged commits relative to the target.


title: COMMON ALIASES/SCRIPTS
content:
Many users create custom Git aliases or scripts named <i>show-unmerged</i> or similar to quickly access this functionality. For example, a common alias is <i>git config alias.unmerged 'branch --no-merged'</i>. More complex scripts might filter by age, author, or allow for interactive deletion.


title: USE CASES
content:
Identifying branches that are ready for deletion, tracking long-running feature branches, finding branches that need to be rebased, and cleaning up local repositories are common uses for this command.


title: HISTORY
content:
The core <i>git branch</i> command has been a fundamental part of Git since its inception. The <i>--no-merged</i> and <i>--merged</i> options were introduced early in Git's development to provide robust capabilities for managing and identifying the merge status of branches, greatly simplifying repository maintenance tasks.


title: PARAMETERS
content:
<b>--format=<<i>format</i>></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the output format. Common options include <i>human</i> (default), <i>json</i>, and <i>csv</i>.<br><br><b>--threshold=<<i>threshold</i>></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets a general size or count <i>threshold</i>. Any metric exceeding this value will be flagged in the output.<br><br><b>--json</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Outputs results in a machine-readable JSON format, suitable for scripting and automated analysis.<br><br><b>--no-progress</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Suppresses the progress indicator shown during repository analysis, useful for non-interactive scripts.<br><br><b>--no-walk</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Disables walking the commit graph. This can significantly speed up analysis by only examining loose and packed objects, but provides less comprehensive data related to history depth.<br><br><b>--tags</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Includes all tags when analyzing the repository, expanding the scope beyond just branches.<br><br><b>--branches</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Includes all branches when analyzing the repository (default behavior if no <i>commitish</i> is specified).<br><br><b>--all</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Analyzes all references (<i>branches</i> and <i>tags</i>), providing a complete repository overview.<br><br><b><<i>commitish</i>></b><br>&nbsp;&nbsp;&nbsp;&nbsp;One or more commit hashes, branch names, or tags to limit the scope of the analysis to specific parts of the repository history. If omitted, all local branches are analyzed.<br><br>


title: DESCRIPTION
content:
<b>git-sizer</b> is a powerful tool for analyzing a Git repository's size and internal characteristics, helping identify potential performance bottlenecks or problematic growth patterns. It thoroughly examines various aspects, including the total number of objects, their combined packed size, the depth of the commit graph, and the size of individual blobs and trees. This utility is indispensable for repository administrators and developers aiming to proactively manage repository health, pinpoint excessively large files (often candidates for Git LFS), or understand the root causes of slow operations like cloning or garbage collection. By providing detailed, actionable metrics, <b>git-sizer</b> facilitates the optimization of repository structure, ensuring more efficient and manageable Git workflows.


title: CAVEATS
content:
Analyzing very large repositories without the <i>--no-walk</i> option can be time-consuming due to the extensive graph traversal.<br>The reported sizes primarily reflect <i>packed</i> object sizes, which may differ from the actual on-disk space occupied by the Git repository.<br><b>git-sizer</b> identifies potential issues but does not provide direct solutions; it guides further investigation or action (e.g., using Git LFS for large files or <b>git-gc</b> for optimization).<br>It requires a local clone of the repository to perform its analysis; it cannot directly analyze remote repositories.


title: KEY METRICS MEASURED
content:
<b>git-sizer</b> reports on a wide array of metrics, providing a comprehensive view of repository structure and content:<br>- <i>Total Objects</i> and <i>Total Packed Size</i>: Overall repository bulk.<br>- <i>Maximum Blob Size</i> and <i>Maximum Tree Size</i>: Identification of large individual files or deeply nested directory structures.<br>- <i>Maximum Commit Depth</i> and <i>Maximum Tag Depth</i>: Indicators of long history or deep reference chains.<br>- <i>Maximum Path Length</i>: Helps identify files with excessively long absolute paths within the repository.<br>These metrics collectively help pinpoint specific areas of concern that might impact performance, maintainability, or compatibility with various file systems.


title: CUSTOMIZABLE THRESHOLDS
content:
A powerful feature of <b>git-sizer</b> is the ability to define custom thresholds for individual metrics (e.g., <i>--max-blob-size-threshold=100MB</i>) or apply a general threshold to flag any metric exceeding a specified limit. This feature significantly enhances the utility of the tool by allowing users to quickly identify and focus on areas that violate their defined repository health policies, performance benchmarks, or organizational standards, streamlining the identification of problematic assets.


title: HISTORY
content:
<b>git-sizer</b> emerged as an external Git command, independently developed to address the growing need for repository size analysis in increasingly large Git projects. Its popularity surged as organizations faced performance challenges with massive repositories, particularly concerning cloning times and general repository bloat. It fills a critical gap in the Git ecosystem by offering detailed insights into repository health, empowering users to proactively identify and manage growth patterns. Its ongoing development focuses on enhancing the accuracy and utility of its diagnostic capabilities within modern Git workflows.


title: SYNOPSIS
content:
Since <i>git-squash</i> is not a standalone command, its functionality is typically achieved via <b><i>git rebase -i</i></b>.<br><br><b><i>git rebase -i <I>[commit-ish]</I></i></b><br><b><i>git rebase -i <I>HEAD~<N></I></i></b><br><br>Where <i><N></i> is the number of commits from HEAD to include in the interactive rebase, and <i><I>commit-ish</I></i> specifies the commit before the series you want to rebase. When in interactive mode, you mark commits with 'squash' or 'fixup'.


title: PARAMETERS
content:
<b>-i, --interactive</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Required to enter interactive rebase mode. This opens an editor with a list of commits in your rebase range, allowing you to specify actions for each commit, including 'squash' or 'fixup'.<br><br><b>squash</b><br>&nbsp;&nbsp;&nbsp;&nbsp;An action keyword used within the interactive rebase editor. Marks the current commit to be combined with the previous commit, merging their commit messages. Git will prompt you to edit the combined message.<br><br><b>fixup</b><br>&nbsp;&nbsp;&nbsp;&nbsp;An action keyword used within the interactive rebase editor. Similar to 'squash', it combines the current commit with the previous one, but discards the current commit's log message, using only the previous commit's message. No message editing prompt occurs.<br><br><b><commit-ish></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the commit before the range of commits you want to rebase (and potentially squash). All commits from this <i><I>commit-ish</I></i> to HEAD will be presented in the interactive todo list.<br><br><b>HEAD~<N></b><br>&nbsp;&nbsp;&nbsp;&nbsp;A common way to specify the range for interactive rebase. It indicates the last <i><N></i> commits from the current HEAD that you want to rebase and potentially squash.<br><br>


title: DESCRIPTION
content:
<i>git-squash</i> is not a native Git command; rather, it commonly refers to the process of combining multiple Git commits into a single, more meaningful commit. This powerful operation is most frequently achieved using <b><i>git rebase -i</i></b> (interactive rebase). The primary purpose of squashing commits is to clean up a branch's history, making it more linear, understandable, and easier to review. For instance, a series of incremental commits (e.g., 'fix typo', 'add feature part 1', 'fix bug', 'add feature part 2') can be consolidated into a single, comprehensive commit like 'Implement Feature X'. This practice helps maintain a clean, concise project history, particularly before merging a feature branch into main development lines like <i>main</i> or <i>master</i>, contributing to cleaner pull requests and easier future debugging.


title: CAVEATS
content:
Squashing commits rewrites Git history. This means the SHA-1 hashes of the squashed commits will change. Therefore:<br>1. <b>Do not squash commits that have already been pushed to a shared, public repository</b> unless you coordinate with all collaborators, as it will require a force push (<b><i>git push --force-with-lease</i></b> or <b><i>git push --force</i></b>) and can lead to merge conflicts for others.<br>2. Always be cautious when rewriting history. If unsure, create a backup branch before starting the rebase.<br>3. Ensure the final squashed commit retains all necessary changes and a clear, descriptive commit message.


title: WHEN TO SQUASH
content:
Squashing is ideal for:<br>1. Cleaning up local feature branches before merging them into a main branch.<br>2. Combining several small, incremental commits (e.g., 'WIP', 'fix typo', 'minor refactor') into a single, logical unit of work.<br>3. Simplifying pull requests by presenting a clean, easy-to-review history to maintainers.<br>4. Reverting complex changes more easily by having fewer, larger commits to revert.


title: INTERACTIVE REBASE PROCESS
content:
When you run <b><i>git rebase -i</i></b>, Git opens your default text editor with a 'todo list'. Each line represents a commit, prefixed with 'pick'. To squash:<br>1. Change 'pick' to 'squash' (or 's') for commits you want to merge into the <i>previous</i> commit.<br>2. Change 'pick' to 'fixup' (or 'f') for commits you want to merge into the <i>previous</i> commit, discarding the current commit's message.<br>3. Save and close the editor. Git will then apply the changes, potentially opening another editor for you to refine the combined commit message(s).


title: HISTORY
content:
The concept of squashing commits has been an integral part of Git's powerful interactive rebase functionality since its inception. While specific aliases or scripts named <i>git-squash</i> might appear in various workflows, the underlying capability to combine commits through 'squash' and 'fixup' commands within <i>git rebase -i</i> has been a core feature of Git for many years, enabling developers to maintain clean and linear project histories.


title: PARAMETERS
content:
<b>-r, --recursive</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Recursively stamp all files in the current directory and its subdirectories.<br><br><b>-v, --verbose</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enable verbose output, showing which files are being processed.<br><br><b>-h, --help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display a help message and exit.<br><br><b>--version</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show the program's version number and exit.<br><br>


title: DESCRIPTION
content:
<I>git-stamp</I> is a utility designed to synchronize the modification and access times (mtime and atime) of files in a Git repository with the last commit timestamp recorded by Git. This tool is particularly useful in build environments where incremental builds rely heavily on file modification times to determine whether a file needs to be recompiled or rebuilt. By default, Git doesn't preserve file timestamps upon checkout, which can lead to unnecessary rebuilds or incorrect caching.<br><br><I>git-stamp</I> addresses this by applying the commit timestamp of the last modification to the actual file's metadata. It can operate on specified files or recursively on all files in the current directory. This ensures that the filesystem's view of file modification times accurately reflects their last change within the Git history, thereby optimizing build processes and ensuring consistency across different development environments.


title: CAVEATS
content:
<b>Local Metadata Only:</b> <I>git-stamp</I> modifies only the local file metadata (timestamps) and does not affect the Git repository's history or content.<br><b>Filesystem Compatibility:</b> May encounter limitations or behave unexpectedly on certain network file systems or non-standard file systems that handle timestamps differently.<br><b>Untracked/Ignored Files:</b> It only processes files tracked by Git. Untracked or ignored files will not be stamped.<br><b>Dependency on Git:</b> The tool relies on the Git command-line utility being available and properly configured in the environment.


title: HOW IT WORKS
content:
<I>git-stamp</I> fetches the Unix timestamp of a file's last modification from Git's history using commands like <b>git log --pretty=format:%at -1 <I>filename</I></b>. It then applies this timestamp to the actual file's modification and access times using system calls, effectively 'touching' the file with the Git-derived timestamp. This process ensures the filesystem's metadata accurately reflects the file's last change within the Git repository.


title: TYPICAL USE CASES
content:
Primarily utilized within build systems (e.g., Make, Ninja, Bazel) to ensure that only files truly modified according to Git history are reprocessed, optimizing build times. It also helps maintain consistent build outputs across various development environments and prevents unnecessary full rebuilds when checking out different Git revisions.


title: HISTORY
content:
<I>git-stamp</I> emerged as a practical solution to a common challenge in development workflows: the disconnect between Git's internal timestamping and a filesystem's modification times. While not part of the official Git distribution, standalone implementations like 'srid/git-stamp' (first seen around 2012-2013) address the need for accurate file timestamps in build systems. Its development is driven by the demand for efficient incremental builds and consistent environments, where precise file modification times are critical.


title: SYNOPSIS
content:
<b>git standup</b> [-d <I>days</I>] [-r <I>repo</I>] [-b <I>branch</I>] [-s] [-g] [-a] [-L] [-m|-M|-x|-j|-t] [-c|-C] [-D <I>date</I>] [--email <I>email</I>] [--author <I>author</I>] [--remote] [--pull] [--stashes] [--grep <I>pattern</I>] [--exclude <I>pattern</I>] [--include <I>pattern</I>] [--git-log-options <I>options</I>] [--group-by <I>type</I>] [-h] [-v]


title: PARAMETERS
content:
<b>-d <I>days</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show commits from the last <I>N</I> days.<br><br><b>-r <I>repo</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Limit report to commits in the specified repository path.<br><br><b>-b <I>branch</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Limit report to commits on the specified branch.<br><br><b>-s</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Suppress <I>git status</I> output for a cleaner view.<br><br><b>-g</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Suppress <I>git branch</I> output.<br><br><b>-a</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show all commits, not just those by the current user.<br><br><b>-L</b><br>&nbsp;&nbsp;&nbsp;&nbsp;List all local repositories discovered, without showing commits.<br><br><b>-m</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Format output in Markdown.<br><br><b>-M</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Format output in Markdown, including full commit messages.<br><br><b>-x</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Output report in XML format.<br><br><b>-j</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Output report in JSON format.<br><br><b>-t</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Output a plaintext summary table.<br><br><b>-c</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Only list repositories that contain commits.<br><br><b>-C</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Only list repositories that contain commits, excluding merge commits.<br><br><b>-D <I>date</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show commits made after a specific date (e.g., "yesterday", "2023-01-01").<br><br><b>--email <I>email</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Filter commits by author's email address.<br><br><b>--author <I>author</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Filter commits by author's name.<br><br><b>--remote</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Include commits from remote tracking branches.<br><br><b>--pull</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Perform a <I>git pull</I> in each repository before scanning for commits.<br><br><b>--stashes</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Include information about pending stashes in the report.<br><br><b>--grep <I>pattern</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Filter commits by log message content using a regex pattern.<br><br><b>--exclude <I>pattern</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Exclude repositories whose paths match the specified pattern.<br><br><b>--include <I>pattern</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Include only repositories whose paths match the specified pattern.<br><br><b>--git-log-options <I>options</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Pass additional options directly to the <I>git log</I> command.<br><br><b>--group-by <I>type</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Group commits by 'author' or 'repo' (repository).<br><br><b>-h</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display help message and exit.<br><br><b>-v</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display version information and exit.<br><br>


title: DESCRIPTION
content:
git-standup is a lightweight command-line utility designed to quickly summarize recent Git activity. Its primary use case is to help developers recall and report on their work for daily stand-up meetings.<br>By default, it lists commits made by the current user today and yesterday. The command can traverse directories to find multiple Git repositories and aggregate their commit logs into a single report, providing a comprehensive overview of work across various projects.<br>It supports filtering by days, branches, authors, and dates, and offers various output formats, including plaintext, Markdown, XML, and JSON, making it adaptable for different reporting needs.


title: CAVEATS
content:
git-standup relies on <I>git</I> being installed and available in the system's PATH. For optimal use across multiple projects, it is recommended to organize Git repositories within a common parent directory. Running the command from a very deep directory structure or with a very large number of repositories without specific filters might impact performance.


title: CONFIGURATION
content:
git-standup can be configured using environment variables, such as <I>GIT_STANDUP_DAYS</I> to set the default number of days to look back, or <I>GIT_STANDUP_GIT_LOG_OPTIONS</I> to pass custom default options to <I>git log</I>. These variables allow users to tailor the command's behavior without explicitly passing options every time.


title: MULTI-REPOSITORY USAGE
content:
When executed from a directory containing multiple Git repositories (or directories that contain Git repositories), git-standup will automatically scan and aggregate commit information from all detected repositories, making it ideal for developers working across numerous projects.


title: HISTORY
content:
git-standup was created by Jonas Lundberg as a practical utility to simplify the process of recalling and reporting daily Git activities, particularly for agile stand-up meetings. Its development has focused on providing a flexible, easy-to-use script that integrates seamlessly with existing Git workflows, offering various filtering and output options to suit different user needs.


title: SYNOPSIS
content:
<b>git stash</b> [<options>] [<subcommand>] [<args>]<br><br>Common forms:<br><b>git stash push</b> [-p|--patch] [-k|--[no-]keep-index] [-u|--include-untracked] [-a|--all] [-q|--quiet] [-m|--message &lt;message&gt;] [--] [&lt;pathspec&gt;...]<br><b>git stash pop</b> [--index] [&lt;stash&gt;]<br><b>git stash apply</b> [--index] [&lt;stash&gt;]<br><b>git stash list</b> [&lt;options&gt;]<br><b>git stash show</b> [&lt;options&gt;] [&lt;stash&gt;]<br><b>git stash drop</b> [-q|--quiet] [&lt;stash&gt;]<br><b>git stash clear</b><br><b>git stash branch</b> &lt;branchname&gt; [&lt;stash&gt;]


title: PARAMETERS
content:
<b><b>push</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Saves your local modifications to a new stash entry. This is the default action when no subcommand is given, e.g., <i><b>git stash -m 'message'</b></i>.<br><br><b><b>list</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Lists the stash entries that you currently have, showing their index and message.<br><br><b><b>show</b> [&lt;stash&gt;]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows the changes recorded in the given stash entry (defaults to the latest one, <i>stash@{0}</i>).<br><br><b><b>pop</b> [--index] [&lt;stash&gt;]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Removes a single stash entry from the stash list and applies it on top of the current working tree. Use <i><b>--index</b></i> to try to restore the index state.<br><br><b><b>apply</b> [--index] [&lt;stash&gt;]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Applies a single stash entry from the list onto the current working tree, but leaves it in the stash list for potential reuse. Use <i><b>--index</b></i> to try to restore the index state.<br><br><b><b>drop</b> [&lt;stash&gt;]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Removes a single stash entry from the stash list (defaults to <i>stash@{0}</i>).<br><br><b><b>clear</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Removes all stash entries from the stash list.<br><br><b><b>branch</b> &lt;branchname&gt; [&lt;stash&gt;]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Creates and checks out a new branch named <i>&lt;branchname&gt;</i> starting from the commit at which the <i>&lt;stash&gt;</i> was originally created, and applies the changes from <i>&lt;stash&gt;</i> to it.<br><br><b><b>-p</b>, <b>--patch</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Interactively select hunks from the diff to be stashed. Similar to <i><b>git add -p</b></i>.<br><br><b><b>-k</b>, <b>--keep-index</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Don't stash anything that has already been added to the index. Only stash unstaged changes.<br><br><b><b>-u</b>, <b>--include-untracked</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Includes untracked files in the stash. These files are typically not version controlled.<br><br><b><b>-a</b>, <b>--all</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Includes untracked and ignored files in the stash, in addition to tracked files.<br><br><b><b>-m</b> &lt;message&gt;, <b>--message</b> &lt;message&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Associates a message with the new stash entry, making it easier to identify later.<br><br>


title: DESCRIPTION
content:
<i><b>git stash</b></i> is a powerful command that temporarily shelves (or <i>stashes</i>) changes you've made to your working directory and puts them on a stack of unfinished changes. This is incredibly useful when you need to switch branches quickly without committing your current work, or when you want to pull new changes without conflicts from your work-in-progress. It cleans your working directory, making it ready for other operations, then allows you to re-apply the stashed changes later. By default, it saves both staged and unstaged changes. You can optionally include untracked and even ignored files.


title: CAVEATS
content:
<ul><li>By default, <i><b>git stash</b></i> does not stash new, untracked files. Use <i><b>-u</b></i> or <i><b>-a</b></i> to include them.</li><li>Applying a stash might result in conflicts if your current working directory has changes that overlap with the stashed changes. These conflicts must be resolved manually.</li><li><i><b>git stash pop</b></i> removes the stash from the stack after applying, while <i><b>git stash apply</b></i> leaves it there. Choose based on whether you intend to reuse the stash.</li><li>Binary files can be stashed, but <i><b>git stash show</b></i> typically won't display their differences in a human-readable format.</li></ul>


title: <I>STASH REFLOG</I>
content:
<i><b>git stash</b></i> maintains its own reflog, which is a history of where the stash pointer has been. This means that even if you accidentally `drop` a stash, you can often recover it by inspecting the `reflog` of `refs/stash` (e.g., `<i><b>git reflog stash</b></i>`) and then using `<i><b>git stash apply</b>` `stash@{<index>}` or `<i><b>git checkout</b>` `stash@{<index>}`.


title: <I>WORKING WITH MULTIPLE STASHES</I>
content:
While <i><b>git stash</b></i> operations (like `pop` or `apply`) default to the most recent stash entry (<i>stash@{0}</i>), you can specify any stash entry by its index (e.g., <i>stash@{1}</i>, <i>stash@{2}</i>) obtained from <i><b>git stash list</b></i>. This allows you to manage and apply older or specific stashes as needed, offering great flexibility when juggling multiple unfinished tasks.


title: HISTORY
content:
The <i><b>git stash</b></i> command was introduced relatively early in Git's history (around Git 1.5.3) to address the common workflow problem of needing to switch contexts or pull changes without committing unfinished work. Initially, it primarily used the <i><b>save</b></i> subcommand (now deprecated in favor of <i><b>push</b></i>). Over time, it has evolved with new options like <i><b>--include-untracked</b></i> and <i><b>--all</b></i> to provide more flexibility in what gets stashed. It has become an indispensable tool for many Git users, allowing for agile context switching and efficient management of work in progress, embodying Git's flexibility.


title: PARAMETERS
content:
<b>--short, -s</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Gives the output in a concise, one-line-per-file format, useful for scripting.<br><br><b>--branch, -b</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays information about the current branch and its upstream tracking branch, including ahead/behind counts.<br><br><b>--porcelain[=<I>version</I>]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Provides machine-readable output format, designed to be stable and parsable by scripts. Default version is '1', '2' is available for more structured output.<br><br><b>--long</b><br>&nbsp;&nbsp;&nbsp;&nbsp;The default output format, showing detailed information in multiple sections.<br><br><b>--untracked-files[=<I>mode</I>]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows untracked files. <I>mode</I> can be <i><b>no</b></i> (do not show), <i><b>normal</b></i> (show just filename), or <i><b>all</b></i> (show contents of untracked directories).<br><br><b>--ignored</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows ignored files in addition to untracked files. Requires <I>--untracked-files=all</I>.<br><br><b>--no-ahead-behind</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Suppresses the display of the ahead/behind count for the current branch relative to its upstream.<br><br><b>--column[=<I>options</I>]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays untracked files and ignored files in columns, making the output more readable. <I>options</I> can specify layout.<br><br><b>--show-stash</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows the number of currently stashed entries.<br><br>


title: DESCRIPTION
content:
The <i><b>git status</b></i> command displays the state of the working tree and the staging area (index) relative to the last commit. It's a fundamental command for understanding the current state of your Git repository.<br><br>It provides critical information, categorizing files into three main groups:<br><b>1. Changes to be committed:</b> Files that have been staged (added to the index) and are ready to be committed.<br><b>2. Changes not staged for commit:</b> Modified files in the working directory that have not yet been added to the staging area.<br><b>3. Untracked files:</b> New files in the working directory that are not tracked by Git and have not been added to the staging area.<br><br><i><b>git status</b></i> helps developers monitor their progress, identify uncommitted changes, and decide which files need to be staged or ignored before making a commit. It's an essential tool in the daily Git workflow.


title: CAVEATS
content:
<i><b>git status</b></i> only shows changes relative to the <i><b>HEAD</b></i> commit. It does not display changes that are already committed.<br>By default, it does not show individual files within untracked directories unless <i><b>--untracked-files=all</b></i> is used. Ignored files are also hidden by default.


title: SHORT OUTPUT FORMAT (`-S`)
content:
When using the <i><b>--short</b></i> or <i><b>-s</b></i> option, the output is presented as a list of paths, each prefixed by two characters representing the status. The first character indicates the status of the index (staging area) relative to the <i><b>HEAD</b></i> commit, and the second character indicates the status of the working tree relative to the index.<br><br>Common status codes include:<br><b>M</b>: Modified<br><b>A</b>: Added<br><b>D</b>: Deleted<br><b>R</b>: Renamed<br><b>C</b>: Copied<br><b>U</b>: Unmerged<br><b>?</b>: Untracked<br><b>!</b>: Ignored<br><br>For example, <i><b>MM</b></i> means a file modified in the index and also modified in the working tree. <i><b> M</b></i> (space followed by M) means a file modified in the working tree but not staged. <i><b>M </b></i> (M followed by space) means a file modified and staged but not committed yet.


title: HISTORY
content:
<i><b>git status</b></i> has been a core and indispensable command since the early days of Git's development. It provides the essential overview required for Git's unique staging area workflow. While its core functionality remains consistent, its output formats have evolved over time to improve human readability (e.g., color, detailed long format) and to support robust scripting (e.g., <I>--porcelain</I> format).


title: PARAMETERS
content:
<b>--strip-comments</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Strip lines that begin with a <b>#</b> character. These lines will be entirely removed from the output.<br><br><b>--comment-lines</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Keep <i>only</i> lines that begin with a <b>#</b> character. All other lines, including blank lines, will be removed. This option cannot be used in conjunction with <i>--empty-lines</i>.<br><br><b>--empty-lines</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Keep <i>only</i> empty lines. All other lines, including those with comments or content, will be removed. This option cannot be used in conjunction with <i>--comment-lines</i>.<br><br>


title: DESCRIPTION
content:
<i>git-stripspace</i> is a Git plumbing command designed to normalize whitespace in text input. It reads content from standard input and outputs a cleaned version to standard output. Its primary function is to remove leading and trailing whitespace from each line, collapse multiple consecutive blank lines into a single blank line, and ensure that the output ends with exactly one newline character.<br><br>This command is primarily used internally by Git itself to ensure consistency in various textual fields, such as commit messages, where whitespace normalization is important for canonical representation and easier parsing. It helps standardize text content before it's processed or stored by Git, contributing to the integrity and predictability of Git's internal data structures.


title: CAVEATS
content:
This command is a low-level 'plumbing' command primarily intended for internal Git use or advanced scripting. It operates strictly on standard input and writes to standard output, making it suitable for pipelines but not for direct file manipulation without redirection.<br><br>The options <i>--comment-lines</i> and <i>--empty-lines</i> are mutually exclusive; only one can be specified at a time.


title: INPUT/OUTPUT
content:
This command reads from standard input (stdin) and writes its processed output to standard output (stdout). It does not take file paths as direct arguments. Therefore, it is typically used in conjunction with shell redirection (e.g., <code>git stripspace &lt; input.txt</code>) or in a pipeline (e.g., <code>cat input.txt | git stripspace</code>).


title: INTERNAL USE
content:
<i>git-stripspace</i> is not commonly invoked directly by end-users in their daily Git workflow. Instead, it is an internal utility leveraged by higher-level Git commands (e.g., <i>git-commit</i>) to ensure that specific text fields, such as commit messages, are normalized before being stored or used by Git. This ensures that Git can reliably compare and process textual content.


title: HISTORY
content:
<i>git-stripspace</i> is a fundamental plumbing command within Git, integrated early into its development to handle the critical task of text normalization. Its functionality is vital for internal operations, especially when processing textual metadata like commit messages, where a canonical representation of whitespace is essential for consistency, content hashing, and reliable parsing. While its core purpose has remained constant, it has evolved as part of Git's robust toolkit, ensuring that the system can consistently process and store text data regardless of minor formatting variations in user input.


title: SYNOPSIS
content:
<b>git submodule</b> <command> [<options>] [--] [<repository>...]<br><b>git submodule add</b> [-b <branch>] [--name <name>] [--reference <repository>] [--depth <depth>] [--] <repository> [<path>]<br><b>git submodule update</b> [--init] [--remote] [--[no-]recursive] [--force] [--checkout|--rebase|--merge] [--reference <repository>] [--depth <depth>] [--jobs <n>] [--] [<path>...]<br><b>git submodule status</b> [--cached] [--recursive] [--] [<path>...]<br><b>git submodule init</b> [--] [<path>...]<br><b>git submodule deinit</b> [-f|--force] [--] <path>...<br><b>git submodule foreach</b> [--recursive] <command>


title: PARAMETERS
content:
<b><b>add</b> <repository> [<path>]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Adds a new submodule to the repository. The <i>&lt;repository&gt;</i> is the URL of the external repository, and <i>&lt;path&gt;</i> is the relative path where it should be cloned.<br><br><b><b>update</b> [--init] [--remote] [<path>...]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Updates the registered submodules to the commit specified by the superproject. <i>--init</i> initializes uninitialized submodules. <i>--remote</i> updates to the HEAD of the submodule's remote tracking branch.<br><br><b><b>status</b> [<path>...]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows the status of the submodules. It indicates if the submodule is at the specified commit, has local changes, or is uninitialized.<br><br><b><b>init</b> [<path>...]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Initializes the submodules by creating their <i>.git/config</i> entries from <i>.gitmodules</i>.<br><br><b><b>deinit</b> [-f|--force] <path>...</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Unregisters the given submodules. Removes the submodule entry from <i>.git/config</i> and <i>.gitmodules</i>. Use <i>--force</i> to remove modified submodules.<br><br><b><b>foreach</b> [--recursive] <command></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Executes an arbitrary shell command in each checked out submodule.<br><br><b><b>sync</b> [<path>...]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Synchronizes remote URL configurations for submodules. Useful when the superproject's remote URL changes.<br><br><b><b>set-url</b> <path> <newurl></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the URL of the given submodule.<br><br><b><b>set-branch</b> [-b <branch>] [--default] <path></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the default branch for the given submodule.<br><br><b><b>absorbgitdirs</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Moves the <i>.git</i> directory of a submodule into the superproject's <i>.git/modules</i> directory to simplify submodule management.<br><br><b><b>--cached</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Operates on the index copy of the submodule entry, not the working tree.<br><br><b><b>--recursive</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Processes submodules recursively, i.e., also operates on nested submodules.<br><br><b><b>--force</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Used with <b>update</b> to discard local changes in the submodule working tree, and with <b>deinit</b> to remove modified submodules.<br><br><b><b>--reference</b> <repository></b><br>&nbsp;&nbsp;&nbsp;&nbsp;During add/update, use the local repository as a reference for cloning, allowing a local clone to be used instead of fetching from the network.<br><br><b><b>--depth</b> <depth></b><br>&nbsp;&nbsp;&nbsp;&nbsp;During add/update, creates a shallow clone with a history truncated to the specified number of commits.<br><br>


title: DESCRIPTION
content:
The `git-submodule` command is a powerful utility within Git designed to manage repositories embedded inside another repository. It allows a project to incorporate external code or libraries without directly copying them into the main project's repository. Instead, it maintains a reference to a specific commit of another Git repository, known as a submodule. This enables developers to keep external dependencies separate while still tracking which version of those dependencies their project uses. Submodules are particularly useful for managing shared components, third-party libraries, or complex projects broken into smaller, independent parts. They provide a mechanism to ensure that all developers working on a project are using the exact same versions of all dependencies, improving consistency and reproducibility.


title: CAVEATS
content:
<b>Detached HEAD:</b> Submodules often check out into a detached HEAD state. This means if you make changes directly within the submodule and commit, those changes are not on a branch. You must manually create or switch to a branch, commit, and then update the superproject's reference.<br><b>Updating Superproject:</b> After pulling changes in a submodule or switching its branch, the superproject needs to be updated to record the new commit hash. Forgetting this can lead to inconsistencies.<br><b>Deleting Submodules:</b> Deleting a submodule requires several manual steps: removing the entry from <i>.gitmodules</i>, removing the entry from <i>.git/config</i>, un-staging the submodule, and finally removing the submodule directory itself. <b>git submodule deinit</b> helps with some of this, but it's not a single-command delete.<br><b>Cloning Recursively:</b> New users often forget to clone the superproject with <i>--recursive</i> or run <b>git submodule update --init --recursive</b> after cloning, leading to empty submodule directories.<br><b>Branch Management:</b> If a submodule needs to track a specific branch rather than a fixed commit, you must use <b>git submodule update --remote</b> or <b>git submodule set-branch</b>.


title: .GITMODULES FILE
content:
When you add a submodule, Git automatically creates or updates a <i>.gitmodules</i> file in the superproject's root directory. This file is a plain text file that maps the submodule's name to its path and URL. It acts as a configuration file for all submodules in the project and is version-controlled.


title: SUPERPROJECT'S ROLE
content:
The superproject does not track the <i>contents</i> of the submodule; it tracks a specific commit hash within the submodule's repository. This means if the submodule's repository changes, the superproject only reflects this if its submodule reference is explicitly updated to the new commit.


title: ALTERNATIVES
content:
While <b>git-submodule</b> is Git's native solution, other methods exist for managing dependencies, such as Git subtrees (which merge the dependency's history directly into the superproject), or language-specific package managers (e.g., npm, Cargo, pip) that download dependencies outside the Git repository.


title: HISTORY
content:
`git-submodule` was introduced early in Git's history, around version 1.5.2 in 2007. It was designed to address the common requirement of managing external dependencies and components within a larger project, predating more modern dependency management solutions found in specific programming languages. Its initial implementation provided basic functionality for adding and updating external repositories, and it has since evolved with new commands and options to improve usability and address common workflows, such as <b>deinit</b> and <b>foreach</b>, making it a robust, albeit sometimes complex, solution for nested repositories.


title: SYNOPSIS
content:
<b>git subtree</b> &lt;<i>command</i>&gt; [&lt;<i>options</i>&gt;]<br><br>Common commands and their primary syntax:<br>&nbsp;&nbsp;<b>git subtree add</b> <i>--prefix=&lt;prefix&gt; &lt;repository&gt; &lt;ref&gt;</i><br>&nbsp;&nbsp;<b>git subtree pull</b> <i>--prefix=&lt;prefix&gt; [&lt;repository&gt; [&lt;ref&gt;]]</i><br>&nbsp;&nbsp;<b>git subtree push</b> <i>--prefix=&lt;prefix&gt; &lt;repository&gt; &lt;ref&gt;</i><br>&nbsp;&nbsp;<b>git subtree split</b> <i>--prefix=&lt;prefix&gt; [&lt;commit&gt;]</i><br>&nbsp;&nbsp;<b>git subtree merge</b> <i>--prefix=&lt;prefix&gt; &lt;commit&gt;</i>


title: PARAMETERS
content:
<b><b>add</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Adds a new external repository as a subtree into a specified subdirectory.<br><br><b><b>pull</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Updates an existing subtree by pulling changes from its remote source.<br><br><b><b>push</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Pushes changes made within the subtree directory back to its original external repository.<br><br><b><b>split</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Extracts the history of a specific subdirectory into a new, independent branch or a new repository.<br><br><b><b>merge</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Merges a specific commit from an external project into the designated subtree directory.<br><br><b><i>--prefix=&lt;prefix&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The mandatory path within the main repository where the subtree is (or will be) located. E.g., <i>src/mylibrary</i>.<br><br><b><i>&lt;repository&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The URL or local path to the external Git repository. Used with <b>add</b>, <b>pull</b>, and <b>push</b>.<br><br><b><i>&lt;ref&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The branch or commit from the external repository to integrate or push to (e.g., <i>main</i>, <i>HEAD</i>). Used with <b>add</b>, <b>pull</b>, and <b>push</b>.<br><br><b><i>--squash</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;When adding or pulling, squashes the entire history of the subtree into a single commit. This helps keep the main repository's history cleaner and smaller.<br><br><b><i>--annotate=&lt;annotation&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Used with <b>split</b>. Prepends a custom string to commit messages in the newly split history.<br><br><b><i>--branch=&lt;branch&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Used with <b>split</b>. Specifies the name of the new branch to create for the split history.<br><br><b><i>--rejoin</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Used with <b>split</b>. Creates a new commit in the original repository that records the split, allowing future merges to use the split history efficiently.<br><br><b><i>&lt;commit&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The specific commit hash to merge into the subtree. Used with <b>merge</b>.<br><br>


title: DESCRIPTION
content:
<b>git-subtree</b> is a Git command used to manage subprojects within a main Git repository. Unlike <b>git-submodule</b>, it doesn't store a separate repository reference; instead, it merges the history of the subproject directly into a subdirectory of the main repository. This approach simplifies workflows, as changes to the subproject appear as regular commits in the main repository's history, eliminating the need for separate <i>.gitmodules</i> files or specific <i>git submodule</i> commands.<br><br>It's particularly useful when you want to include a library or component from another project and treat it as an integral part of your own repository, allowing you to modify and push changes back to the original source or simply keep a unified history. <b>git-subtree</b> supports both integrating external repositories into a subdirectory and splitting a subdirectory's history out into its own repository.


title: CAVEATS
content:
<b>Caveats and limitations:</b><br>- Can create a very large history in the main repository if not squashed, as it merges the full history of the subtree.<br>- Pushing changes back to the original repository can be tricky, especially if the original repository has diverged significantly or if the history was squashed.<br>- Requires careful management of the <i>--prefix</i> to avoid mistakes, as operations are sensitive to this path.<br>- Not ideal for situations requiring strict version pinning or clear separation of development cycles between main and subprojects, where <b>git-submodule</b> might be a better fit.


title: SQUASHING HISTORY
content:
The <i>--squash</i> option is a critical feature for <b>add</b> and <b>pull</b> operations. It condenses the entire history of the subtree being integrated into a single commit in the main repository. This significantly reduces the size and complexity of the main repository's log, making it easier to read and manage, especially when dealing with subprojects that have very long or irrelevant histories.


title: MERGE STRATEGY
content:
<b>git-subtree</b> operations, particularly <b>pull</b> and <b>merge</b>, often implicitly utilize Git's specialized 'subtree' merge strategy. This strategy is designed to correctly handle merges where one tree is a subdirectory of another, by intelligently manipulating paths during the merge process to align the histories properly.


title: HISTORY
content:
<b>git-subtree</b> originated as a contrib script (<i>git-subtree.sh</i>) bundled with Git, designed to offer an alternative to <b>git-submodule</b>. It was later rewritten in C and became a built-in command in Git 1.7.11, released in 2012. Its development aimed to provide a simpler way to integrate external projects by avoiding the complexities of detached HEADs and separate repository references inherent in submodules.


title: PARAMETERS
content:
<b><i><b>-h</b>, <b>--help</b></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Displays the help message and exits.</i><br><br><b><i><b>-a</b>, <b>--all</b></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Includes information for all local and remote branches.</i><br><br><b><i><b>-c</b>, <b>--color</b></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Forces color output, even if not detected automatically.</i><br><br><b><i><b>-p</b>, <b>--porcelain</b></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Outputs the summary in a machine-readable format for scripting.</i><br><br><b><i><b>-s</b>, <b>--sort</b></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Sorts branches alphabetically by name instead of by activity.</i><br><br><b><i><b>-v</b>, <b>--verbose</b></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Shows more detailed information, such as full commit messages.</i><br><br><b><i><b>-q</b>, <b>--quiet</b></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Suppresses warnings and other non-critical output.</i><br><br><b><i><b>--no-fetch</b></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Prevents fetching from remotes before displaying the summary.</i><br><br><b><i><b>--exclude</b> <pattern></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Excludes branches whose names match the specified pattern.</i><br><br><b><i><b>--format</b> <format></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Specifies a custom output format using placeholders.</i><br><br><b><i><b>--include-gitmodules</b></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Includes a summary of the .gitmodules file.</i><br><br><b><i><b>--status</b></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Explicitly shows the status for the current branch (default behavior).</i><br><br><b><i><b>--no-submodules</b></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Omits information about submodules from the summary.</i><br><br><b><i><b>--no-stash</b></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Excludes information about stashed changes.</i><br><br><b><i><b>--no-divergence</b></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Disables showing divergence information between local and tracking branches.</i><br><br><b><i><b>--exclude-remotes</b></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Excludes all remote-tracking branches from the output.</i><br><br><b><i><b>--only-remotes</b></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Only displays information for remote-tracking branches.</i><br><br><b><i><b>--include-untracked</b></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Includes untracked files in the local changes status.</i><br><br>


title: DESCRIPTION
content:
<i>The <b>git-summary</b> command provides a concise overview of a Git repository's current state. It displays essential information including the active branch, its tracking status, divergence from the remote, and details about the latest commit. Additionally, it highlights local changes by showing staged, unstaged, and untracked files. The summary also includes information about the repository's remotes, the latest tag, and the status of any submodules. This tool is particularly useful for developers who need a quick snapshot of their project's health and pending changes without having to run multiple Git commands like `git status`, `git branch`, and `git remote -v`. It helps in quickly assessing the repository's readiness for commits, pushes, or pulls.</i>


title: CAVEATS
content:
<i>The <b>git-summary</b> command is not a core Git command. It is typically provided by external Git extension packages, such as <b>git-extras</b>. Therefore, its availability depends on whether such a package is installed on your system. The exact features and options might vary slightly between different versions or implementations of <b>git-extras</b>.</i>


title: <B>USAGE PHILOSOPHY</B>
content:
<i><b>git-summary</b> is designed to be a quick glance tool. It prioritizes speed and conciseness, providing most of the necessary information to understand the current state of a repository without requiring the user to piece together data from multiple core Git commands. It's often used as a daily check for developers to ensure their working directory is clean or to understand the state of their branches before performing major operations.</i>


title: HISTORY
content:
<i><b>git-summary</b> emerged as part of the broader <b>git-extras</b> project, a collection of community-contributed Git utilities designed to augment Git's built-in functionality. The <b>git-extras</b> project began around 2011 and has since grown to include hundreds of convenient commands, with <b>git-summary</b> being one of the most popular for quickly assessing repository state. It addresses a common need for a single command to provide a comprehensive project overview, streamlining workflows for many developers.</i>


title: SEE ALSO
content:
<i><b>git(1)</b></i>, <i><b>git-status(1)</b></i>, <i><b>git-branch(1)</b></i>, <i><b>git-remote(1)</b></i>


title: SYNOPSIS
content:
<pre><b>git svn</b> <i>&lt;command&gt;</i> [<i>&lt;options&gt;</i>] [<i>&lt;arguments&gt;</i>]</pre><br>Common commands include:<br><i><b>init</b></i>: Initializes a new or existing Git repository to track a Subversion repository.<br><i><b>clone</b></i>: Initializes and fetches the entire history from a Subversion repository.<br><i><b>fetch</b></i>: Fetches new commits from the tracked Subversion repository.<br><i><b>rebase</b></i>: Updates your local Git branch with changes from the Subversion repository, rewriting your local history.<br><i><b>dcommit</b></i>: Pushes your Git commits to the Subversion repository.


title: PARAMETERS
content:
<b>--prefix=<prefix></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies a prefix for tracking Subversion branches and tags, for example, <i>svn/</i>. This determines how SVN paths appear in your Git remote branches.<br><br><b>-r <revision></b><br>&nbsp;&nbsp;&nbsp;&nbsp;For <i>clone</i> or <i>fetch</i>, specifies a specific revision or revision range to fetch. For example, <i>-r 100:HEAD</i>.<br><br><b>--no-metadata</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Skips adding Git-svn metadata (e.g., <i>git-svn-id</i>) to commit messages. Generally not recommended if you intend to <i>dcommit</i> back to SVN.<br><br><b>--authors-file=<file></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies a file mapping Subversion authors to Git authors (<i>svn_username = Git User <git.user@example.com></i>), useful for consistent commit attribution.<br><br><b>-s</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Assumes the standard Subversion repository layout (<i>trunk</i>, <i>branches</i>, <i>tags</i>). Alias for <i>--stdlayout</i>.<br><br><b>-T <trunk_path></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the path to the trunk in the SVN repository if not using the standard layout.<br><br><b>-b <branches_path></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the path to the branches in the SVN repository if not using the standard layout.<br><br><b>-t <tags_path></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the path to the tags in the SVN repository if not using the standard layout.<br><br><b>--dry-run</b><br>&nbsp;&nbsp;&nbsp;&nbsp;For <i>dcommit</i>, shows what would be committed to the Subversion repository without actually performing the commit.<br><br><b>-n</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Alias for <i>--dry-run</i> when used with the <i>dcommit</i> command.<br><br><b>--log-window=<n></b><br>&nbsp;&nbsp;&nbsp;&nbsp;For <i>fetch</i>, specifies how many revisions to fetch in a single SVN transaction. Can improve performance for large fetches.<br><br><b>-l</b><br>&nbsp;&nbsp;&nbsp;&nbsp;For <i>clone</i>, creates a local repository without a remote Git connection, only tracking the SVN remote. Alias for <i>--local</i>.<br><br>


title: DESCRIPTION
content:
git-svn is a Git command that provides bidirectional operation between a Git repository and a Subversion repository. It allows developers who prefer using Git's powerful local branching, staging area, and advanced history management features to collaborate on projects primarily hosted in Subversion. <br><br>git-svn functions by maintaining a mapping between Git commits and SVN revisions, enabling users to fetch changes from an SVN repository into a local Git repository and to "dcommit" (push) Git commits back to SVN. This makes it a crucial tool for teams transitioning from SVN to Git or for individual developers working within an SVN-centric organization who wish to leverage Git's advantages locally. It tracks SVN branches and tags as Git remote branches, facilitating a relatively seamless workflow despite the underlying architectural differences between Git's Directed Acyclic Graph (DAG) history and SVN's linear history.


title: CAVEATS
content:
<ul><li><b>History Mismatch</b>: Git's Directed Acyclic Graph (DAG) for history is fundamentally different from SVN's linear history. This can lead to complexities; <i>git svn rebase</i> is often preferred over merging to keep history linear for SVN.</li><li><b>Branching and Merging</b>: While <i>git-svn</i> tracks SVN branches, Git's branching model is more flexible. Merging Git branches that contain non-linear history back to SVN can be problematic, often requiring squashing or careful rebasings.</li><li><b>Performance</b>: For very large Subversion repositories or deep histories, initial <i>git svn clone</i> and subsequent <i>git svn fetch</i> operations can be slow and resource-intensive due to the need to translate SVN revisions into Git commits.</li><li><b>Tags</b>: Git light-weight tags have no direct SVN equivalent. SVN tags are typically copies of branches, which <i>git-svn</i> treats as remote branches. Git annotated tags are more analogous to SVN's "tag" concept.</li><li><b>Empty Directories</b>: Git does not track empty directories, whereas SVN does. This can cause minor inconsistencies when <i>dcommitting</i> if empty directories are significant.</li><li><b>Authentication</b>: <i>git-svn</i> relies on the <i>svn</i> command-line client for authentication, which might require additional configuration for password caching or SSH keys.</li></ul>


title: COMMON WORKFLOW
content:
<ul><li><b>Cloning</b>: Start with <i>git svn clone &lt;SVN_URL&gt; &lt;local_repo_name&gt;</i>. This creates a local Git repository and fetches all history from the SVN URL.</li><li><b>Updating</b>: To get the latest changes from SVN, use <i>git svn rebase</i>. This fetches new revisions and applies your local commits on top, maintaining a linear history.</li><li><b>Committing to SVN</b>: After making local Git commits, push them to SVN using <i>git svn dcommit</i>. This command converts your Git commits into SVN revisions and pushes them sequentially.</li><li><b>Branching</b>: SVN branches are tracked as Git remote branches (e.g., <i>remotes/svn/branch_name</i>). To work on an SVN branch, create a local Git branch from it: <i>git checkout -b my_local_branch remotes/svn/branch_name</i>.</li></ul>


title: AUTHORSHIP MAPPING
content:
Subversion tracks authors by username, while Git uses a "Name <email>" format. For proper authorship in Git commits (and vice-versa), an <i>authors-file</i> can be used. This file maps SVN usernames to Git author strings, ensuring correct attribution when converting commits. Example: <i>svn_username = Git User <git.user@example.com></i>.


title: HISTORY
content:
<i>git-svn</i> has been an integral part of the Git distribution almost since its inception. It was developed to address the practical need for Git users to interact with Subversion repositories, which were prevalent at the time of Git's rise. Its inclusion allowed developers to leverage Git's superior local workflow features (e.g., fast branching, staging area) without requiring their entire team or project to migrate from Subversion. Over the years, it has seen continuous development to improve performance, enhance compatibility with various SVN configurations, and refine its error handling. While the overall industry trend has shifted away from Subversion towards Git and other DVCS, <i>git-svn</i> remains a vital tool for organizations with legacy SVN repositories or in hybrid environments.


title: SYNOPSIS
content:
<b>git switch</b> [<I>options</I>] [<I>branch</I>]<br><b>git switch</b> <I>-c</I> <I>&lt;new-branch&gt;</I> [<I>&lt;start-point&gt;</I>]<br><b>git switch</b> <I>--orphan</I> <I>&lt;new-branch&gt;</I><br><b>git switch</b> <I>-</I>


title: PARAMETERS
content:
<b><i>&lt;branch&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The name of the branch to switch to. Can be an existing local or remote-tracking branch.<br><br><b><i>-c</i> <I>&lt;new-branch&gt;</I>, <i>--create</i> <I>&lt;new-branch&gt;</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Create a new branch named <I>&lt;new-branch&gt;</I> and switch to it. If <I>&lt;start-point&gt;</I> is given, it's created there, otherwise from <i>HEAD</i>.<br><br><b><i>-C</i> <I>&lt;new-branch&gt;</I>, <i>--force-create</i> <I>&lt;new-branch&gt;</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Like <i>-c</i>, but if <I>&lt;new-branch&gt;</I> already exists, it will be reset to <I>&lt;start-point&gt;</I> (or <i>HEAD</i>) and forcefully switched to.<br><br><b><i>-t</i>, <i>--track</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;When creating a new branch, set up <i>upstream</i> configuration. This is implied if the argument is a remote-tracking branch.<br><br><b><i>--no-track</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Do not set up <i>upstream</i> configuration, even if the branch name matches a remote-tracking branch.<br><br><b><i>--orphan</i> <I>&lt;new-branch&gt;</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Create a new, unassociated <I>orphan</I> branch named <I>&lt;new-branch&gt;</I>, removing all previous history from the working tree.<br><br><b><i>-</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Switch to the previous branch (like <i>git checkout -</i>).<br><br><b><i>--detach</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Detach <i>HEAD</i> at the tip of the specified <I>&lt;branch&gt;</I> or commit. Allows working on a specific commit without being on a branch.<br><br><b><i>-f</i>, <i>--force</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Allow switching even if there are local modifications that would be overwritten. This will discard uncommitted changes if they conflict with the switch.<br><br><b><i>--discard-changes</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Alias for <i>--force</i>.<br><br><b><i>--guess</i>, <i>--no-guess</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Control if the branch name completion should be attempted based on remote-tracking branches. <i>--guess</i> is the default behavior.<br><br>


title: DESCRIPTION
content:
<i>git switch</i> is a command introduced in <b>Git version 2.23</b>, designed to provide a dedicated and safer way to switch branches or create new ones.<br><br>Historically, the <i>git checkout</i> command was overloaded, performing actions like switching branches, creating new branches, and restoring files. This often led to confusion. <i>git switch</i> aims to resolve this by separating the concerns, focusing solely on branch manipulation. It offers clearer semantics for switching between existing branches, creating new branches from a starting point, and detaching <i>HEAD</i> to a specific commit.<br><br>Unlike <i>git checkout</i>, <i>git switch</i> is more opinionated about state changes, explicitly warning or preventing operations that would discard local modifications, making it generally safer for new users. It works with both local and remote-tracking branches, providing options for tracking upstream branches automatically.


title: CAVEATS
content:
<i>git switch</i> strictly handles branch operations and does not manage file-level restoration; use <i>git restore</i> for that.<br><br>While generally safer than <i>git checkout</i>, the <i>--force</i> option can still discard local, uncommitted changes. Always be mindful when using it.<br><br>This command was introduced in <b>Git 2.23</b>; it may not be available on older Git installations.


title: DEFAULT BEHAVIOR
content:
If no branch name is specified, <i>git switch</i> will not perform any action and simply print usage information. Unlike <i>git checkout</i>, it does not list existing branches when called without arguments.


title: SAFETY FEATURES
content:
<i>git switch</i> will prevent you from switching branches if you have uncommitted changes that would be lost by the switch, unless you explicitly use the <i>--force</i> (or <i>--discard-changes</i>) option to indicate that you want to discard them.


title: HISTORY
content:
<i>git switch</i> was introduced in <b>Git 2.23</b> (August 2019) alongside <i>git restore</i>. The primary motivation was to de-overload the widely used <i>git checkout</i> command, which historically performed both branch switching and file restoration. By separating these concerns, the Git command-line interface became more intuitive and less error-prone, improving clarity and user experience, especially for new users learning Git.


title: SYNOPSIS
content:
<b>git symbolic-ref</b> [<b>-m</b> <i>&lt;reason&gt;</i>] <i>&lt;name&gt;</i> [<i>&lt;ref&gt;</i>]<br><b>git symbolic-ref --delete</b> <i>&lt;name&gt;</i><br><b>git symbolic-ref --quiet</b> <i>&lt;name&gt;</i><br><b>git symbolic-ref --short</b> <i>&lt;name&gt;</i>


title: PARAMETERS
content:
<b><b>-m</b> <i>&lt;reason&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the reflog message when creating or updating a symbolic ref. This message is recorded in the reflog for the target reference.<br><br><b><b>--delete</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Deletes the specified symbolic reference. The command will fail if the reference is not symbolic.<br><br><b><b>--quiet</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Suppresses error messages when checking if a ref is symbolic. Returns 0 if symbolic, 1 if not symbolic, or 128 if the ref does not exist or other errors occur.<br><br><b><b>--short</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;When reading a symbolic ref, displays the target ref in a shorter, more user-friendly format (e.g., <i>main</i> instead of <i>refs/heads/main</i>).<br><br><b><i>&lt;name&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The name of the symbolic reference to operate on (e.g., <i>HEAD</i>, <i>refs/remotes/origin/HEAD</i>). It must be a non-existent ref or an existing symbolic ref for write operations.<br><br><b><i>&lt;ref&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The target reference that <i>&lt;name&gt;</i> should point to (e.g., <i>refs/heads/feature-branch</i>). Used when setting a symbolic ref. Must be a valid existing reference.<br><br>


title: DESCRIPTION
content:
<b>git symbolic-ref</b> is a low-level command used to read, update, and delete <i>symbolic references</i> in Git. Unlike a direct reference which points directly to a commit hash, a symbolic reference points to another reference. The most common example is <i>HEAD</i>, which typically points to your current branch (e.g., <i>refs/heads/main</i>). This command allows you to inspect what a symbolic ref points to, change its target (e.g., to programmatically switch <i>HEAD</i> to another branch), or remove it entirely. It's crucial for operations that manipulate the repository's state at a foundational level, often utilized by plumbing commands or scripts to manage the active branch or other dynamic pointers within the Git repository.


title: CAVEATS
content:
Directly manipulating <i>HEAD</i> with <b>git symbolic-ref</b> can lead to a 'detached HEAD' state if pointed directly to a commit-ish, or put the repository into an unexpected state if used incorrectly. It's generally safer to use higher-level commands like <b>git checkout</b> or <b>git switch</b> for common branch operations. This command is primarily for scripting and plumbing operations where precise control over Git's internal references is required.


title: SYMBOLIC REFS VS. DIRECT REFS
content:
<i>Symbolic references</i> point to other references (e.g., <i>HEAD</i> points to <i>refs/heads/main</i>). <i>Direct references</i> (also known as 'loose' references) point directly to a commit, tree, or blob object's SHA-1 hash (e.g., <i>refs/heads/main</i> points to a specific commit ID). <b>git symbolic-ref</b> only operates on symbolic references, managing their targets.


title: COMMON USE CASES
content:
Beyond manipulating <i>HEAD</i>, <b>git symbolic-ref</b> is used to manage symbolic links for remote tracking branches (e.g., <i>refs/remotes/origin/HEAD</i> typically points to <i>refs/remotes/origin/main</i>). It's also invaluable in custom Git workflows or advanced scripting scenarios where a dynamic, human-readable pointer to another reference is needed within the repository.


title: HISTORY
content:
The <b>git symbolic-ref</b> command is a fundamental Git plumbing command, integrated into Git's core functionality since its early development. It provides direct access to the mechanism of symbolic references, which are central to how Git manages concepts like the current branch (<i>HEAD</i>) and remote tracking branches. Its design reflects Git's philosophy of providing low-level tools that higher-level 'porcelain' commands are built upon, enabling robust and flexible repository management.


title: SYNOPSIS
content:
<br><code>git-sync <b>--repo</b>=&lt;URL&gt; <b>--branch</b>=&lt;BRANCH&gt; <b>--dest</b>=&lt;PATH&gt; [options]</code>


title: PARAMETERS
content:
<b><b>--repo</b>, <b>-r</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<br>Specifies the URL of the Git repository to synchronize.<br>e.g., <i>https://github.com/user/repo.git</i><br><br><b><b>--branch</b>, <b>-b</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<br>The Git branch to track and synchronize.<br>e.g., <i>main</i> or <i>dev</i><br><br><b><b>--rev</b>, <b>-s</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<br>A specific Git revision (commit SHA, tag, or branch) to check out. Overrides <B>--branch</B>.<br><br><b><b>--dest</b>, <b>-d</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<br>The local directory path where the repository content will be synchronized.<br>e.g., <i>/var/www/html</i><br><br><b><b>--period</b>, <b>-p</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<br>The synchronization interval, in seconds.<br>e.g., <i>300</i> (for 5 minutes)<br><br><b><b>--ssh-key</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<br>Path to an SSH private key file for repository authentication.<br><br><b><b>--username</b>, <b>--password</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<br>Credentials for basic authentication over HTTP/S.<br><br><b><b>--depth</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<br>Limits the number of commits to fetch during cloning.<br>e.g., <i>1</i> for a shallow clone.<br><br><b><b>--wait</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<br>If true, `git-sync` waits until the initial synchronization completes before exiting (useful for initContainers).<br><br><b><b>--full-repo</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<br>If true, the `.git` directory is kept in the destination, allowing local Git operations.<br><br>


title: DESCRIPTION
content:
<br>The `git-sync` command is a utility primarily designed for keeping a local directory synchronized with a remote Git repository. While not a standard command-line tool for general Linux systems, it is prominently used in containerized environments, particularly within Kubernetes. It functions as an efficient mechanism to fetch the latest changes from a Git repository and make them available inside a running container, often serving as an <i>initContainer</i> or a <i>sidecar</i> to periodically update application configurations or content.<br><br>Upon execution, `git-sync` typically performs an initial clone of the specified repository. Subsequently, it operates on a defined schedule (or continuously) to pull new commits, ensuring the local copy remains up-to-date with the remote branch or revision. This eliminates the need for applications within the container to manage Git operations themselves, simplifying their deployment and lifecycle. It handles various Git protocols, including HTTP/S and SSH, and supports authentication methods like basic auth or SSH keys.<br><br>Its key benefit lies in enabling dynamic content or configuration updates without requiring container restarts, making deployments more agile and responsive to source control changes.


title: CAVEATS
content:
<br>1. <B>Security of Credentials:</B> Sensitive information like SSH keys or passwords should be managed securely, ideally through Kubernetes Secrets or similar secure mechanisms, and mounted into the container.<br>2. <B>Performance with Large Repositories:</B> Frequent syncing of very large repositories can consume significant network bandwidth and disk I/O, potentially impacting application performance.<br>3. <B>Contextual Usage:</B> `git-sync` is highly optimized for container orchestration platforms like Kubernetes. While it can be run standalone, its primary design caters to these specific environments. It's not a general-purpose Git client substitute.<br>4. <B>Handling Conflicts:</B> `git-sync` is designed for one-way synchronization (remote to local). It does not handle local modifications or merge conflicts; any local changes will be overwritten during syncs, unless <B>--full-repo</B> is enabled and git operations are performed manually after a sync.


title: USAGE PATTERNS IN KUBERNETES
content:
<br>`git-sync` is commonly deployed in Kubernetes as an <i>initContainer</i> to ensure an application has the necessary Git repository content before it starts, or as a <i>sidecar container</i> that continuously runs alongside the main application container, periodically updating the shared volume with the latest Git changes. This enables applications to consume up-to-date configurations or content without requiring re-deploys.


title: EXIT CODES AND ROBUSTNESS
content:
<br>`git-sync` is designed to be robust. It handles network failures and Git operation errors gracefully, often retrying operations. Its exit codes can signal success or failure, which is crucial for orchestrators to determine container readiness or initiate recovery actions.


title: HISTORY
content:
<br>The `git-sync` utility gained prominence with the rise of containerization and orchestrators like Kubernetes. It was developed to address the specific challenge of dynamically updating configurations, content, or code within containers without requiring a full image rebuild or pod restart. Its design as a simple, single-purpose tool, often implemented as an <i>initContainer</i> or <i>sidecar</i> container, aligns perfectly with the microservices architecture and the need for agility in cloud-native deployments. It abstracts away the complexities of Git operations from the main application, allowing developers to focus on application logic while `git-sync` manages content freshness.


title: SYNOPSIS
content:
<code>git tag [-a | -s | -u &lt;keyid&gt;] [-f] [-m &lt;msg&gt; | -F &lt;file&gt;] &lt;tagname&gt; [&lt;commit&gt; | &lt;object&gt;]</code><br><code>git tag -d &lt;tagname&gt;...</code><br><code>git tag [-l | --list] [--contains &lt;commit&gt;] [--no-contains &lt;commit&gt;] [--points-at &lt;object&gt;] [--sort=&lt;key&gt;] [&lt;pattern&gt;...]</code><br><code>git tag -v &lt;tagname&gt;...</code>


title: PARAMETERS
content:
<b><i>&lt;tagname&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The name of the tag to create, delete, or verify.<br><br><b><i>&lt;commit&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The commit object the tag will point to. Defaults to <b>HEAD</b> if not specified.<br><br><b><b>-a</b>, <b>--annotate</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Create an <i>annotated tag</i>. This is recommended for releases as it stores metadata like tagger name, email, and date.<br><br><b><b>-s</b>, <b>--sign</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Create a <i>GPG-signed tag</i>. Requires a GPG key configured in Git. Ensures the integrity and authenticity of the tag.<br><br><b><b>-u</b> <i>&lt;keyid&gt;</i>, <b>--local-user=</b><i>&lt;keyid&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Use the specified GPG key to sign the tag, instead of the default.<br><br><b><b>-m</b> <i>&lt;msg&gt;</i>, <b>--message=</b><i>&lt;msg&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Use the given message as the tag message. If multiple <b>-m</b> options are given, their values are concatenated as separate paragraphs.<br><br><b><b>-F</b> <i>&lt;file&gt;</i>, <b>--file=</b><i>&lt;file&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Take the tag message from the given file. Use <b>-</b> to read from standard input.<br><br><b><b>-d</b>, <b>--delete</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Delete the specified tags.<br><br><b><b>-f</b>, <b>--force</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Replace an existing tag with the new one (object or message). Use with caution as it rewrites history for others.<br><br><b><b>-l</b>, <b>--list</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;List tags with optional patterns. This is the default action if no other options are given.<br><br><b><b>-v</b>, <b>--verify</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Verify the GPG signature of the given tags.<br><br><b><b>--contains</b> <i>&lt;commit&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Only list tags that contain the specified commit.<br><br><b><b>--no-contains</b> <i>&lt;commit&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Only list tags that <i>do not</i> contain the specified commit.<br><br><b><b>--points-at</b> <i>&lt;object&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Only list tags that point at the given object (e.g., a commit, tree, or blob).<br><br><b><b>--sort=</b><i>&lt;key&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sort the output of tags based on the specified key (e.g., <i>version:refname</i>, <i>creatordate</i>).<br><br>


title: DESCRIPTION
content:
The <b>git tag</b> command is used to <i>create, list, delete, and verify tags</i> in a Git repository. Tags are permanent pointers to specific points in history, commonly used to mark release points (e.g., v1.0, v2.0). Unlike branches, tags are not meant to move once created. Git supports two main types of tags:<br><br>1.  <b>Lightweight Tags</b>: These are simply pointers to a specific commit. They are like a branch that never moves, typically used for private or temporary tagging.<br>2.  <b>Annotated Tags</b>: These are full Git objects stored in the Git database. They contain a tagger name, email, date, and a tagging message, and can be GPG-signed for verification. Annotated tags are recommended for public releases because they provide valuable metadata and ensure authenticity. They are immutable and point to a specific commit.<br><br>The command allows users to list existing tags, create new ones (either lightweight or annotated), delete obsolete tags, and verify the cryptographic signatures of signed tags, ensuring the integrity and origin of the tagged commit. Tags are crucial for navigation and stable release management in Git workflows.


title: CAVEATS
content:
<ul><li><b>Tags are not automatically pushed</b>: Unlike branches, Git tags are not automatically pushed to remote repositories when you run <code>git push</code>. You must explicitly push tags using <code>git push --tags</code> or <code>git push origin &lt;tagname&gt;</code>.</li><li><b>Replacing tags with <code>--force</code></b>: Using the <code>-f</code> or <code>--force</code> option to overwrite an existing tag is generally discouraged, especially on shared repositories, as it can cause confusion and issues for other collaborators who might have already fetched the original tag. If a tag needs to be moved or corrected, it's often better to delete the old tag and create a new one, communicating the change.</li><li><b>Annotated vs. Lightweight</b>: Always prefer <i>annotated tags</i> for releases or public milestones. <i>Lightweight tags</i> lack important metadata (tagger, date, message) and cannot be signed, making them less suitable for formal releases and integrity checks.</li></ul>


title: LIGHTWEIGHT VS. ANNOTATED TAGS
content:
<i>Lightweight tags</i> are simple pointers to a commit, similar to a local branch that doesn't move. They contain no extra information.<br><br><i>Annotated tags</i> are full Git objects. They include the tagger's name, email, date, and a tagging message. They can also be GPG-signed, providing authenticity verification. For public releases or important milestones, <b>annotated tags are strongly recommended</b> due to their rich metadata and verifiability. Use <b>-a</b> for annotated, or <b>-s</b> for signed annotated tags.


title: SIGNING TAGS FOR AUTHENTICITY
content:
When creating an <i>annotated tag</i>, you can sign it using your GPG key with the <b>-s</b> (<b>--sign</b>) option. This cryptographic signature ensures that the tag was indeed created by you and that its contents have not been tampered with. Others can then verify the tag's authenticity using <b>git tag -v &lt;tagname&gt;</b>, adding a layer of trust to your releases.


title: PUSHING TAGS TO REMOTES
content:
By default, <b>git push</b> does not push your tags to the remote repository. To share your tags, you must explicitly push them. You can push all local tags that are not yet on the remote using <b>git push --tags</b>. Alternatively, to push a specific tag, use <b>git push &lt;remote&gt; &lt;tagname&gt;</b>. Remember that once a tag is pushed, changing or deleting it on the remote requires extra care and coordination.


title: HISTORY
content:
The concept of tagging specific points in history has been a fundamental feature of version control systems long before Git. In Git, tags were integral to its design from the outset, providing a stable, immutable reference for key project milestones like releases. The distinction between <i>lightweight</i> and <i>annotated tags</i>, with the latter being full Git objects capable of carrying metadata and GPG signatures, reflects Git's emphasis on data integrity and decentralized trust. While the core functionality has remained consistent, the command has seen enhancements in listing capabilities (e.g., <code>--contains</code>, <code>--sort</code>) and verification options to support complex repository histories and secure release management practices. Its usage remains central to publishing stable software versions.


title: PARAMETERS
content:
<b><I>file</I>...</b><br>&nbsp;&nbsp;&nbsp;&nbsp;One or more files whose timestamps are to be updated or which are to be created if they do not exist. These files are typically then staged for Git.<br><br><b>-a</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Change only the access time of the file(s).<br><br><b>-m</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Change only the modification time of the file(s).<br><br><b>-c, --no-create</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Do not create any files; only update timestamps of existing files. If a file does not exist, no action is performed.<br><br><b>-r <I>file</I>, --reference=<I>file</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Use the access and modification times from a specified <I>reference file</I> instead of the current time. The timestamps of the reference file are applied to the target file(s).<br><br><b>-t [[CC]YY]MMDDhhmm[.ss]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Use a specified time instead of the current time. The format allows specifying century (CC), year (YY), month (MM), day (DD), hour (hh), minute (mm), and optionally seconds (ss).<br><br><b>--</b><br>&nbsp;&nbsp;&nbsp;&nbsp;A convention used to signify the end of command options. All subsequent arguments are treated as filenames, even if they begin with a hyphen (-).<br><br>


title: DESCRIPTION
content:
The <B>git-touch</B> command is <B>not a standard Linux or Git command</B>. It commonly refers to a user-defined <I>Git alias</I> or a custom <I>shell script</I> that combines the functionality of the standard <B>touch(1)</B> utility with Git operations, most frequently <B>git-add(1)</B>. Its primary purpose is to provide a convenient way to create new empty files, or update the access and modification timestamps of existing files, and then immediately stage these changes into the Git index. This streamlines the workflow for developers who often need to 'touch' files and ensure they are tracked by Git, without manually running both <B>touch</B> and <B>git add</B> separately.


title: CAVEATS
content:
The functionality of <B>git-touch</B> is entirely dependent on its specific implementation as a user-defined alias or script. It is <B>not</B> distributed as part of Git or standard Linux utilities, meaning its behavior, supported options, and even existence can vary widely between different development environments. Users should consult their Git configuration or custom scripts to understand its precise behavior. If implemented poorly, it could lead to unexpected file modifications or Git staging issues, such as overwriting existing content (though the standard <B>touch</B> utility itself does not overwrite file content, only metadata).


title: COMMON IMPLEMENTATIONS
content:
A typical and widely used implementation of <B>git touch</B> as a Git alias might look like this, defined in your Git configuration (e.g., via <B>git config</B>):<br><br><code>git config --global alias.touch '!touch "$@" && git add "$@"'</code><br><br>This alias allows passing all arguments (indicated by <code>"$@"</code>) directly to the <B>touch</B> command, and then subsequently to <B>git add</B>. This ensures that any files created or whose timestamps are modified by <B>touch</B> are automatically staged for the next Git commit. Other implementations might add more complex logic, such as immediately committing changes, handling specific file types, or providing additional custom options.


title: HISTORY
content:
As <B>git-touch</B> is not a standard command, it lacks a formal development history or official releases. Its emergence is a testament to the Git community's flexibility in extending Git's capabilities through aliasing and scripting. Developers frequently create it as a personal convenience utility, arising from the common workflow need to quickly create new files or update existing ones and immediately incorporate them into the Git repository's staging area. Its specific implementation varies, but the underlying concept of combining <B>touch</B> with <B>git add</B> has been a persistent user-driven enhancement for streamlining Git workflows.


title: SYNOPSIS
content:
<I>git undo</I> [<I>commit-ish</I>]<br><I>git undo</I> [<I>--hard</I> | <I>--soft</I> | <I>--mixed</I>]


title: PARAMETERS
content:
<b><I>commit-ish</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Optional</I>. When used without <I>--hard</I>, <I>--soft</I>, or <I>--mixed</I> options, this specifies the commit to revert. It can be a commit hash, a branch name, or a relative reference like <I>HEAD~1</I>. If omitted, <I>git undo</I> defaults to reverting the last commit (<I>HEAD</I>).<br><br><b><I>--hard</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Optional</I>. When specified, performs a destructive undo by resetting the branch to the commit immediately preceding <I>HEAD</I> (<I>HEAD~1</I>), equivalent to <I>git reset --hard HEAD~1</I>. This permanently discards all uncommitted changes in the working directory and staging area. This option is mutually exclusive with <I>commit-ish</I>.<br><br><b><I>--soft</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Optional</I>. When specified, performs an undo by resetting the branch to <I>HEAD~1</I>, equivalent to <I>git reset --soft HEAD~1</I>. This moves the branch pointer but keeps the changes that were in the undone commit(s) in the staging area (index). This option is mutually exclusive with <I>commit-ish</I>.<br><br><b><I>--mixed</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Optional</I>. When specified, performs an undo by resetting the branch to <I>HEAD~1</I>, equivalent to <I>git reset --mixed HEAD~1</I>. This is the default behavior for <I>git reset</I>. It moves the branch pointer and keeps the changes from the undone commit(s) in the working directory as unstaged changes. This option is mutually exclusive with <I>commit-ish</I>.<br><br>


title: DESCRIPTION
content:
<i>git-undo</i> is a convenience command, often provided by third-party Git utility collections like <I>git-extras</I>, designed to simplify common "undo" operations in a Git repository. It typically acts as a wrapper around more fundamental Git commands such as <I>git revert</I> and <I>git reset</I>. By default, when invoked without specific options, it often performs a non-destructive undo, similar to <I>git revert HEAD</I>, creating a new commit that reverses the changes of the last commit. However, it also provides options, such as <I>--hard</I>, <I>--soft</I>, or <I>--mixed</I>, to invoke <I>git reset</I> for more aggressive undo actions, allowing users to move the branch pointer and discard changes in the working directory or staging area. Its primary purpose is to abstract away the complexity of choosing the correct underlying Git command for various undo scenarios, making it quicker and easier for users to revert or reset their repository state.


title: CAVEATS
content:
<I>git-undo</I> is not a standard command included with Git; it typically needs to be installed as part of a third-party package like <I>git-extras</I> or implemented as a custom shell alias/script.<br>The <I>--hard</I> option is destructive: it will permanently discard uncommitted changes and move the branch pointer, leading to potential data loss if not used carefully.<br>Its exact behavior can vary slightly depending on the specific implementation (e.g., from <I>git-extras</I> vs. a custom script), so it's always good to understand what it does under the hood.


title: USAGE EXAMPLES
content:
To revert the last commit, creating a new commit that undoes its changes:<br><I>git undo</I><br><br>To revert a specific commit identified by its hash:<br><I>git undo 1a2b3c4d</I><br><br>To reset the branch to the previous commit, discarding all local uncommitted changes (use with caution, this is destructive):<br><I>git undo --hard</I><br><br>To reset the branch to the previous commit, keeping the changes from that commit in the staging area:<br><I>git undo --soft</I><br><br>To reset the branch to the previous commit, keeping the changes from that commit in the working directory as unstaged changes:<br><I>git undo --mixed</I>


title: HISTORY
content:
The concept of a simple "undo" command in Git arose from the common need to quickly reverse recent changes without needing to remember the intricacies of <I>git revert</I> or <I>git reset</I>. While not part of the core Git distribution, various third-party projects and individual users have created versions of <I>git-undo</I> to streamline workflows. A notable implementation is found within <I>git-extras</I>, a popular collection of community-contributed Git utilities, which integrates <I>git-undo</I> as a convenient wrapper around frequently used undo operations. Its development is driven by the desire to make Git more approachable for everyday tasks.


title: PARAMETERS
content:
<b>--all</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Unlocks all files currently locked by the current user on the Git LFS server. This option cannot be used with specific paths.<br><br><b>--force</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Unlocks a file even if it was locked by another user. This requires appropriate permissions on the Git LFS server, often administrative access.<br><br><b><path>...</b><br>&nbsp;&nbsp;&nbsp;&nbsp;One or more paths to the files to be unlocked. These paths must be relative to the repository root. This argument is omitted when using the <b>--all</b> option.<br><br>


title: DESCRIPTION
content:
The <b>git lfs unlock</b> command is used to release file locks on the Git LFS server. <br><br>When a file is locked using <b>git lfs lock</b>, it prevents other collaborators from modifying that specific file on the server, ensuring that only the locking user can push changes to it. This mechanism is particularly useful for binary or large files that Git cannot efficiently merge, helping to avoid merge conflicts. <br><br><b>git lfs unlock</b> allows the user who originally acquired the lock to release it, making the file available for modification by others. It can also be used with the <b>--force</b> option by an administrator or a user with appropriate permissions to unlock a file that was locked by another user, overriding their lock.


title: CAVEATS
content:
Unlocking a file locked by another user using <b>--force</b> requires administrative permissions on the Git LFS server. Misuse can lead to loss of work if another user is actively working on the locked file. <br><br>Locks are stored on the Git LFS server, not locally. Therefore, a network connection to the server is required for this command to succeed. <br><br>This command only affects files tracked by Git LFS.


title: PERMISSIONS
content:
For <b>git lfs unlock</b> to succeed when using the <b>--force</b> option, the user must have administrative privileges or specific permissions configured on the Git LFS server. Otherwise, attempting to unlock a file locked by another user will result in an error.


title: SERVER INTERACTION
content:
The locking and unlocking operations are performed against the Git LFS server configured for your repository. This means that these commands require connectivity to the remote Git LFS endpoint to function correctly and update the lock status.


title: HISTORY
content:
File locking was introduced early in Git LFS's development to address challenges with concurrent modifications of large binary files that Git's standard merging capabilities couldn't handle well. It provides a more robust collaboration workflow for assets managed by Git LFS, ensuring atomic updates for specific files.


title: PARAMETERS
content:
<b><i>&lt;object&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The SHA-1 hash of the object to be unpacked from a packfile. The command will find the object within the repository's packfiles and write its unpacked content as a loose object.<br><br>


title: DESCRIPTION
content:
<i>git-unpack-file</i> is an internal <i>plumbing</i> command in Git. Its primary purpose is to extract a specific Git object (identified by its SHA-1 hash) that is currently stored within a <i>packfile</i> and write it as a loose object in the <br><code>.git/objects/</code> directory. This process involves decompressing the object and, if it's a <i>delta-compressed</i> object, applying the delta against its base object.<br><br>Users typically do not invoke this command directly; it's used internally by other Git commands like <code>git cat-file --batch</code> to efficiently access packed objects. It plays a crucial role in Git's efficient storage mechanism, allowing objects to be stored compactly in packfiles while still providing a mechanism to access individual objects as if they were loose.


title: CAVEATS
content:
This is an internal <i>plumbing</i> command and is generally not intended for direct use by end-users. Misuse can lead to a corrupted repository. It only unpacks a single object, not an entire packfile. It assumes the necessary packfiles and their corresponding index files are present and valid in the repository.


title: OBJECT STORAGE MECHANISM
content:
This command is a key component of Git's efficient object storage system. Git stores objects in two primary ways: as <i>loose objects</i> (one file per object) or in <i>packfiles</i> (multiple objects compressed into a single file). Packfiles are highly optimized, often using <i>delta compression</i> where an object is stored as a difference from a base object. <i>git-unpack-file</i> handles the complex task of decompressing and reassembling such delta-compressed objects back into their full, original form.


title: HISTORY
content:
As part of Git's early design, efficiency in object storage was paramount. The packfile mechanism, introduced early on, allowed for compact storage of numerous objects, especially those with common history, via delta compression. <i>git-unpack-file</i> emerged as a necessary internal tool to reconstitute individual objects from these highly compressed packfiles, enabling other Git commands to access objects as if they were loose, regardless of their packed state. Its development was integral to supporting Git's robust and efficient object database.


title: PARAMETERS
content:
<b>-n, --dry-run</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Do not unpack objects. Instead, only verify the integrity of the pack file by checking checksums and object sizes. This can be used to validate a pack before committing to unpacking.<br><br><b>-q, --quiet</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Do not report details of unpacked objects to standard output. By default, the command may list the names of objects it unpacks.<br><br><b>-r, --recursive</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Unpack objects recursively. This option implies <I>--strict</I> and is often used internally when a pack might contain references to other objects that need unpacking or further processing.<br><br><b>--strict</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Abort if any errors are encountered during the unpacking process, such as checksum mismatches or corrupted object data. This ensures stricter error checking and prevents unpacking potentially corrupted or malicious objects into the repository.<br><br><b>--unpack-grafted</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Unpack objects that are referred to by graft points. This is relevant when the <I>core.unpackedGrafts</I> configuration option is enabled, allowing grafts to be handled during the unpack process.<br><br>


title: DESCRIPTION
content:
The <I>git-unpack-objects</I> command is a low-level <B>plumbing</B> command in Git. Its primary function is to read a packed archive (a <I>.pack</I> file) from standard input, and then extract and store the objects (commits, trees, blobs, tags) contained within this pack file into the local Git object database. This process makes the objects accessible and usable by the repository.<br><br>This command is typically used internally by other higher-level Git operations, such as <I>git-fetch-pack</I> (when fetching or pulling changes from a remote repository), <I>git-receive-pack</I> (when receiving pushed commits), or <I>git-index-pack</I> (which creates an index for a pack and then can unpack it). While it can verify the integrity of the pack file by checking checksums, it is not generally invoked directly by end-users. It serves as a crucial component for the efficient storage, transfer, and management of Git objects.


title: CAVEATS
content:
This command is considered a <B>plumbing</B> command and is not intended for direct use by end-users. It should only be invoked by higher-level Git commands or trusted scripts. Care should be taken when unpacking objects from untrusted sources without the <I>--strict</I> option, as Git's object model, while robust, relies on the integrity of the pack file for security and consistency.


title: EXIT STATUS
content:
The command exits with status <B>0</B> on success, indicating that the objects were unpacked or verified without critical errors. It exits with a non-zero status if an error occurs during unpacking or verification (e.g., corrupted pack file, I/O errors).


title: HISTORY
content:
The <I>git-unpack-objects</I> command has been a fundamental component of Git's object storage and network protocols since the early days of Git. As Git relies heavily on efficient packing and unpacking of objects for both storage optimization and network transfer, this command's core functionality has remained essential and largely unchanged, reflecting its foundational role in Git's internal architecture.


title: PARAMETERS
content:
<b><b>--add</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Add specified file(s) to the index. This option is required when adding new paths that are not already in the index.<br><br><b><b>--remove</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Remove specified file(s) from the index. This option is required when removing paths.<br><br><b><b>--replace</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Combines the functionality of <b>--add</b> and <b>--remove</b>. It allows replacing existing entries in the index with new ones from the command line.<br><br><b><b>--refresh</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Checks the working tree against the index. Updates index entries with current metadata (e.g., permissions, size) from the worktree. It also identifies entries that are unmerged or missing from the worktree.<br><br><b><b>--really-refresh</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Similar to <b>--refresh</b>, but also checks the object contents (SHA-1) in addition to the metadata, which can be slower.<br><br><b><b>--chmod=(+|-)x</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets (<b>+x</b>) or unsets (<b>-x</b>) the executable bit for the specified path(s) in the index. This only affects the index entry, not the working directory file.<br><br><b><b>--skip-worktree</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the 'skip-worktree' bit for the specified path(s). Git will assume the worktree file is unchanged and ignore its modifications, useful for local configuration files.<br><br><b><b>--no-skip-worktree</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Unsets the 'skip-worktree' bit, allowing Git to track worktree changes for the specified path(s) again.<br><br><b><b>--assume-unchanged</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the 'assume-unchanged' bit. Git will assume the file's contents have not changed, primarily for performance in large repositories. Modifying the file in the worktree while this bit is set can lead to issues.<br><br><b><b>--no-assume-unchanged</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Unsets the 'assume-unchanged' bit, forcing Git to check the file's contents again.<br><br><b><b>--cacheinfo &lt;mode&gt;,&lt;object&gt;,&lt;path&gt;</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Adds a specific entry to the index directly, without checking the working tree. Requires a file mode (e.g., 100644), an object hash (SHA-1), and the path.<br><br><b><b>--stdin</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Reads paths from standard input, one per line, instead of from command line arguments.<br><br>


title: DESCRIPTION
content:
The <b>git update-index</b> command is a low-level Git utility used to directly manipulate the Git index (also known as the staging area). It allows you to register the current content of specific files in the index, stage changes for the next commit, or modify file metadata like permissions.<br><br>While commands like <b>git add</b> are typically used for staging changes, <b>git update-index</b> provides finer control over what gets stored in the index. It's often used by scripts or advanced users who need to bypass some of the checks or functionalities of higher-level commands. For example, it can be used to add the contents of a file without the file being present in the working directory, or to change the executable bit of a file in the index without affecting the working copy.


title: CAVEATS
content:
<b>git update-index</b> is a low-level command. For most common use cases, <b>git add</b> is the preferred and safer option as it handles many details automatically. Incorrect use of <b>git update-index</b> can lead to inconsistencies in your Git repository's index, potentially causing unexpected behavior in future commits or merges. Use it with caution and only when you fully understand its implications.


title: THE GIT INDEX
content:
The Git index, often called the 'staging area', is a crucial component that acts as a temporary buffer between your working directory and your Git repository. It holds a snapshot of what your next commit will look like. <b>git update-index</b> is the command that allows Git to populate and manage this snapshot.


title: LOW-LEVEL USAGE
content:
Unlike user-friendly commands like <b>git add</b> which infer actions (add, modify, delete) based on file status, <b>git update-index</b> requires explicit instructions (e.g., <b>--add</b>, <b>--remove</b>). This makes it powerful for scripting but more error-prone for manual use. It's often used when you need to stage changes that are not present in the working directory, or when managing specific file flags.


title: SKIP-WORKTREE VS. ASSUME-UNCHANGED
content:
These two bits, manipulated via <b>--skip-worktree</b> and <b>--assume-unchanged</b>, control how Git handles files. <i>Skip-worktree</i> is typically used for user intent, marking files that should not be automatically updated or checked by Git (e.g., local configuration files). <i>Assume-unchanged</i> is a performance hint for Git, telling it to assume a file hasn't changed unless its mtime or ctime suggests otherwise, reducing the need for costly stat calls in large repositories. Modifying a file with <i>assume-unchanged</i> set can lead to unexpected behavior.


title: HISTORY
content:
<b>git update-index</b> is one of the foundational commands in Git, existing since the very early days of its development. It directly reflects Git's core design philosophy of maintaining a 'staging area' (the index) as an intermediate step between the working directory and the repository. While high-level commands like <b>git add</b> were later introduced to simplify user interaction, <b>git update-index</b> remains the underlying mechanism for interacting with the index programmatically and for advanced staging operations.


title: SYNOPSIS
content:
<b>git update-ref</b> [-m &lt;reason&gt;] (-d | --delete) &lt;ref&gt; [&lt;oldvalue&gt;]<br><b>git update-ref</b> [-m &lt;reason&gt;] [--no-deref] &lt;ref&gt; &lt;newvalue&gt; [&lt;oldvalue&gt;]<br><b>git update-ref</b> [-m &lt;reason&gt;] [--no-deref] [--single-reflog] [--create-reflog] --stdin<br><b>git update-ref</b> [--atomic] [--stdin]


title: PARAMETERS
content:
<b>ref</b><br>&nbsp;&nbsp;&nbsp;&nbsp;The name of the ref to update. For example, <I>HEAD</I> or <I>refs/heads/main</I>.<br><br><b>newvalue</b><br>&nbsp;&nbsp;&nbsp;&nbsp;The new object name (SHA-1 or SHA-256 hash) or ref name that <I>&lt;ref&gt;</I> should point to.<br><br><b>oldvalue</b><br>&nbsp;&nbsp;&nbsp;&nbsp;The expected current value of <I>&lt;ref&gt;</I>. If provided, the update will only occur if <I>&lt;ref&gt;</I> currently points to <I>&lt;oldvalue&gt;</I>, ensuring a compare-and-swap behavior.<br><br><b>-d, --delete</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Delete the specified ref.<br><br><b>-m <reason></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Update the reflog for <I>&lt;ref&gt;</I> with a message indicating the reason for the update.<br><br><b>--no-deref</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Update a symbolic ref directly instead of updating the ref it points to.<br><br><b>--create-reflog</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Create a reflog for the ref, even if it's not normally logged (e.g., tags).<br><br><b>--single-reflog</b><br>&nbsp;&nbsp;&nbsp;&nbsp;This flag is a no-op, kept for historical reasons.<br><br><b>--stdin</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Read ref updates from standard input in the format: <I>oldvalue newvalue ref</I>. Allows for atomic batch updates.<br><br><b>--atomic</b><br>&nbsp;&nbsp;&nbsp;&nbsp;When used with <I>--stdin</I>, ensures that all updates succeed or all fail as a single atomic transaction.<br><br><b>--abort-if-ungrouped</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Used with <I>--stdin</I>, aborts the operation if any line from stdin is not part of a group (i.e., not preceded by <I>start_group</I> and followed by <I>end_group</I>).<br><br>


title: DESCRIPTION
content:
git-update-ref is a fundamental Git <I>plumbing</I> command used to safely and atomically update the object name or symbolic reference stored in a ref. Refs are typically files located in the <I>.git/refs/</I> directory (e.g., <I>.git/refs/heads/main</I> for the <I>main</I> branch). This command ensures that updates are performed reliably, preventing race conditions and data corruption, especially in environments with concurrent operations. It allows users to update a ref to a <I>newvalue</I>, optionally checking against an <I>oldvalue</I> for a compare-and-swap operation. It can also be used to delete a ref or create a new one. The command records updates in the reflog, providing a history of changes to the ref, which is crucial for operations like <I>git reflog</I>. For advanced use cases, it supports reading multiple update instructions from standard input, enabling efficient bulk operations.


title: CAVEATS
content:
Directly manipulating ref files in the <I>.git/refs/</I> directory is highly discouraged. Always use <I>git-update-ref</I> to ensure atomic and safe updates, especially when dealing with concurrent operations or symbolic refs. Incorrect manual modifications can lead to repository corruption.


title: DISCUSSION
content:
While many high-level Git commands (like <I>git commit</I>, <I>git branch</I>, <I>git reset</I>) automatically update refs as part of their operation, <I>git-update-ref</I> provides a low-level, precise control for managing refs directly. It is a critical "plumbing" command that ensures the integrity of the Git repository's internal structure. Its ability to perform compare-and-swap updates (<I>oldvalue</I> check) is vital for ensuring that updates are applied only if the ref is in an expected state, preventing accidental overwrites due to concurrent changes. The <I>--stdin</I> option further enhances its utility by allowing multiple ref updates to be performed as a single atomic operation, which is crucial for performance and consistency in complex scenarios, such as garbage collection or repository migrations.


title: DESCRIPTION
content:
<i>git-update-server-info</i> is a Git plumbing command used to generate or update essential auxiliary files in a bare Git repository. Specifically, it creates or refreshes the <i>info/refs</i> and <i>objects/info/packs</i> files.<br><br>These files are crucial for Git clients that interact with the repository using the 'dumb' HTTP protocol. The <i>info/refs</i> file provides a list of all available references (branches, tags) and their corresponding object IDs, allowing clients to discover what's in the repository. The <i>objects/info/packs</i> file lists all available packfiles, which contain the actual Git objects.<br><br>Without these files, a 'dumb' HTTP client cannot discover the repository's contents and thus cannot clone or fetch. 'Smart' protocols (like SSH, the native Git protocol, or smart HTTP) do not require these files as they negotiate references and transfer objects directly with the server.<br><br>This command is typically invoked automatically as part of a <b>post-update</b> hook after a successful push to ensure the auxiliary files are always up-to-date. It requires the repository to be bare; it will fail if run in a non-bare repository.


title: CAVEATS
content:
The <i>git-update-server-info</i> command is specifically designed for and only relevant to serving Git repositories via the 'dumb' HTTP protocol. It has no effect on smart protocols (e.g., Git protocol, SSH, or smart HTTP). It also requires the repository to be a bare repository; running it in a non-bare repository will result in an error. Care should be taken with symlinks, as certain configurations (e.g., <b>http.serverAllowSymlinks</b>) can expose them.


title: AUTOMATIC EXECUTION
content:
This command is most commonly executed automatically through a <b>post-update</b> hook in the Git repository. When a user pushes changes to a bare repository, the <b>post-update</b> hook triggers <i>git-update-server-info</i> to ensure that the <i>info/refs</i> and <i>objects/info/packs</i> files are refreshed, making the latest changes discoverable by 'dumb' HTTP clients.


title: PROTOCOL SPECIFICITY
content:
It's crucial to understand that <i>git-update-server-info</i> solely serves the 'dumb' HTTP protocol. For users accessing your repository via SSH, the native Git protocol (<b>git://</b>), or 'smart' HTTP (which uses <b>git-http-backend</b>), this command's output is not used. These 'smart' protocols negotiate directly with the Git server for references and object data, making the auxiliary info files redundant for their operation.


title: HISTORY
content:
<i>git-update-server-info</i> dates back to the early days of Git, playing a vital role in enabling web-based access to repositories before 'smart' HTTP protocol became common. It was essential for simple static HTTP servers to offer Git read-only access. While modern Git hosting often relies on smart protocols, this command remains relevant for basic, low-overhead HTTP setups, embodying Git's flexibility in server-side deployment.


title: PARAMETERS
content:
<b><b>--exec=&lt;git-upload-archive&gt;</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the full path to the <i>git-upload-archive</i> command on the remote host. This is useful for environments where the command is not in the standard PATH or a custom binary is used.<br><br>


title: DESCRIPTION
content:
<i>git-upload-archive</i> is a crucial <i>plumbing</i> command within Git, primarily designed to facilitate the serving of repository archives to clients. It operates on the server-side, typically invoked by the <b>git-archive</b> command over a network connection like SSH. Its core function is to receive a list of desired paths (relative to the repository's root) from the client and then stream the corresponding archive data back.<br><br>This command is not intended for direct use by end-users; rather, it forms an essential component of Git's remote repository interaction, enabling operations such as <b>git archive --remote</b>. While SSH is the most common transport, it can be configured to work over other protocols. It ensures that when a client requests an archive, the server can efficiently pack and transmit the requested files and directories.


title: PROTOCOL
content:
The client communicates with <i>git-upload-archive</i> by sending a series of lines, each representing a path relative to the repository's root, followed by a flush packet. The server then responds by sending the archive data. This low-level protocol is handled automatically by the <b>git-archive</b> client command and is not typically interacted with directly by users.


title: PARAMETERS
content:
<b><i>&lt;directory&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The path to the Git repository on the server that <i>git-upload-pack</i> should serve objects from. This is usually an absolute or relative path to a bare repository's <b>.git</b> directory or the repository itself.<br><br>


title: DESCRIPTION
content:
<i>git-upload-pack</i> is a "plumbing" command, meaning it's an internal Git command not typically invoked directly by end-users. Its primary function is to serve Git objects (commits, trees, blobs, tags) from a remote repository to a client. When you run <b>git fetch</b>, <b>git pull</b>, or <b>git clone</b>, the client-side Git process communicates with a remote server. On the server, <i>git-upload-pack</i> is executed.<br><br>It reads "want" and "have" lines from the client's standard input, identifies which objects the client needs, and then sends a packfile containing those objects to the client's standard output. This command forms the core of Git's "smart" protocol for transferring data efficiently over network connections like SSH, HTTP(S), or the native Git protocol (<b>git://</b>). It ensures only necessary data is transferred, optimizing bandwidth usage and facilitating the distributed nature of Git repositories.


title: CAVEATS
content:
<i>git-upload-pack</i> is an internal command and should generally not be executed directly by users. It relies on specific Git protocol messages exchanged via standard input/output. Incorrect direct usage or exposing it without proper security mechanisms (e.g., via a misconfigured <i>git-daemon</i> or SSH setup) can lead to security vulnerabilities or unexpected behavior. It is designed to be invoked by higher-level Git commands or services like SSH or <i>git-daemon</i>.


title: PROTOCOLS AND USAGE
content:
<i>git-upload-pack</i> is typically invoked by a server-side process handling various Git protocols:<br><br><b>SSH:</b> When you clone or fetch via SSH (e.g., <b>git clone user@host:/path/to/repo.git</b>), the SSH daemon on the server executes <i>git-upload-pack</i> within the context of the requested repository. The SSH connection acts as the transparent channel for <b>stdin</b>/<b>stdout</b>.<br><br><b>Smart HTTP(S):</b> For HTTP(S) access, a web server (like Apache or Nginx) or a Git hosting service routes requests to a CGI script or an application that executes <i>git-upload-pack</i>. This setup often involves <b>git-http-backend</b> which acts as the intermediary.<br><br><b>Git Protocol (git://):</b> The <i>git-daemon</i> service listens for incoming Git protocol connections and, upon request, forks <i>git-upload-pack</i> to handle the object transfer for public, read-only access.


title: HISTORY
content:
<i>git-upload-pack</i> has been a fundamental component of Git's network transfer capabilities since its early days, essential for enabling the distributed nature of Git. It was designed by Linus Torvalds and the early Git developers to provide an efficient and stateless mechanism for clients to request and receive repository objects from a server, forming the basis of the "smart" protocol. Its core functionality has remained largely consistent, evolving with performance optimizations and protocol enhancements over time.


title: PARAMETERS
content:
<b>--index</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set utimes from the Git index. This is typically the default behavior if no <B>--commit</B> is specified.<br><br><b>--commit=<tree-ish></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set utimes from the specified commit or tree object. The <I>tree-ish</I> can be a commit hash, branch name, or any reference that resolves to a tree.<br><br><b>--dry-run</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Perform a dry run. Do not actually change any file timestamps, but instead show what actions would be taken.<br><br><b>--verbose</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Be verbose. Display more details about the operations being performed, such as which files are being processed and their new timestamps.<br><br><b><path>...</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Limit the operation to the specified paths. If no paths are provided, <B>git-utimes</B> will operate on all tracked files in the current working directory.<br><br>


title: DESCRIPTION
content:
git-utimes is a Git subcommand (often found in <I>git-contrib</I>) designed to restore the access and modification times (utimes) of files within the Git working tree. It provides a mechanism to set these timestamps based on information from the Git index or from a specific commit's tree-ish. This utility is particularly valuable in situations where file timestamps are unintentionally altered or lost – for instance, during <B>git clone</B> operations, <B>git checkout</B> to a different branch, or when files are copied outside of Git's direct management. Preserving these timestamps is crucial for various reasons, such as ensuring that build systems like <B>make</B> accurately detect whether files need recompilation, or for maintaining consistency in timestamp-sensitive applications. By default, <B>git-utimes</B> operates on all files currently tracked by Git within the active working directory, making it a powerful tool for maintaining the integrity of your project's file metadata.


title: CAVEATS
content:
git-utimes is typically a script located in the <B>git-contrib</B> repository, meaning it is not a built-in command of the core Git distribution. It may not be available by default on all systems and might require manual installation or adding to your PATH.<br>File modification times (<I>mtime</I>) stored within Git are generally based on the time the blob object was created or committed, not necessarily the original file's modification time. This command restores timestamps based on Git's internal records, which might differ from the absolute original file timestamps.<br>Access times (<I>atime</I>) are generally not tracked by Git. This command might set <I>atime</I> to match <I>mtime</I> or leave it as the current time, depending on the script's specific implementation and the underlying operating system's capabilities.


title: PURPOSE IN BUILD SYSTEMS
content:
This command is particularly valuable in environments where build systems (like <B>make</B>) rely on file modification times to determine if a recompilation or rebuild is necessary. If a Git operation (like <B>git clone</B> or <B>git checkout</B>) updates files without preserving original timestamps, <B>make</B> might incorrectly rebuild everything, even if the source code hasn't changed. <B>git-utimes</B> helps prevent this by restoring timestamps consistent with the repository state, ensuring efficient and correct build processes.


title: TIMESTAMP GRANULARITY
content:
The precision of the timestamps set by <B>git-utimes</B> depends on the operating system's capabilities and the timestamps stored by Git. Git typically stores timestamps with second-level precision, while some modern file systems support sub-second precision. This might lead to minor discrepancies if sub-second precision was crucial for the original file.


title: HISTORY
content:
<B>git-utimes</B> originated as a supplementary script within the <B>git-contrib</B> collection, which serves as a repository for various useful but non-core Git utilities. Its development addresses a common pain point for Git users: the loss of original file timestamps during standard Git operations like cloning or checking out branches. This utility provides a solution for scenarios where maintaining accurate timestamps is crucial, especially for build systems that rely on them for dependency tracking, thus filling a gap in Git's native timestamp management capabilities.


title: PARAMETERS
content:
<b><i>&lt;variable&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The name of the logical Git variable to query. Supported variables include: <i>GIT_AUTHOR_IDENT</i>, <i>GIT_COMMITTER_IDENT</i>, <i>GIT_EDITOR</i>, <i>GIT_PAGER</i>, <i>GIT_SSH_COMMAND</i>, <i>GIT_EXEC_PATH</i>, <i>GIT_PREFIX</i>, and <i>GIT_INTERNAL_TEST_DRIVER</i>.<br><br>


title: DESCRIPTION
content:
The <b>git-var</b> command is a low-level "plumbing" utility designed to query specific logical variables that Git maintains or utilizes internally. Unlike <b>git config</b>, which reads arbitrary configuration values, <b>git-var</b> focuses on a predefined set of variables crucial to Git's operational context, often related to user identification, internal paths, or the execution of external programs.<br><br>These variables include: <i>GIT_AUTHOR_IDENT</i> and <i>GIT_COMMITTER_IDENT</i> (which provide formatted author and committer identities), <i>GIT_EDITOR</i> and <i>GIT_PAGER</i> (determining the editor for interactive prompts and the pager for output display), <i>GIT_SSH_COMMAND</i> (for SSH operations), and <i>GIT_EXEC_PATH</i> (the absolute path where Git looks for its subcommands and helper programs). It also queries <i>GIT_PREFIX</i>, which represents the relative path from the current working directory to the top-level directory of the Git working tree.<br><br>This command is primarily intended for scripting purposes, allowing external scripts and Git's own internal mechanisms to reliably retrieve consistent information about its operating environment and state without needing to parse complex configuration files or outputs of other commands.


title: CAVEATS
content:
<b>git-var</b> is categorized as a "plumbing" command, indicating it's a low-level interface primarily for scripting and internal Git operations, not typically for direct end-user interaction. It queries a specific, limited set of internal Git variables and should not be confused with <b>git config</b>, which is used for reading and writing general Git configuration options.


title: VARIABLE TYPES AND THEIR MEANING
content:
<ul><li><b><i>GIT_AUTHOR_IDENT</i></b> and <b><i>GIT_COMMITTER_IDENT</i></b>: These variables output a formatted identity string (e.g., 'Name &lt;email&gt; Timestamp &plusmn;Timezone') derived from the <b>user.name</b>, <b>user.email</b>, and <b>user.date</b> configuration settings.</li><li><b><i>GIT_EDITOR</i></b>, <b><i>GIT_PAGER</i></b>, <b><i>GIT_SSH_COMMAND</i></b>: These variables return the determined paths or commands for external tools, as established by Git's configuration and environment variables.</li><li><b><i>GIT_EXEC_PATH</i></b>: Provides the absolute path where Git expects to find its helper programs and subcommands. This is crucial for Git's internal operation.</li><li><b><i>GIT_PREFIX</i></b>: Outputs the relative path from the current working directory to the top-level directory of the Git working tree. This is particularly useful when executing Git commands from a subdirectory within a repository.</li><li><b><i>GIT_INTERNAL_TEST_DRIVER</i></b>: A variable primarily used for internal Git testing purposes and not typically relevant for general usage.</li></ul>


title: HISTORY
content:
<b>git-var</b> has been a stable part of Git's plumbing commands for a significant period, serving its specific purpose of querying essential internal variables. Its functionality has remained largely consistent, focusing on providing reliable access to key operational parameters and identities for scripting and Git's internal processes. It was introduced to standardize how Git's own scripts and external tools could consistently determine certain crucial environmental and identity-related information.


title: PARAMETERS
content:
<b><b>-v</b>, <b>--verbose</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Print the contents of the signature and the verified data. This option provides more detailed information about the signature itself, including the signer's identity and key details.<br><br><b><b>--raw</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Print the raw GPG status output directly from the GPG program. This output is typically terse and machine-readable, useful for scripting or detailed debugging of GPG interactions.<br><br><b><b>&lt;commit&gt;...</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;One or more commit-ish identifiers (e.g., commit SHA-1, branch name, tag name) whose GPG signatures are to be verified. The command will process each specified commit sequentially.<br><br>


title: DESCRIPTION
content:
The <i>git-verify-commit</i> command is used to cryptographically verify the GPG (GNU Privacy Guard) signature of one or more Git commit objects. When a commit is signed using <i>git commit -S</i>, a GPG signature is embedded within the commit object. This command checks the validity of this signature using the GPG program installed on your system.<br><br>It validates whether the signature is intact, whether it corresponds to the commit's content, and whether it was made by a trusted key in your GPG keyring. This is crucial for establishing the authenticity and integrity of commits, especially in collaborative environments, ensuring that a commit truly came from the stated author and has not been tampered with since signing. The command relies on an external GPG program to perform the actual cryptographic verification.


title: CAVEATS
content:
Verification requires the GPG (or GnuPG) program to be installed and correctly configured on the system. The public key corresponding to the private key used to sign the commit must exist in your GPG keyring for the signature to be successfully verified as valid. If the key is not present, not trusted, or expired, the verification may fail or indicate an untrusted/invalid signature. Also, the command only verifies the signature of the commit object itself, not the content of the tree it points to.


title: EXIT STATUS
content:
The command exits with status 0 if all specified commits have valid GPG signatures and the verification process is successful. A non-zero exit status indicates a failure in verification (e.g., signature not found, invalid signature, or an underlying GPG error), signaling that the commit's authenticity or integrity could not be confirmed.


title: HISTORY
content:
<i>git-verify-commit</i> has been an integral part of Git's cryptographic verification capabilities since early versions, reinforcing the project's commitment to ensuring the integrity and authenticity of commit history. It works in conjunction with GPG, building upon established public-key cryptography standards to provide a mechanism for establishing trust in signed commits within a distributed version control system.


title: SYNOPSIS
content:
<b>git verify-pack</b> [--verbose | -v] [--stat-only | -s] &lt;pack-file&gt; [&lt;pack-file&gt; ...]


title: PARAMETERS
content:
<b><b>--verbose</b> | <b>-v</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show a detailed list of all objects, their sizes, and types. Also reports statistics like the number of objects, deltas, and loose objects. This provides the most comprehensive output.<br><br><b><b>--stat-only</b> | <b>-s</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Only show statistics about the pack file, without listing individual objects. This option is faster for very large pack files when only a summary is needed.<br><br><b><b>&lt;pack-file&gt;</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The path to the pack file (<I>.pack</I> extension) to be verified. Multiple pack files can be specified to verify them all in one invocation. These files are typically found in <I>.git/objects/pack/</I>.<br><br>


title: DESCRIPTION
content:
git-verify-pack is a Git <I>plumbing</I> command used to check the validity and consistency of a Git pack file and its corresponding index. Pack files are an efficient way Git stores objects (blobs, trees, commits, tags) by compressing them and delta-compressing similar objects. This command is crucial for ensuring data integrity, especially after network transfers or disk operations.<br><br>It reads the pack file, decompresses objects, verifies checksums (both object and pack checksums), and checks for consistency between the pack file and its .idx (index) file. Any inconsistencies, such as corrupted objects, incorrect sizes, or missing objects, are reported. It's often used by developers and system administrators for diagnostic purposes or as part of a robust backup strategy to confirm repository health. It helps identify potential data corruption before it leads to more severe issues within a Git repository.


title: CAVEATS
content:
This command operates directly on pack files and their indices; it is not a user-level command for general repository health checks like <I>git fsck</I>. It only reports corruption and does not attempt to fix it. Verifying very large pack files can be time-consuming and memory-intensive, especially with the <B>--verbose</B> option. It requires both the <I>.pack</I> and its corresponding <I>.idx</I> file to be present and correctly named (e.g., <I>pack-abc.pack</I> and <I>pack-abc.idx</I>).


title: RETURN STATUS
content:
<I>git-verify-pack</I> exits with a non-zero status code if any errors or inconsistencies are found during the verification process. It exits with zero status on success. This behavior makes it highly suitable for use in scripts to programmatically check pack file health.


title: OUTPUT FORMAT
content:
The command's output typically includes the pack file version, total number of objects, number of loose objects, number of delta objects, and various checksums (pack checksum, object checksums). When the <B>--verbose</B> option is used, it lists each object's type (e.g., blob, commit), its uncompressed size, and its offset within the pack file.


title: HISTORY
content:
Pack files and their verification mechanisms have been fundamental to Git's object storage model since its early days. The <I>git-verify-pack</I> command likely emerged as a core utility alongside the introduction of pack files to ensure the integrity of this optimized storage format. Its purpose has remained consistent: to provide a low-level diagnostic tool for validating the raw pack file data. It's a <I>plumbing</I> command, meaning it's intended for scripting and lower-level operations rather than direct daily use by end-users, reflecting its foundational role in Git's internal object database management.


title: PARAMETERS
content:
<b><b>&lt;tag&gt;...</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;One or more tag objects or references (e.g., tag names or object IDs) whose GPG signatures are to be verified. The command will process each specified tag.<br><br>


title: DESCRIPTION
content:
The <i>git-verify-tag</i> command is an internal Git utility used to cryptographically verify the GPG signature of one or more tag objects. It is typically invoked by <i>git tag -v &lt;tagname&gt;</i> when you want to ensure the authenticity and integrity of a signed tag.<br><br>When executed, <i>git-verify-tag</i> inspects the specified tag object(s), extracts the associated GPG signature, and attempts to verify it against the local GPG keyring. The output typically includes the GPG verification status, such as "good signature", "BAD signature", or "no signature", along with details of the signing key. A successful verification confirms that the tag has not been tampered with and was created by a trusted entity whose public key is present in your GPG keyring. This command is crucial for maintaining trust and security in distributed Git workflows.


title: CAVEATS
content:
Verification relies on the 'gpg' command-line tool being installed and properly configured on your system.<br>For a 'good signature' status, the public key of the tag's signer must be present and trusted in your local GPG keyring. If the key is not found or not trusted, the signature verification may fail or report 'unknown key'.<br>This command only verifies the GPG signature over the tag object itself; it does not verify the integrity of the commit that the tag points to.


title: EXIT STATUS
content:
The command exits with a status code indicating the outcome of the verification process:<br><i>0</i>: Successfully verified at least one tag, meaning a good signature was found, or the tag was unsigned (no signature detected).<br><i>128</i>: A usage error occurred, such as no tags being specified or an invalid tag reference.<br><i>Non-zero (other)</i>: GPG signature verification failed for one or more tags (e.g., bad signature, unknown key, or GPG error).


title: HISTORY
content:
GPG signing of tags was introduced early in Git's history, around version 1.4.0 (circa 2006), to provide cryptographic assurance for releases and checkpoints. The 'git-verify-tag' command serves as the underlying mechanism for validating these signatures, allowing users to confirm the authenticity of tags created by others. While initially an internal component, its functionality became a direct command for programmatic verification.


title: PARAMETERS
content:
<b><I>URL</I> ...</b><br>&nbsp;&nbsp;&nbsp;&nbsp;One or more URLs to open in the web browser. If no URLs are provided, the command typically relies on the <I>GITWEB_URL</I> environment variable.<br><br>


title: DESCRIPTION
content:
The <I>git-web--browse</I> command is an internal Git helper script primarily used by <I>git instaweb</I> to automatically open a web browser to the locally served Gitweb interface. When <I>git instaweb</I> starts a temporary web server displaying your repository via Gitweb, it invokes <I>git-web--browse</I> to launch your default web browser and navigate to the appropriate URL. While it's generally invoked indirectly, it can also be called directly to open specified URLs. It intelligently detects common web browsers installed on the system and attempts to launch the first one found, providing a seamless experience for viewing Git repositories through a web interface. Its behavior can be customized via environment variables, allowing users to specify a preferred browser or the URL to open.


title: CAVEATS
content:
The command relies on the availability of a recognized web browser executable on the system's PATH. If no suitable browser is found, it may fail to launch. Browser detection heuristics might not cover all installed browsers or might prioritize an unexpected one. When invoked directly without <I>git instaweb</I>, it often needs the <I>GITWEB_URL</I> environment variable to be set to open the intended Gitweb interface, unless URLs are provided as arguments.


title: ENVIRONMENT VARIABLES
content:
<I>git-web--browse</I> can be configured via the following environment variables:<br><br><b>GITWEB_BROWSER</b>: Specifies the command or browser to use for opening the URL. This variable overrides the default browser detection. The value can be a simple command name (e.g., <I>firefox</I>, <I>chromium</I>) or a full path to an executable.<br><b>GITWEB_URL</b>: Specifies the URL to open if no URLs are provided as command-line arguments. This is typically set by <I>git instaweb</I>.


title: HISTORY
content:
The <I>git-web--browse</I> script, along with <I>git instaweb</I>, has been a part of Git since its early days. It was introduced to simplify the process of quickly viewing Git repositories through a web interface, primarily for local debugging and demonstration purposes. Its development focused on providing robust cross-platform browser detection and launching capabilities to integrate seamlessly with the <I>git instaweb</I> workflow, reducing manual steps for users.


title: PARAMETERS
content:
<b>-p, --patch</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Show the patch (diff) for each commit.</i><br><br><b>-s, --no-patch</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Suppress showing patch output (default if not using <b>-p</b>).</i><br><br><b>-U&lt;n&gt;, --unified=&lt;n&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Generate diffs with <b>n</b> lines of context instead of the default 3.</i><br><br><b>--abbrev-commit</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Show only the abbreviated commit hash.</i><br><br><b>--pretty=&lt;format&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Format the output using a predefined style or custom format. <B>Note:</B> <b>git log</b> offers superior formatting.</i><br><br><b>-n &lt;n&gt;, --max-count=&lt;n&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Limit the number of commits to output.</i><br><br><b>--since=&lt;date&gt;, --after=&lt;date&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Show commits more recent than a specific date.</i><br><br><b>--until=&lt;date&gt;, --before=&lt;date&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Show commits older than a specific date.</i><br><br><b>--author=&lt;pattern&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Limit commits to those where the author matches the pattern.</i><br><br><b>--committer=&lt;pattern&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Limit commits to those where the committer matches the pattern.</i><br><br><b>--grep=&lt;pattern&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Limit commits to those with commit messages matching the pattern.</i><br><br><b>-S&lt;string&gt;, --pickaxe-regex</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Show commits that add or delete an instance of the given string (search by content changes).</i><br><br><b>-G&lt;regex&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Show commits where the diff introduces or removes lines matching the regex.</i><br><br><b>&lt;path&gt;...</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Limit commits to those that touch the specified paths. The <b>--</b> separator can be used for clarity.</i><br><br>


title: DESCRIPTION
content:
<i>The <b>git-whatchanged</b> command displays commit history and, optionally, patch differences for changes made to a Git repository. It is a historical command that has largely been superseded by <b>git log -p</b>, which offers more flexibility and control over output formatting. <b>git-whatchanged</b> traverses the commit graph starting from the HEAD (or specified revisions) and shows each commit's metadata (author, date, commit message hash) along with a summary of changed files (diffstat) and the actual patch content if requested. It's useful for quickly reviewing what changes were introduced by a series of commits, especially when migrating from older VCS systems or working with scripts that historically used this command.</i>


title: CAVEATS
content:
<i>The <b>git-whatchanged</b> command is considered a legacy command. While it still functions, <b>git log -p</b> is the modern and recommended alternative for viewing commit history with patches. <b>git log</b> offers a richer set of options for filtering, formatting, and traversing the commit graph, making it significantly more powerful and flexible. New scripts and workflows should strongly prefer <b>git log</b>.</i>


title: <I>DEFAULT OUTPUT</I>
content:
<i>By default, <b>git-whatchanged</b> prints the commit ID, author, and date, followed by a diffstat (summary of changes) for each commit, without the actual patch content. To see the full patch, the <b>-p</b> option is required.</i><br>


title: <I>COMPARISON WITH GIT LOG</I>
content:
<i>While <b>git-whatchanged</b> focuses on showing changes, <b>git log</b> is a more general-purpose history browser. Any query achievable with <b>git-whatchanged</b> can be done with <b>git log -p</b>, often with greater flexibility and more pleasant output. For instance, <b>git whatchanged -p</b> is largely equivalent to <b>git log -p --stat --summary</b>.</i>


title: HISTORY
content:
<i><b>git-whatchanged</b> was one of the earliest commands in Git's history, designed to provide a "changelog" like view, similar to <code>cvs annotate</code> or <code>svn log</code>. Its primary purpose was to show which commits changed what files. As Git matured, the more generalized and powerful <b>git log</b> command evolved, incorporating and expanding upon the functionalities of <b>git-whatchanged</b>, particularly with its extensive formatting and filtering capabilities. Consequently, <b>git-whatchanged</b> has been largely deprecated in favor of <b>git log -p</b> since Git version 1.7.0, though it remains available for backward compatibility.</i>


title: SYNOPSIS
content:
<b>git worktree</b> <I>subcommand</I> [<I>options</I>] [<I>arguments</I>]<br><br>Common subcommands:<br>  <b>add</b>: <b>git worktree add</b> [-b <I>new-branch</I>] [--track] [--bare] [--[no-]orphan] [--[no-]checkout] [--detach] [--force] [--dry-run] <I>path</I> [<I>commit-ish</I>]<br>  <b>list</b>: <b>git worktree list</b> [--porcelain] [--bare]<br>  <b>remove</b>: <b>git worktree remove</b> [--force] <I>path</I><br>  <b>prune</b>: <b>git worktree prune</b> [--expire <I>time</I>]<br>  <b>move</b>: <b>git worktree move</b> <I>path</I> <I>new-path</I><br>  <b>lock</b>: <b>git worktree lock</b> <I>path</I><br>  <b>unlock</b>: <b>git worktree unlock</b> <I>path</I>


title: PARAMETERS
content:
<b><b>add</b> <I>path</I> [<I>commit-ish</I>]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Creates a new working tree at <i>&lt;path&gt;</i>, optionally checking out <i>&lt;commit-ish&gt;</i>.<br><br><b><b>list</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Lists all linked working trees.<br><br><b><b>remove</b> <I>path</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Removes a linked working tree at <i>&lt;path&gt;</i>.<br><br><b><b>prune</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Removes stale working tree information (directories corresponding to removed worktrees).<br><br><b><b>move</b> <I>path</I> <I>new-path</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Moves a linked working tree from <i>&lt;path&gt;</i> to <i>&lt;new-path&gt;</i>.<br><br><b><b>lock</b> <I>path</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Marks a working tree as 'locked', preventing accidental removal.<br><br><b><b>unlock</b> <I>path</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Unlocks a previously locked working tree.<br><br><b>--detach</b><br>&nbsp;&nbsp;&nbsp;&nbsp; (for <b>add</b>) Check out <i>HEAD</i> into a detached <i>HEAD</i> state in the new worktree.<br><br><b>-b <I>new-branch</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp; (for <b>add</b>) Create and checkout a new branch named <i>&lt;new-branch&gt;</i> in the new worktree.<br><br><b>--track</b><br>&nbsp;&nbsp;&nbsp;&nbsp; (for <b>add</b>) Set up the new branch to track a remote branch if <i>&lt;commit-ish&gt;</i> is a remote-tracking branch.<br><br><b>--bare</b><br>&nbsp;&nbsp;&nbsp;&nbsp; (for <b>add</b>, <b>list</b>) For <b>add</b>, creates a bare worktree (no working files). For <b>list</b>, lists bare worktrees.<br><br><b>--[no-]orphan</b><br>&nbsp;&nbsp;&nbsp;&nbsp; (for <b>add</b>) Create an orphan branch in the new worktree (--orphan) or prevent it (--no-orphan).<br><br><b>--[no-]checkout</b><br>&nbsp;&nbsp;&nbsp;&nbsp; (for <b>add</b>) Perform (--checkout) or skip (--no-checkout) the initial checkout of files.<br><br><b>--force</b><br>&nbsp;&nbsp;&nbsp;&nbsp; (for <b>add</b>, <b>remove</b>) For <b>add</b>, force creation into a non-empty directory. For <b>remove</b>, force removal of a dirty worktree.<br><br><b>--dry-run</b><br>&nbsp;&nbsp;&nbsp;&nbsp; (for <b>add</b>) Don't actually create the worktree, just show what would happen.<br><br><b>--porcelain</b><br>&nbsp;&nbsp;&nbsp;&nbsp; (for <b>list</b>) Output working tree information in a machine-readable format.<br><br><b>--expire <I>time</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp; (for <b>prune</b>) Prune working trees whose associated Git directory is older than the specified time.<br><br>


title: DESCRIPTION
content:
<i>git worktree</i> allows creating and managing additional linked working trees for a single Git repository. This means you can have multiple directories, each containing a checkout of a different branch or commit from the same underlying repository. It's incredibly useful for developers who need to work on multiple features, branches, or experiments concurrently without constantly switching branches in a single working directory, stashing changes, or cloning the repository multiple times. It facilitates rapid context switching and parallel development, making it easier to manage complex workflows and quickly test different codebases.


title: CAVEATS
content:
A worktree cannot be a submodule, nor can it be nested inside another worktree. The original/main worktree cannot be removed using <b>git worktree remove</b>. Removing a worktree with uncommitted changes requires the <b>--force</b> option. Each linked worktree maintains its own <i>HEAD</i> and index, but they all share the same object database with the main repository.


title: HOW IT WORKS
content:
A <b>git worktree</b> maintains a separate <i>HEAD</i>, index, and working tree for each linked worktree, all sharing the same Git object database (typically located in the original repository's <i>.git/objects</i> directory). This shared object database makes linked worktrees very lightweight in terms of disk space, as only the working files and per-worktree metadata are duplicated.


title: TYPICAL USE CASES
content:
<b>git worktree</b> is ideal for:<br>  - Working on a feature branch while simultaneously performing a hotfix on <i>main</i>.<br>  - Testing a branch against different environments or dependencies without altering your primary working directory.<br>  - Running build processes for multiple branches in parallel.<br>  - Reviewing pull requests or patches in an isolated environment without disturbing your current work.


title: HISTORY
content:
<b>git worktree</b> was introduced in Git version 2.5 (June 2015). It was developed to address the common use case of needing to work on multiple branches simultaneously without duplicating the entire repository or constantly stashing/unstashing changes in a single working directory. Before its introduction, users often resorted to multiple clones or complex manual setups to achieve similar parallel development capabilities. Its availability significantly streamlined such workflows by providing a first-class mechanism within Git itself.


title: PARAMETERS
content:
<b>--prefix=&lt;path&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Instead of writing the entire index as a tree object, write a tree object that represents the contents of the given path (and its subdirectories) in the index. The &lt;path&gt; must refer to a directory within the index. The resulting tree object will represent only that subdirectory and its contents.<br><br>


title: DESCRIPTION
content:
<i>git write-tree</i> is a low-level Git "plumbing" command that reads the current content of the Git index and creates a new <I>tree object</I> in the Git object database. A tree object represents a directory and its contents at a specific point in time, storing references to <I>blob objects</I> (for file contents) and other <I>tree objects</I> (for subdirectories).<br><br>This command captures the snapshot of the staged changes, but it does not create a <I>commit object</I>. It only produces the tree object that a commit object would later reference. Higher-level commands like <i>git commit</i> internally use <i>git write-tree</i> to construct the tree component of a new commit.<br><br>For <i>git write-tree</i> to succeed, all necessary blob objects for the files and tree objects for the subdirectories (as represented in the index) must already exist in the object database. This is typically ensured by commands like <i>git add</i>, which writes the file contents as blobs to the database when staging.


title: CAVEATS
content:
This command operates strictly on the Git index, not the working directory. Any changes in the working directory that have not been staged (added to the index) will not be included in the generated tree object.<br><br>All necessary blob and subtree objects must already exist in the Git object database for <i>git write-tree</i> to succeed. If the index refers to objects that haven't been written (e.g., a file was added to the index but its content blob wasn't stored), the command will fail. (This is generally handled by <i>git add</i>).<br><br>It's a low-level command, not intended for direct daily use by end-users.


title: PLUMBING COMMAND
content:
<i>git write-tree</i> is classified as a 'plumbing' command, meaning it's a low-level building block that operates directly on Git's internal data structures (like the index and object database). Most users interact with 'porcelain' commands like <i>git commit</i>, which use plumbing commands internally.


title: OUTPUT
content:
The command outputs the SHA-1 (or other configured hash algorithm, like SHA-256) hash of the newly created tree object to standard output upon successful completion. This hash is then typically used by other commands, such as <i>git commit</i>, to link the tree object to a commit.


title: HISTORY
content:
<i>git write-tree</i> has been a fundamental component of Git since its early development. It serves as the core mechanism for capturing and storing the directory snapshots that form the basis of Git's version control. Its existence highlights Git's design philosophy of building powerful high-level commands upon a set of robust low-level 'plumbing' tools.


title: SYNOPSIS
content:
<b>github-label-sync</b> [<i>options</i>] <b>--config</b> <<i>config_file</i>> <b>--access-token</b> <<i>token</i>> [<b>--repository</b> <<i>owner</i>>/<<i>repo</i>>...]


title: PARAMETERS
content:
<b><b>-c</b>, <b>--config</b> <<i>file</i>></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the path to the YAML or JSON configuration file that defines the desired state of labels.<br><br><b><b>-a</b>, <b>--access-token</b> <<i>token</i>>, <b>--token</b> <<i>token</i>></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Provides the GitHub Personal Access Token required for authentication with the GitHub API. This token must have sufficient permissions (e.g., <i>repo</i> scope).<br><br><b><b>-r</b>, <b>--repository</b> <<i>owner</i>>/<<i>repo</i>></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Designates one or more specific GitHub repositories to synchronize. This option can be repeated. If omitted, <i>github-label-sync</i> will use repositories defined within the configuration file.<br><br><b><b>-d</b>, <b>--dry-run</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Executes a trial run, showing exactly what changes would be made without actually modifying any labels on GitHub. This is highly recommended for previewing.<br><br><b><b>-A</b>, <b>--allow-added</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prevents <i>github-label-sync</i> from deleting any labels that exist in the target repository but are not present in the configuration file. Labels are only added or updated.<br><br><b><b>-D</b>, <b>--disable-deletion</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;An alias for <b>--allow-added</b>. Prevents the deletion of labels not defined in the configuration file.<br><br><b><b>-q</b>, <b>--quiet</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Suppresses all standard output, including progress messages, showing only errors if they occur.<br><br><b><b>-v</b>, <b>--version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays the current version number of the <i>github-label-sync</i> utility and exits.<br><br><b><b>-h</b>, <b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Outputs a detailed usage message, including a list of available options and their descriptions, then exits.<br><br>


title: DESCRIPTION
content:
<i>github-label-sync</i> is a powerful command-line utility designed to automate the management and synchronization of labels across one or more GitHub repositories. It reads a desired label configuration from a local YAML or JSON file and applies these definitions to specified repositories. The tool can intelligently create new labels, update existing ones (e.g., change color or description), and optionally delete labels that are present in the repository but not defined in the configuration file. This automation is crucial for maintaining consistent labeling conventions, which in turn improves issue tracking, project management, and reporting workflows across multiple projects or organizational teams. It features a robust dry-run mode to preview all planned changes before they are actually applied, providing a safe way to manage your labels. Authentication is handled securely via a GitHub Personal Access Token.


title: CAVEATS
content:
Using <i>github-label-sync</i> requires a GitHub Personal Access Token with appropriate permissions (at least the <i>repo</i> scope). Be cautious when running without the <b>--dry-run</b> option and without <b>--allow-added</b> (or <b>--disable-deletion</b>), as this can lead to unintended deletion of existing labels not defined in your configuration file. This utility is specifically designed for GitHub and does not support other Git hosting platforms like GitLab or Bitbucket. Always ensure your configuration file is correctly formatted to avoid errors.


title: CONFIGURATION FILE FORMAT
content:
The configuration file for <i>github-label-sync</i> must be in YAML or JSON format and contain an array of label objects. Each label object typically includes <b>name</b>, <b>color</b>, and an optional <b>description</b>.<br><br><i>Example (YAML):</i><br><b>- name:</b> bug<br><b>  color:</b> "d73a4a"<br><b>  description:</b> "Something isn't working"<br><b>- name:</b> enhancement<br><b>  color:</b> "a2eeef"<br><b>  description:</b> "New feature or request"<br>The configuration file can also optionally specify an array of <b>repositories</b> to apply the labels to, removing the need for the <b>--repository</b> command-line argument.


title: AUTHENTICATION
content:
Access to GitHub is authenticated using a Personal Access Token (PAT) which must be passed via the <b>--access-token</b> (or <b>--token</b>) option. It is strongly recommended to use environment variables (e.g., <code>GITHUB_ACCESS_TOKEN</code>) or a secure secrets management system to avoid exposing the token directly in command-line history or scripts. The PAT needs appropriate scopes, typically the <i>repo</i> scope, to allow label creation, modification, and deletion in private and public repositories.


title: HISTORY
content:
<i>github-label-sync</i> was originally developed by the Financial Times to streamline label management across their numerous GitHub repositories, addressing a common need for consistent project metadata. It was first published as an npm package on April 20, 2016, making it accessible to a wider developer community. Since its initial release, the utility has undergone continuous maintenance and updates, reflecting community contributions and evolving GitHub API features, ensuring its continued relevance for automated label synchronization.


title: PARAMETERS
content:
<b><b>--all</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows all branches, tags, and remote-tracking branches in the history view.<br><br><b><b>--branches</b>[=<i>&lt;pattern&gt;</i>]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Includes commits reachable from all local branches, optionally filtered by a shell-style <i>&lt;pattern&gt;</i>.<br><br><b><b>--tags</b>[=<i>&lt;pattern&gt;</i>]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Includes commits reachable from all tags, optionally filtered by a shell-style <i>&lt;pattern&gt;</i>.<br><br><b><b>--remotes</b>[=<i>&lt;pattern&gt;</i>]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Includes commits reachable from all remote-tracking branches, optionally filtered by a shell-style <i>&lt;pattern&gt;</i>.<br><br><b><b>--since</b>=<i>&lt;date&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows commits more recent than a specific <i>&lt;date&gt;</i> (e.g., '2 weeks ago', '2023-01-01').<br><br><b><b>--until</b>=<i>&lt;date&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows commits older than a specific <i>&lt;date&gt;</i>.<br><br><b><b>--max-count</b>=<i>&lt;n&gt;</i><br><b>-</b><i>&lt;n&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Limits the number of commits to display to the first <i>&lt;n&gt;</i> found.<br><br><b><b>--author</b>=<i>&lt;pattern&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows commits where the author's name or email matches the specified regular expression <i>&lt;pattern&gt;</i>.<br><br><b><b>--committer</b>=<i>&lt;pattern&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows commits where the committer's name or email matches the specified regular expression <i>&lt;pattern&gt;</i>.<br><br><b><b>--grep</b>=<i>&lt;pattern&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows commits with a log message that matches the specified regular expression <i>&lt;pattern&gt;</i>.<br><br><b><i>&lt;revision-range&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies a range of revisions to display (e.g., <i>master..feature</i> to show commits on 'feature' but not 'master').<br><br><b>-- <i>&lt;path&gt;</i>...</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Limits the commits displayed to those that affect the specified <i>&lt;path&gt;</i>(s). Use '--' to separate paths from revisions.<br><br><b><b>--select-commit</b> <i>&lt;sha1&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Starts <i>gitk</i> with the commit identified by <i>&lt;sha1&gt;</i> pre-selected in the view.<br><br>


title: DESCRIPTION
content:
<i>gitk</i> is a Tcl/Tk based graphical user interface for browsing the history of a Git repository. It provides a visual representation of the commit graph, allowing users to easily inspect individual commits, view the diff of changes introduced by a commit, and understand the branching and merging history. It's an invaluable tool for quickly visualizing the state and evolution of a Git repository. Users can filter commits by various criteria such as author, committer, commit message, and date, making it efficient to locate specific changes or understand contributions over time. Being part of the official Git distribution, it offers a reliable and readily available graphical view of repository history.


title: CAVEATS
content:
Requires a Tcl/Tk installation to run, which might not be pre-installed on all systems. While functional and reliable, its user interface and feature set may appear less modern or extensive compared to newer, dedicated graphical Git clients. Performance can be slower on extremely large repositories with a vast number of commits.


title: USER INTERFACE OVERVIEW
content:
The <i>gitk</i> window typically consists of several key panes:<br>A history graph pane (usually top-left) displays commits and their relationships, showing branches, merges, and tags.<br>A commit details pane (top-right) provides comprehensive information about the currently selected commit, including its hash, author, committer, date, and full commit message.<br>A diff pane (bottom) shows the changes introduced by the selected commit, allowing users to inspect modified files and their line-by-line differences.<br>Additionally, it features a search bar and various filter options to narrow down the displayed history based on different criteria.


title: CONFIGURATION
content:
<i>gitk</i>'s appearance and default behavior are highly customizable through Git's configuration system. Users can modify settings in the global <i>~/.gitconfig</i> file or the repository-specific <i>.git/config</i> file. This includes customization of colors for different elements (e.g., branches, tags), fonts, the visibility of columns in the history list, and default sorting orders, allowing for a personalized viewing experience.


title: HISTORY
content:
<i>gitk</i> has been an integral part of the official Git distribution since its early days, providing a robust, native graphical history browser. It's written in Tcl/Tk, a cross-platform scripting language with a GUI toolkit, which contributed to its early accessibility and widespread adoption as a default Git GUI tool for visualizing repository history.


title: PARAMETERS
content:
<b>reconfigure</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Reapplies and reloads the GitLab configuration based on <i>/etc/gitlab/gitlab.rb</i>.<br><br><b>start</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Starts all GitLab services.<br><br><b>stop</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Stops all GitLab services.<br><br><b>restart</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Restarts all GitLab services.<br><br><b>status</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays the current operational status of all GitLab services.<br><br><b>tail <I>service</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Follows the real-time logs of a specific GitLab service (e.g., <i>nginx</i>, <i>unicorn</i>, <i>sidekiq</i>).<br><br><b>console</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Opens an interactive GitLab Rails console for advanced administration and debugging.<br><br><b>rake <I>task</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Executes a GitLab Rake task (e.g., <i>gitlab-ctl rake gitlab:check</i> for system diagnostics).<br><br><b>hup</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sends a HUP signal to relevant services, often used for non-disruptive configuration reloads.<br><br><b>service-list</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Lists all services managed by the GitLab Omnibus package.<br><br><b>clean-logs</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Cleans up old application and service logs to free disk space.<br><br><b>backup-etc</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Creates a tarball backup of the <i>/etc/gitlab</i> directory, including <i>gitlab.rb</i> and SSL certificates.<br><br>


title: DESCRIPTION
content:
The <b>gitlab-ctl</b> command is the primary administrative utility for managing a GitLab Omnibus installation. It provides a comprehensive set of tools to control the lifecycle and configuration of various GitLab components, including Nginx, PostgreSQL, Redis, Unicorn, Sidekiq, and Prometheus.<br><br>It significantly simplifies the administration of a complex GitLab setup by offering commands to start, stop, restart, reconfigure, and check the health of these bundled services. This command is indispensable for performing routine maintenance, applying configuration changes defined in <i>/etc/gitlab/gitlab.rb</i>, and troubleshooting operational issues within the GitLab environment.


title: CAVEATS
content:
Most <b>gitlab-ctl</b> operations require root privileges (i.e., running with <i>sudo</i>).<br>This utility is designed specifically for GitLab Omnibus installations and is not applicable to source installations or containerized deployments (like Docker or Kubernetes).<br>Using the <i>console</i> or <i>rake</i> subcommands without proper knowledge can lead to data corruption or service outages. Always consult GitLab documentation before executing complex tasks.


title: CONFIGURATION FILE
content:
All primary configuration for the GitLab Omnibus installation is managed via the <i>/etc/gitlab/gitlab.rb</i> file. After making any changes to this file, you must run <b>gitlab-ctl reconfigure</b> for the changes to take effect.


title: LOG LOCATIONS
content:
GitLab service logs are typically stored under <i>/var/log/gitlab/</i>. Each service has its own subdirectory within this path (e.g., <i>/var/log/gitlab/nginx/</i>, <i>/var/log/gitlab/unicorn/</i>). The <b>gitlab-ctl tail</b> command is a convenient way to view these logs in real-time.


title: TROUBLESHOOTING STEPS
content:
For initial troubleshooting, start with <b>gitlab-ctl status</b> to check which services are running or failing.<br>Reviewing logs with <b>gitlab-ctl tail</b> is crucial for identifying error messages.<br>If configuration issues are suspected, running <b>gitlab-ctl reconfigure</b> can often resolve inconsistencies, and <b>gitlab-ctl check-config</b> (if available in your GitLab version) can validate the <i>gitlab.rb</i> syntax.


title: HISTORY
content:
The <b>gitlab-ctl</b> command emerged as a core component of the GitLab Omnibus package, which was first introduced to drastically simplify the installation and management of GitLab. Prior to Omnibus, deploying GitLab involved manually configuring numerous interdependent services (Ruby on Rails application, Nginx, PostgreSQL, Redis, Sidekiq, etc.), a process that was notoriously complex and prone to errors.<br><br>By bundling all necessary dependencies and providing <b>gitlab-ctl</b> as a unified command-line interface, GitLab greatly streamlined deployments and ongoing maintenance for system administrators. It leverages an embedded Chef client for robust configuration management, allowing administrators to define their GitLab instance's settings in a single <i>gitlab.rb</i> file and apply them reliably.


title: PARAMETERS
content:
<b>register</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Registers a new runner with a GitLab instance.</i><br><br><b>run</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Starts the runner process to pick up and execute jobs.</i><br><br><b>exec</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Executes a CI job locally, useful for debugging and testing.</i><br><br><b>list</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Lists all configured GitLab Runners.</i><br><br><b>verify</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Checks the status of registered runners and removes invalid ones.</i><br><br><b>unregister</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Unregisters a runner from GitLab and removes its configuration.</i><br><br><b>install</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Installs the runner as a system service (e.g., systemd on Linux).</i><br><br><b>start</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Starts the runner system service.</i><br><br><b>stop</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Stops the runner system service.</i><br><br><b>status</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Shows the status of the runner system service.</i><br><br><b>--version</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Displays the GitLab Runner version information.</i><br><br><b>help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Shows help for a command or global options.</i><br><br>


title: DESCRIPTION
content:
<b>gitlab-runner</b> is the open-source application that executes jobs in a GitLab CI/CD pipeline.<br>It can be installed on various operating systems and configured to connect to a GitLab instance. Runners pick up jobs from GitLab, execute them based on the <b>.gitlab-ci.yml</b> configuration, and send the results (logs, artifacts) back to GitLab.<br>Runners can be configured with different executors, such as Docker, Kubernetes, Shell, SSH, Parallels, VirtualBox, or custom executors, allowing flexibility in how jobs are run and providing isolation.<br>It acts as the backbone for automating software development workflows, enabling continuous integration, continuous delivery, and continuous deployment directly within the GitLab platform.


title: CAVEATS
content:
<b>gitlab-runner</b> requires a GitLab instance (SaaS or self-managed) to function and receive jobs.<br>Proper configuration of executors (e.g., Docker, Kubernetes) is crucial for security, isolation, and performance.<br>Resource management (CPU, memory, disk) is vital, especially for shared runners executing multiple jobs concurrently.<br>Network connectivity between the runner machine and the GitLab instance, as well as any external services required by jobs, must be ensured.


title: CONFIGURATION FILE
content:
The primary configuration for <b>gitlab-runner</b> is managed through a <b>config.toml</b> file, typically located at <b>/etc/gitlab-runner/config.toml</b> on Linux.<br>This file defines registered runners, their executors, concurrent job limits, and other operational settings crucial for runner behavior.


title: EXECUTORS
content:
<b>gitlab-runner</b> supports various executors that determine how jobs are run:<br><b>Docker</b>: Runs jobs inside Docker containers (most common, provides good isolation).<br><b>Shell</b>: Runs jobs directly on the runner machine's shell environment (simple, but less isolated).<br><b>Kubernetes</b>: Runs jobs as pods within a Kubernetes cluster (scalable, cloud-native).<br>Other executors include SSH, Parallels, VirtualBox, and custom solutions, each offering different levels of isolation, performance, and setup complexity.


title: HISTORY
content:
<b>gitlab-runner</b> evolved alongside GitLab CI/CD, which was initially a separate project (GitLab CI) before being fully integrated into GitLab. As GitLab matured into a complete DevOps platform, <b>gitlab-runner</b> became its dedicated and highly configurable job execution agent, supporting various environments and scales.<br>Its development consistently focuses on flexibility, security, and performance for CI/CD workloads, adapting to modern containerization and orchestration technologies to meet the demands of continuous delivery.


title: SYNOPSIS
content:
<I>gitleaks</I> <I>command</I> [options]<br><I>gitleaks</I> <I>detect</I> [flags]<br><I>gitleaks</I> <I>protect</I> [flags]<br><I>gitleaks</I> <I>version</I><br><br>The primary command is <b>detect</b> for scanning a repository and <b>protect</b> for integrating into pre-commit hooks.


title: PARAMETERS
content:
<b>--config <I>path</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Path to a custom Gitleaks config file (e.g., <I>.gitleaks.toml</I>).<br><br><b>--repo-path <I>path</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Path to the repository to scan. Defaults to the current directory. (Alias: <I>--source</I>)<br><br><b>--verbose</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enable verbose output.<br><br><b>--log-level <I>level</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set the log level (debug, info, warn, error, fatal).<br><br><b>--exit-code <I>int</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Exit code if a leak is found (default is 1).<br><br><b>--report-path <I>path</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Path to write the report file.<br><br><b>--report-format <I>format</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Format of the report file (json, sarif, csv, text, noop).<br><br><b>--redact</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Redact secrets from the log and report output.<br><br><b>--branch <I>name</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Only scan a specific branch.<br><br><b>--staged</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Scan only staged files (used with <I>detect</I> and <I>protect</I>).<br><br><b>--uncommitted</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Scan only uncommitted changes.<br><br><b>--threads <I>int</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Number of threads to use for scanning (default depends on CPU cores).<br><br><b>--commit <I>hash</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Scan a specific commit.<br><br><b>--commit-from <I>hash</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Scan from a specific commit hash.<br><br><b>--commit-to <I>hash</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Scan to a specific commit hash.<br><br><b>--exclude-forks</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Exclude scanning forked repositories.<br><br><b>--max-commit-delta <I>int</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Maximum number of commits to scan back (0 for unlimited).<br><br><b>--install-hook</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Install the Gitleaks pre-commit hook (used with <I>protect</I>).<br><br><b>--remove-hook</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Remove the Gitleaks pre-commit hook (used with <I>protect</I>).<br><br>


title: DESCRIPTION
content:
<I>gitleaks</I> is an open-source command-line tool designed to identify and prevent the accidental exposure of sensitive information, such as passwords, API keys, tokens, and other credentials, within Git repositories. It achieves this by scanning commit history, branches, and tags for patterns that indicate the presence of secrets. <br><br>The tool uses a comprehensive set of predefined rules (regex patterns and heuristics) to detect various types of secrets. Users can also define custom rules to tailor detection to their specific needs. <br><br><I>gitleaks</I> is widely used in DevSecOps practices. It can be integrated into Continuous Integration/Continuous Deployment (CI/CD) pipelines to enforce security policies and catch secrets before they are pushed to remote repositories. It can also be run as a pre-commit hook on developer machines to prevent secrets from ever entering the Git history. Its primary goal is to help organizations maintain a strong security posture by preventing sensitive data from being publicly exposed.


title: CAVEATS
content:
<b>False Positives:</b> While <I>gitleaks</I> uses sophisticated rules, it can still produce false positives, requiring manual review of findings.<br><b>Performance:</b> Scanning very large repositories with extensive commit history can be time-consuming and resource-intensive.<br><b>Rule Updates:</b> The effectiveness of <I>gitleaks</I> depends on its detection rules being up-to-date. Regularly updating the tool is crucial.<br><b>Not a complete solution:</b> It's a critical component of security, but not a substitute for proper secret management solutions (e.g., vaults) and secure coding practices.<br><b>History Rewriting:</b> <I>gitleaks</I> identifies secrets, but doesn't automatically remove them from history. Removing secrets from Git history requires tools like <I>git filter-repo</I> or <I>BFG Repo-Cleaner</I>, which should be used with extreme caution.


title: CI/CD INTEGRATION
content:
<I>gitleaks</I> is commonly integrated into CI/CD pipelines (e.g., GitHub Actions, GitLab CI, Jenkins) to automatically scan code pushes or pull requests, failing builds if secrets are detected.


title: PRE-COMMIT HOOKS
content:
Developers can install <I>gitleaks</I> as a Git pre-commit hook to scan changes locally before they are committed, preventing secrets from entering the repository history in the first place.


title: CUSTOM RULES
content:
Beyond its extensive default rules, <I>gitleaks</I> allows users to define custom regular expressions and configurations in a TOML file (<I>.gitleaks.toml</I>) to detect organization-specific patterns or sensitive data.


title: DOCKER SUPPORT
content:
<I>gitleaks</I> can be easily run as a Docker container, providing a consistent and isolated environment for scanning without requiring local installation of dependencies.


title: HISTORY
content:
<I>gitleaks</I> was originally created by Zach Khan and released as an open-source project. It quickly gained traction within the cybersecurity and DevOps communities due to its effectiveness and ease of integration. It has evolved over time with community contributions, enhancing its rule set, performance, and features, becoming a staple tool for proactive secret detection in Git workflows.


title: PARAMETERS
content:
<b><b>-c</b> <I>CONFIG_KEY=CONFIG_VALUE</I>, <b>--config</b> <I>CONFIG_KEY=CONFIG_VALUE</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets a specific configuration value directly on the command line. This overrides values from configuration files and can be used multiple times.<br><br><b><b>--config</b> <I>FILE</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Loads configuration settings from the specified file. This file typically contains rule settings, ignore lists, and more.<br><br><b><b>--extra-path</b> <I>PATH</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies a directory from which to load extra user-defined rules. This allows for custom linting logic to be applied.<br><br><b><b>--msg-filename</b> <I>FILE</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Lints the commit message contained in the specified file. Useful for testing or linting messages generated by other processes.<br><br><b><b>--msg-filename-stdin</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Reads the commit message from standard input, treating it as if it came from a file. Useful for piping file contents.<br><br><b><b>--msg-stdin</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Reads the commit message directly from standard input. This is typically used when piping a message string.<br><br><b><b>--commit</b> <I>COMMIT_HASH</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Lints the commit message of a specific commit identified by its hash.<br><br><b><b>--commits</b> <I>COMMIT_RANGE</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Lints commit messages within the specified Git commit range (e.g., `HEAD~3..HEAD`). Accepts arguments in a format similar to `git rev-list`.<br><br><b><b>--staged</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Lints the commit message that is currently staged for commit (typically found in `.git/COMMIT_EDITMSG`). This option is frequently used when <i>gitlint</i> is invoked from a Git `commit-msg` hook.<br><br><b><b>--ignore</b> <I>RULE_ID_OR_NAME</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Ignores one or more specific rules by their ID (e.g., `T1`) or name (e.g., `body-max-line-length`). This option can be specified multiple times to ignore several rules.<br><br><b><b>--strict</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Causes <i>gitlint</i> to exit with a non-zero status code if any violations (errors or warnings) are found. By default, it exits with a non-zero code only for errors.<br><br><b><b>--silent</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Suppresses all output if no violations are found. Output is only displayed when there are issues with the commit message.<br><br><b><b>--json</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Outputs the linting results in JSON format, which is ideal for programmatic consumption and integration with other tools or scripts.<br><br><b><b>--verbose</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Provides more detailed output, showing additional information about the rules being checked and their status during the linting process.<br><br><b><b>--debug</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints extensive debugging information, useful for troubleshooting issues with <i>gitlint</i> itself or understanding its internal workings.<br><br><b><b>--version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays the <i>gitlint</i> program's version number and then exits.<br><br><b><b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays the help message for <i>gitlint</i>, including a list of options and usage examples, and then exits.<br><br>


title: DESCRIPTION
content:
<i>gitlint</i> is a powerful and highly configurable command-line tool designed to lint Git commit messages. It helps developers ensure their commit messages adhere to specific standards and conventions, promoting consistency, readability, and maintainability across a project's commit history. <br><br>It comes with a set of default rules (e.g., subject line length, capitalization, imperative mood, body line length) that can be enabled, disabled, or configured. <i>gitlint</i> can lint the last commit, a range of commits, or a commit message from a file or stdin. It's often integrated into Git hooks, such as `commit-msg` or `pre-commit`, to enforce message quality automatically before a commit is created.


title: CAVEATS
content:
<i>gitlint</i> is a Python-based tool, thus requiring a Python interpreter to be installed on the system. It also depends on Git being installed and accessible in the system's PATH. While highly configurable, setting up complex custom rules or advanced integrations might require familiarity with Python programming and Git hook mechanisms. It solely focuses on commit message formatting and does not analyze code quality.


title: INTEGRATION WITH GIT HOOKS
content:
<i>gitlint</i> is most commonly integrated into Git's client-side hooks, particularly the `commit-msg` hook. By placing <i>gitlint</i> within this hook, it automatically lints commit messages before they are finalized, preventing non-compliant messages from ever being committed. It can also be utilized in `pre-commit` hooks for more general pre-commit checks or as part of CI/CD pipelines to validate commit messages before merging.


title: CONFIGURATION FILES
content:
Beyond command-line options, <i>gitlint</i> offers persistent configuration via dedicated files. It primarily looks for a `.gitlint` file (using an INI-like format) or a `pyproject.toml` file in the repository's root or user's home directory. This allows project-specific rules, ignored rules, and other settings to be easily defined, shared, and version-controlled within a repository, ensuring consistent linting behavior across team members.


title: HISTORY
content:
<i>gitlint</i> emerged as an open-source solution to standardize Git commit messages within development teams, aiming to improve the clarity and consistency of project histories. Its development focused on providing a flexible and easy-to-use tool for enforcing best practices in commit message hygiene. Since its inception, it has gained traction due to its straightforward configuration, extensibility, and effectiveness in maintaining clean commit logs.


title: PARAMETERS
content:
<b><B>init</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Initializes</I> gitmoji support in a <I>Git</I> repository, typically setting up a <I>prepare-commit-msg</I> hook.<br><br><b><B>config</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Configures</I> gitmoji behavior, such as enabling/disabling automatic emoji appending or specifying custom emoji lists.<br><br><b><B>add</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Adds</I> a custom gitmoji to the local configuration.<br><br><b><B>remove</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Removes</I> a custom gitmoji from the local configuration.<br><br><b><B>commit</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Initiates</I> an interactive commit process, prompting for an emoji and message.<br><br><b><B>search</B> <I>&lt;term&gt;</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Searches</I> for gitmojis matching the provided <I>term</I>.<br><br><b><B>list</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Displays</I> a comprehensive list of all available gitmojis with their codes and descriptions.<br><br><b><B>update</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Updates</I> the local gitmoji list to the latest version from the source.<br><br><b><B>--version</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Displays</I> the current version of the gitmoji CLI.<br><br><b><B>--help</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Shows</I> the help message for the command or a specific subcommand.<br><br>


title: DESCRIPTION
content:
<b>gitmoji</b> is a command-line interface tool designed to streamline the process of adding emojis to <I>Git</I> commit messages, adhering to the "gitmoji" specification. This specification suggests using specific emojis to categorize and visually enhance commit messages, making the commit history more readable and understandable at a glance.<br><br>The <B>gitmoji</B> CLI typically offers an interactive mode that prompts the user to select an emoji from a predefined list and then guides them through adding the commit message (subject and body). It aims to standardize commit conventions across teams and projects, improving collaboration and code review processes. Beyond interactive committing, <B>gitmoji</B> often provides functionalities to list available emojis, search for specific ones, initialize emoji support in a <I>Git</I> repository, and update the emoji list. It integrates seamlessly with <I>Git</I> workflows, often leveraging <I>Git</I> hooks (like <I>prepare-commit-msg</I>) to automate the emoji selection and message formatting, ensuring consistency without manual intervention.


title: CAVEATS
content:
<B>gitmoji</B> is an external tool and not part of the standard <I>Git</I> distribution. Its availability depends on separate installation.<br><br>The effectiveness and adoption of gitmoji conventions depend on team agreement and consistency.<br><br>The list of emojis and their descriptions might vary slightly between different <B>gitmoji</B> CLI implementations or versions.<br><br>Using emojis in commit messages might not be universally supported by all <I>Git</I> clients or web interfaces, though most modern ones handle them well.


title: CUSTOMIZATION
content:
Users can often customize the behavior of <B>gitmoji</B> tools, such as disabling automatic emoji prepending, adding custom emojis, or modifying the default commit message format through configuration files, typically located in the user's home directory or within the <I>Git</I> repository's <I>.git/config</I> or a project-specific configuration file.


title: INTEGRATION WITH GIT HOOKS
content:
The most common way <B>gitmoji</B> ensures consistent emoji usage is by setting up a <I>prepare-commit-msg</I> <I>Git</I> hook. This hook is executed after the commit message is created but before the editor is launched, allowing <B>gitmoji</B> to prompt for an emoji and prepend it to the message, thus automating adherence to the convention.


title: HISTORY
content:
The concept of "gitmoji" for commit messages gained popularity around 2017-2018, primarily championed by the <I>carloscuesta/gitmoji</I> repository, which provides the specification and a comprehensive list of emojis. Following this, various CLI tools emerged to automate the process, with <I>carloscuesta/gitmoji-cli</I> being one of the most prominent implementations, developed to make it easier for developers to adopt and maintain the gitmoji convention in their daily <I>Git</I> workflows. Its development has focused on providing an interactive, user-friendly experience to standardize commit practices.


title: SYNOPSIS
content:
<b>gitsome</b><br><b>gitsome</b> [<b>--help</b> | <b>--version</b>]<br><b>gitsome</b> [<i>command</i>] [<i>args...</i>]


title: PARAMETERS
content:
<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;Shows the installed <b>gitsome</b> version and exits.<br><br>


title: DESCRIPTION
content:
<b>gitsome</b> is an interactive Git shell designed to enhance your command-line Git and GitHub workflow. It acts as a wrapper around the standard <b>git</b> command, providing powerful features like comprehensive auto-completion for Git commands and their arguments, intelligent GitHub API integration, and custom utilities. Instead of directly executing Git commands, you launch <b>gitsome</b> to enter an interactive shell where you can type your usual <b>git</b> commands, along with specialized <b>gh</b> commands for GitHub interactions and <b>gs</b> commands for gitsome-specific functions. This environment significantly boosts productivity by reducing typing errors, providing context-aware suggestions, and streamlining interactions with your remote repositories on GitHub, all within a familiar terminal interface. It aims to make your Git and GitHub experience more efficient and enjoyable.


title: CAVEATS
content:
<b>gitsome</b> requires Python 2.7 or 3.x to run. Its GitHub-specific features (<b>gh</b> commands) necessitate authentication with the GitHub API, typically via a personal access token, which can be configured using the <b>gh login</b> command within the shell. While highly functional, the project has seen limited active maintenance since 2020, which might impact future compatibility or feature development.


title: <B>GITHUB API INTEGRATION</B>
content:
Within the <b>gitsome</b> shell, commands prefixed with <b>gh</b> allow direct interaction with the GitHub API. Examples include <b>gh repos</b> to list repositories, <b>gh issues</b> to view issues, or <b>gh login</b> to authenticate with GitHub. This significantly streamlines common GitHub tasks directly from the terminal.


title: <B>CUSTOM GITSOME COMMANDS</B>
content:
Commands prefixed with <b>gs</b> are exclusive to <b>gitsome</b>, providing utilities beyond standard Git or GitHub operations. For instance, <b>gs config</b> allows managing gitsome's configuration, and <b>gs cheat</b> can display Git cheatsheets. These commands enhance the interactive experience by offering quick access to help and settings.


title: <B>CONFIGURATION AND CUSTOMIZATION</B>
content:
<b>gitsome</b>'s behavior can be customized via a configuration file located at <i>~/.gitsome/config</i>. This file allows users to define aliases, modify color schemes, set default behaviors, and manage GitHub credentials, enabling a highly personalized workflow.


title: HISTORY
content:
<b>gitsome</b> was created by Donnie Margolis and first released in 2016. Its development was driven by the desire to provide a more interactive and user-friendly command-line experience for Git, particularly for those frequently interacting with GitHub. It aimed to merge the power of Git's CLI with the convenience of an interactive shell, drawing inspiration from tools like <b>ipython</b>. The project gained recognition for its innovative approach to Git and GitHub integration, offering features that were not natively available in the standard Git command line at the time.


title: PARAMETERS
content:
<b><i>&lt;repository_path&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The path to the Git repository to be analyzed. This is a mandatory argument.<br><br><b><i>&lt;output_directory&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Optional. The directory where the generated HTML reports will be stored. If omitted, defaults to <i>./gitstats</i> in the current working directory.<br><br><b><b>--full</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Generates statistics for the entire history of the repository, rather than just the last year (which is often the default if not specified).<br><br><b><b>--full-history</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Similar to <b>--full</b>, ensures all commits from the repository's beginning are included in the analysis.<br><br><b><b>--authors-top=</b><i>&lt;num&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Limits the author statistics to the top <i>&lt;num&gt;</i> contributors (default: 5).<br><br><b><b>--max-authors=</b><i>&lt;num&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the maximum number of authors to display on graphs (default: 20). If more authors exist, they are grouped as 'Other'.<br><br><b><b>--style=</b><i>&lt;css_file&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies a custom CSS file to use for styling the generated HTML reports, overriding the default stylesheet.<br><br><b><b>--since=</b><i>&lt;date&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Only processes commits made since the specified <i>&lt;date&gt;</i> (e.g., '2023-01-01' or '2 weeks ago').<br><br><b><b>--until=</b><i>&lt;date&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Only processes commits made until the specified <i>&lt;date&gt;</i> (e.g., 'yesterday' or '2024-01-01').<br><br><b><b>--pretty-names</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Attempts to use more readable names for authors (e.g., 'John Doe' instead of 'john.doe@example.com').<br><br><b><b>--exclude=</b><i>&lt;list&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;A comma-separated list of file paths or directories to exclude from the analysis.<br><br><b><b>--list-languages</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Lists all supported programming languages that <i>gitstats</i> can analyze and then exits.<br><br><b><b>--version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays the program's version number and exits.<br><br><b><b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays the help message and exits.<br><br>


title: DESCRIPTION
content:
<i>gitstats</i> is a Python-based command-line tool designed to generate detailed statistics from a Git repository.<br><br>It scans the repository's commit history to gather various metrics, such as commit activity (daily, hourly, weekly, monthly), author contributions, file types, lines of code added/removed, and commit message details. The collected data is then processed and rendered into a set of interactive HTML files, complete with graphs generated by <i>Gnuplot</i>.<br><br>This allows developers and project managers to gain deep insights into the project's development trends, team activity, code evolution, and overall project health. The generated reports are self-contained and can be easily viewed in any web browser, making them convenient for sharing and analysis.


title: CAVEATS
content:
Analyzing very large or old Git repositories can be resource-intensive and take a significant amount of time.<br><br>Accuracy of statistics depends on the consistency of author names and emails within the Git history; inconsistent data might lead to authors being counted separately even if they are the same person (though <b>--avoid-email-clones</b> helps mitigate this).


title: DEPENDENCIES
content:
<i>gitstats</i> requires <i>Python</i> (version 2.7+ or 3.x), the <i>Git</i> command-line tool, and <i>Gnuplot</i> to generate the visual graphs within the HTML reports. These must be installed and accessible in the system's PATH.


title: OUTPUT STRUCTURE
content:
The command generates a directory containing an <i>index.html</i> file along with subdirectories for images (graphs) and CSS. The <i>index.html</i> serves as the main entry point to navigate through various statistical reports like commit activity, author activity, file statistics, and more.


title: HISTORY
content:
<i>gitstats</i> was initially developed by Ahti Heinla and released around 2008. It has since been maintained and improved by various contributors, primarily hosted on GitHub. Its purpose has consistently been to provide a visual, accessible, and comprehensive overview of Git repository activity, leveraging <i>Python</i> for data processing and <i>Gnuplot</i> for graphical representation.


title: PARAMETERS
content:
<b><b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays help information about the command and its usage.<br><br><b><b>--version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows the version number of the <i>gitui</i> application.<br><br>


title: DESCRIPTION
content:
<i>gitui</i> is an open-source, terminal user interface (TUI) for Git, written in Rust. It aims to provide a fast and intuitive way to interact with Git repositories directly from the command line, without needing to switch to a graphical user interface. Unlike traditional command-line Git, <i>gitui</i> offers a full-screen, interactive display that shows the repository status, file changes, commit history, and more in real-time.<br><br>Users can perform common Git operations such as staging and unstaging files, committing changes, pushing and pulling from remotes, managing branches, and performing rebases, all through intuitive keyboard shortcuts. Its performance, particularly on large repositories, is a significant advantage attributed to its Rust foundation. <i>gitui</i> is ideal for developers who prefer a keyboard-driven workflow and seek to streamline their Git interactions within a unified terminal environment.


title: CAVEATS
content:
<i>gitui</i> relies on a functioning Git installation and configuration on your system. Its keyboard-driven interface, while efficient, may present a learning curve for users accustomed to mouse-based graphical tools. While powerful for daily Git operations, advanced or very specific Git commands might still require falling back to the standard <i>git</i> command-line interface. Configuration is managed through a <i>RON</i> (Rusty Object Notation) file, which might be unfamiliar to some users.


title: INTERACTIVE NATURE
content:
<i>gitui</i> functions as a dynamic, full-screen terminal user interface. Upon launch, it provides real-time updates of your Git repository's status, allowing seamless navigation between different views like the status screen, diff view, commit log, and branch manager. The primary method of interaction is through keyboard shortcuts within the <i>gitui</i> window itself, offering a continuous workflow without needing to re-enter commands.


title: CONFIGURATION
content:
The behavior and appearance of <i>gitui</i> are highly customizable through a configuration file, typically named <b>config.ron</b>, located in your user's configuration directory (e.g., <b>~/.config/gitui/config.ron</b> on Linux). This file allows users to define custom keybindings, color themes, UI layout preferences, and various other default behaviors, enabling a personalized and efficient Git experience.


title: HISTORY
content:
<i>gitui</i> was created by Marcel Köppen (<i>extrawurst</i>) and first gained significant traction around late 2020 / early 2021. It quickly rose in popularity due to its exceptional performance, particularly in large repositories, a benefit of being written in Rust, and its modern, user-friendly terminal interface.


title: PARAMETERS
content:
<b>&lt;repository_path&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;The mandatory path to the Git repository that <i>gitwatch</i> will monitor for changes.<br><br><b>[&lt;interval_seconds&gt;]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;An optional numerical value specifying the time interval, in seconds, between checks for changes. If omitted, a common default such as 5 or 10 seconds is used.<br><br>


title: DESCRIPTION
content:
<i>gitwatch</i> is a utility designed to continuously monitor a Git repository for file system changes and automatically commit them. It's typically implemented as a simple shell script that polls the specified repository at a regular interval. Its primary use case is during active development, where it ensures that local changes are frequently saved, preventing accidental data loss and creating a granular history. It streamlines the save-and-commit workflow, allowing developers to focus on coding without manual <i>git add</i> and <i>git commit</i> commands. While convenient, it generally uses generic commit messages, making the commit history less descriptive than manually crafted ones.


title: CAVEATS
content:
<b>Frequent Commits:</b> <i>gitwatch</i> typically generates many small, frequent commits, which can clutter the <i>git log</i> with numerous entries.<br><b>Generic Messages:</b> Commits are usually made with a default, generic message (e.g., "Automatic commit by gitwatch"), lacking detailed context that a human-crafted message would provide.<br><b>Resource Usage:</b> Running continuously, especially with a short interval, consumes system resources (CPU, disk I/O, battery on laptops).<br><b>No Intelligent Logic:</b> It only detects file changes and commits; it does not handle branching, merging, or complex Git operations, nor does it discern between significant and trivial changes.


title: TYPICAL USAGE SCENARIO
content:
<i>gitwatch</i> is commonly employed in local development environments where a developer wants to automatically save progress without manually performing <i>git add</i> and <i>git commit</i> for every small change. It helps maintain a clean working directory and provides a detailed history of changes as they occur, allowing developers to focus on coding.


title: COMMIT MESSAGE CUSTOMIZATION
content:
While many basic <i>gitwatch</i> scripts use a generic commit message, more advanced or custom implementations might allow for some level of commit message customization, or integrate with other tools to provide more context to the automatic commits.


title: HISTORY
content:
<i>gitwatch</i> is not an official part of the core Git distribution but rather a popular community-contributed utility. Its development typically stems from individual developers seeking to automate their local commit workflow. It emerged as a practical solution for ensuring frequent saves and creating a continuous, granular commit history, particularly useful for work-in-progress branches or as a simple, automated backup mechanism without requiring explicit manual commits.


title: SYNOPSIS
content:
<b>gitweb.cgi</b> (executed by a web server, e.g., Apache or Nginx)<br>Behavior is determined by configuration variables set in <code>gitweb.conf</code> or environment variables.


title: PARAMETERS
content:
<b><b>$projectroot</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the base directory where Git repositories are located. <i>gitweb</i> searches for repositories in this directory and its subdirectories.<br><br><b><b>$baseurl</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the base URL for the <i>gitweb</i> instance, used for generating absolute URLs in the web interface.<br><br><b><b>$export_ok</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Boolean variable. If true, only repositories with a file named <code>git-daemon-export-ok</code> (or equivalent for http.gitweb.enabled) are displayed. Useful for controlling visibility.<br><br><b><b>$allow_override</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Boolean variable. If true, allows project-specific configuration overrides (e.g., in <code>.git/gitweb/project.conf</code>) to customize individual repository views.<br><br><b><b>$site_name</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;A string that defines the title displayed in the <i>gitweb</i> header, typically the name of the Git hosting site.<br><br><b><b>$home_text</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the path to a text file whose content will be displayed on the <i>gitweb</i> project list homepage. Supports basic HTML.<br><br><b><b>$features{'feature_name'}</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;A hash used to enable or disable various <i>gitweb</i> features, such as <code>blame</code> (blame view), <code>snapshot</code> (tarball downloads), <code>search</code> (commit message search), <code>gravatar</code> (user avatars), etc. Each feature can be set to 1 (enable) or 0 (disable).<br><br><b><b>$logo</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Path to a logo image file to be displayed in the <i>gitweb</i> header.<br><br><b><b>$favicon</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Path to a favicon image file for the website.<br><br><b><b>$stylesheet</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Path to a custom CSS stylesheet to override default <i>gitweb</i> styles.<br><br>


title: DESCRIPTION
content:
<i>gitweb</i> is a Perl CGI (Common Gateway Interface) script that provides a web-based interface for browsing Git repositories. It allows users to view commit history, file contents, diffs, branches, tags, and more, all through a standard web browser. Typically, <i>gitweb</i> is configured to run with a web server like Apache or Nginx, which executes the script when a user accesses its URL. It offers a read-only view of repositories, making it suitable for publicly exposing Git projects without allowing direct push access. Its behavior and appearance are highly configurable through a dedicated configuration file, <br><code>gitweb.conf</code>, which defines various options like the project root directory, enabled features, and theme settings. It's a fundamental tool for many self-hosted Git instances, providing a simple yet powerful way to explore repositories.


title: CAVEATS
content:
<i>gitweb</i> relies heavily on correct web server configuration (e.g., Apache's <code>ScriptAlias</code> or Nginx's <code>fastcgi_pass</code> directives) to function properly. Misconfigurations can lead to broken links or security vulnerabilities.<br>It is primarily a read-only interface; it does not provide mechanisms for pushing commits or managing user access beyond visibility controls.<br>Performance can be an issue for very large instances with thousands of repositories or extremely active repositories if the web server and underlying file system are not adequately tuned.


title: CONFIGURATION FILE (GITWEB.CONF)
content:
The primary way to configure <i>gitweb</i> is through the <code>gitweb.conf</code> file. This file, typically located in <code>/etc/gitweb.conf</code> or determined by the web server configuration, is a Perl script that sets global variables controlling <i>gitweb</i>'s behavior, appearance, and features. It's crucial for defining repository paths, enabling features like snapshot downloads or search, and customizing branding.


title: SECURITY CONSIDERATIONS
content:
As a CGI script, <i>gitweb</i> execution environment should be carefully secured. Ensure the web server executes the script with appropriate permissions and that the <code>$projectroot</code> and other paths are correctly configured to prevent unauthorized access to sensitive files. It's recommended to run it in a <br>chroot environment or with minimal privileges if possible. Always keep <i>gitweb</i> and the underlying Git installation up to date to benefit from security fixes.


title: HISTORY
content:
<i>gitweb</i> was an early and integral component of the Git project, providing a simple yet effective way to browse Git repositories over the web. It was originally developed by Kay Sievers and has since been maintained and extended by the broader Git development community. Its development started around 2005, shortly after Git itself, to provide a readily available web interface for projects hosted with Git. Before the rise of more complex platforms like GitHub or GitLab, <i>gitweb</i> was a standard choice for self-hosting public Git repositories, and it continues to be a robust, lightweight option for those who prefer a minimalist web interface directly integrated with their Git installations.


title: PARAMETERS
content:
<b><i>&lt;PATH_TO_NGINX_CONF&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The path to the Nginx configuration file or directory to be analyzed.<br><br><b>-h, --help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays the help message and exits.<br><br><b>-v, --version</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows the program's version number and exits.<br><br><b>-c <i>&lt;CONFIG_FILE&gt;</i>, --config=<i>&lt;CONFIG_FILE&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies an alternative configuration file for Gixy itself, not Nginx.<br><br><b>-f <i>&lt;FORMAT&gt;</i>, --format=<i>&lt;FORMAT&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the output format, e.g., <i>text</i>, <i>json</i>, <i>xml</i>.<br><br><b>--strict</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Treats all warnings found as errors.<br><br><b>--all-warnings</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows all warnings, including those disabled by default.<br><br><b>--enable <i>&lt;RULE[,RULE...]&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables specific Gixy rules by their ID or name.<br><br><b>--disable <i>&lt;RULE[,RULE...]&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Disables specific Gixy rules by their ID or name.<br><br><b>--stdin</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Reads Nginx configuration from standard input.<br><br><b>--quiet</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Suppresses all output except for errors and issues found.<br><br><b>--diff</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows diff in current Nginx config and default configuration.<br><br>


title: DESCRIPTION
content:
Gixy is a specialized security linter designed to analyze Nginx web server configuration files for potential vulnerabilities and misconfigurations. Developed and open-sourced by Yandex, it helps administrators identify common security pitfalls such as insecure SSL/TLS settings, improper redirects, potential information disclosure, weak CORS policies, and path traversal vulnerabilities. By parsing the Nginx configuration, Gixy applies a comprehensive set of predefined rules to highlight problematic directives or patterns, providing actionable insights to enhance the server's security posture. It acts as an automated security audit tool, crucial for maintaining secure Nginx deployments and can be seamlessly integrated into development and deployment workflows to enforce security best practices proactively.


title: CAVEATS
content:
Gixy is a Python application and requires a Python environment to run. It primarily acts as a static analysis tool; it cannot detect runtime vulnerabilities or issues not covered by its predefined rule set. Its effectiveness relies on the comprehensiveness and up-to-date status of its internal security rules.


title: RULE IDS AND CUSTOMIZATION
content:
Gixy categorizes security checks into various rule IDs (e.g., <i>ssrf</i>, <i>redirect</i>, <i>hsts</i>, <i>xss</i>, <i>path_traversal</i>), allowing users to enable or disable specific checks based on their security requirements. This flexibility helps in tailoring the linting process to specific organizational policies or compliance needs.


title: CI/CD INTEGRATION
content:
The command-line nature of Gixy makes it ideal for integration into Continuous Integration/Continuous Deployment (CI/CD) pipelines. Automating security checks during the build or deployment phase ensures that insecure Nginx configurations are identified and rectified before they reach production environments, enforcing a 'security-first' approach in the development lifecycle.


title: HISTORY
content:
Developed by Yandex, Gixy was open-sourced to help the community secure Nginx configurations. Its creation stemmed from an internal need at Yandex for automated security auditing of Nginx instances. Since its release, it has been actively maintained on GitHub, with ongoing contributions to expand its rule set and improve its analysis capabilities, reflecting the evolving landscape of web security.


title: PARAMETERS
content:
<b>-u, --user <user></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Specify the user to run the command as (default is root).</i><br><br><b>-k, --sudo</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Force the use of 'sudo' instead of 'su' for privilege escalation.</i><br><br><b>-g, --disable-grab</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Do not grab the keyboard and mouse during password prompting.</i><br><br><b>-p, --preserve-env</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Attempt to preserve the current environment variables.</i><br><br><b>-D, --display <display></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Specify the X display to use for the graphical dialog and application.</i><br><br><b>-m, --message <message></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Provide a custom message to be shown in the password dialog.</i><br><br><b>-d, --description <description></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Add a description for the application entry in the menu.</i><br><br><b>--prompt-password</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Always prompt for the password, even if cached.</i><br><br><b>--help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Display a help message and exit.</i><br><br><b>--version</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Output version information and exit.</i><br><br>


title: DESCRIPTION
content:
<i>gksu</i> is a GTK+ frontend for the <i>su</i> and <i>sudo</i> commands, designed to securely run graphical applications requiring root privileges. It provides a user-friendly graphical dialog box to prompt for a password, ensuring the X display environment variables (like DISPLAY and XAUTHORITY) are correctly set for the target application to run within the user's active graphical session.<br><br>Its primary purpose was to prevent users from running their entire desktop environment as root, a highly insecure practice, while still allowing specific administrative tools to function. While widely used in older GNOME-based systems, <i>gksu</i> is now largely considered deprecated. Modern Linux distributions increasingly prefer Polkit-based solutions like <i>pkexec</i> or direct use of <i>sudo -H</i> for launching graphical applications as root, which offer more granular control and better integration with system policies. This shift reflects a move towards more secure and fine-grained privilege management.


title: CAVEATS
content:
<i><b>Security Risk:</b> Running untrusted graphical applications as root can severely compromise your system. Only execute commands from trusted sources.<br><b>Deprecation:</b> gksu is largely deprecated in modern Linux distributions. Many systems now prefer pkexec or sudo -H due to enhanced security and flexibility.<br><b>Environment Issues:</b> While it attempts to handle DISPLAY and XAUTHORITY, complex X setups might still encounter issues.</i>


title: <I>XAUTHORITY AND DISPLAY MANAGEMENT</I>
content:
<i>gksu's key feature was its ability to correctly set up DISPLAY and XAUTHORITY environment variables for the root process. This allowed graphical applications launched as root to display correctly on the user's X session, which is crucial for GUI programs that interact with the X server. Misconfigured XAUTHORITY often leads to 'cannot open display' errors.</i>


title: <I>MODERN ALTERNATIVES</I>
content:
<i>For running graphical applications with elevated privileges today, pkexec is the recommended method. It uses Polkit for policy-based authorization, offering more fine-grained control and a more secure model. Alternatively, sudo -H can be used to set the HOME environment variable to the target user's home directory, which is often sufficient for graphical applications to run correctly while avoiding common X-related issues associated with direct sudo use.</i>


title: HISTORY
content:
<i>gksu</i> (and its counterpart <i>gksudo</i>) emerged as essential tools for GNOME desktop environments, providing a graphical and safer alternative to directly running <i>su</i> or <i>sudo</i> on the command line for GUI applications. It addressed the critical need to avoid running an entire desktop session as root. Initially a core component of privilege escalation in many popular distributions, its prominence began to wane with the rise of PolicyKit (Polkit), which offered a more granular and policy-driven approach to privilege management. Consequently, <i>gksu</i> has been removed from or marked for deprecation in many modern Linux distributions, favoring <i>pkexec</i> for better security and system integration. Its development and maintenance have largely ceased.


title: SYNOPSIS
content:
<B>gksu-properties</B><br><I>(Runs without arguments to launch its graphical configuration interface.)</I>


title: DESCRIPTION
content:
<I>gksu-properties</I> is a graphical utility designed to configure the behavior of the <I>gksu</I> and <I>gksudo</I> commands. These commands provided a convenient graphical front-end for executing applications with elevated privileges (typically as the root user) within a desktop environment, serving a similar purpose to the command-line <I>su</I> and <I>sudo</I> utilities. The <I>gksu-properties</I> tool allowed users to customize key aspects of <I>gksu</I>'s operation. This included settings such as whether to remember passwords across multiple invocations, the duration of the password memory timeout, and the choice between using <I>su</I> or <I>sudo</I> as the underlying privilege escalation mechanism. It offered a user-friendly interface to manage how graphical applications request and handle administrative rights, aiming to simplify a common administrative task for desktop users.


title: CAVEATS
content:
<I>gksu</I> and its related tools, including <I>gksu-properties</I>, are largely considered deprecated in modern Linux distributions (e.g., Ubuntu since 18.04). They have been superseded by more modern and often more secure alternatives like <I>pkexec</I> (part of Polkit) or by using commands like <I>gnome-terminal -- sudo</I> for elevated operations within a terminal. Running graphical applications as the root user, which <I>gksu</I> facilitates, is generally discouraged due to potential security vulnerabilities and system instability. Using a less privileged user and escalating only specific commands is the preferred approach.


title: GUI CONFIGURATION
content:
<I>gksu-properties</I> is exclusively a graphical application. Executing it from the command line launches a separate window where users can interact with its settings through a point-and-click interface, rather than accepting command-line arguments for configuration.


title: CONFIGURABLE SETTINGS
content:
The tool allowed users to modify settings such as the <I>Password timeout</I> (how long credentials are remembered), whether to <I>Remember passwords</I> at all, and the choice of <I>Authentication backend</I> (<I>su</I> or <I>sudo</I>).


title: HISTORY
content:
The <I>gksu</I> suite, including <I>gksu-properties</I>, emerged as a prominent toolset in GNOME-based desktop environments to bridge the gap between graphical applications and the need for root privileges. It provided a simpler, more integrated user experience compared to constantly dropping to a terminal for administrative tasks. Its development aligned with the growth of Linux as a desktop operating system, making privilege escalation more accessible. However, with evolving security paradigms and the adoption of Polkit and Wayland, the design principles behind <I>gksu</I> became less optimal. Consequently, many distributions began phasing out <I>gksu</I> in favor of more granular and secure privilege management frameworks, leading to the obsolescence of <I>gksu-properties</I> as well.


title: SYNOPSIS
content:
<b>glab</b> <i>&lt;command&gt;</i> [<i>&lt;flags&gt;</i>] [<i>&lt;arguments&gt;...</i>]<br><b>glab</b> <i>&lt;group&gt;</i> <i>&lt;subcommand&gt;</i> [<i>&lt;flags&gt;</i>] [<i>&lt;arguments&gt;...</i>]


title: PARAMETERS
content:
<b><b>-h</b>, <b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show help for the current command or subcommand.<br><br><b><b>-v</b>, <b>--version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show the <b>glab</b> version information.<br><br><b><b>-R</b>, <b>--repo</b> <i>&lt;path&gt;|&lt;owner&gt;/&lt;repo&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify a GitLab repository to operate on (e.g., <i>gitlab-org/glab</i> or <i>/home/user/my-repo</i>).<br><br><b><b>--gitlab-hostname</b> <i>&lt;hostname&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the GitLab hostname to interact with (e.g., <i>gitlab.com</i> or <i>my-gitlab.com</i>).<br><br><b><b>--token</b> <i>&lt;token&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Provide a GitLab personal access token for authentication, overriding configured credentials.<br><br><b><b>--confirm</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Confirm any prompts without user interaction, useful for scripting or automation.<br><br><b><b>--no-prompt</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Disable interactive prompts, similar to <b>--confirm</b>.<br><br><b><b>--output</b> <i>&lt;format&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Format the command's output (e.g., <i>json</i>, <i>yaml</i>, <i>text</i>, <i>csv</i>).<br><br><b><b>--color</b> <i>&lt;when&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Control color output (options include <i>always</i>, <i>auto</i>, <i>never</i>).<br><br><b><b>--verbose</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enable verbose output for debugging purposes, showing additional details about operations.<br><br>


title: DESCRIPTION
content:
<b>glab</b> is the official open-source command-line tool for interacting with GitLab. It brings a rich set of GitLab's features directly to your terminal, enabling developers and DevOps engineers to streamline their workflows without leaving the command line. With <b>glab</b>, users can effortlessly manage common GitLab operations such as listing, creating, and updating issues and merge requests, viewing and interacting with CI/CD pipelines, browsing repositories, and much more. It's designed for user-friendliness, providing a consistent and intuitive interface similar to how <b>gh</b> (GitHub CLI) interacts with GitHub.<br><br><b>glab</b> supports both GitLab.com and self-hosted GitLab instances, making it a versatile tool for any GitLab user. It significantly enhances productivity by allowing for scripting and automation of repetitive tasks, integrating seamlessly into existing development environments and CI/CD pipelines. Its active development ensures continuous alignment with new GitLab features and community needs.


title: CAVEATS
content:
<b>glab</b> requires an internet connection to communicate with GitLab instances. Authentication via a GitLab Personal Access Token is typically necessary for most operations, especially those involving private repositories or sensitive actions. While comprehensive, <b>glab</b> might not expose every single nuance of the GitLab web interface or API directly through a command, though it covers the most common workflows. As an actively developed tool, commands and options may evolve or be added in future versions.


title: AUTHENTICATION
content:
The primary method to authenticate <b>glab</b> is by running <b>glab auth login</b>. This command guides the user through the process of obtaining and storing a GitLab Personal Access Token, which <b>glab</b> uses for all authenticated operations. It supports various authentication methods, including web browser flows and token pasting.


title: CONFIGURATION
content:
<b>glab</b> allows users to configure global settings and preferences using the <b>glab config</b> command. This includes setting the default GitLab hostname, preferred text editor for interactive prompts, and other behaviors. Configuration files are typically stored in the user's home directory, allowing for persistent settings across sessions.


title: EXTENSIBILITY
content:
<b>glab</b> supports custom extensions, allowing users to create their own commands or integrate external scripts to extend its functionality. This extensibility provides a powerful way to tailor <b>glab</b> to specific workflows or integrate it with other tools and services, fostering a highly customizable command-line experience.


title: HISTORY
content:
<b>glab</b> originated as an independent community project, aiming to fulfill the need for a robust command-line interface for GitLab, mirroring the success of tools like <b>gh</b> for GitHub. Its utility and growing popularity led to its eventual adoption as the official GitLab CLI by GitLab Inc. This formal integration has ensured consistent development, better alignment with GitLab's product roadmap, and enhanced support for users. The project remains open-source, benefiting from continued community contributions and rapid feature iterations, constantly evolving to meet the demands of GitLab users worldwide.


title: SYNOPSIS
content:
<b>glab alias <I>command</I> [flags]</b><br><br>Commands:<br>  <b>glab alias list</b><br>  <b>glab alias set <I>&lt;alias-name&gt;</I> <I>&lt;command&gt;</I> [--shell]</b><br>  <b>glab alias delete <I>&lt;alias-name&gt;</I></b><br>  <b>glab alias import</b><br>  <b>glab alias export</b>


title: PARAMETERS
content:
<b>list</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Lists all currently configured <I>glab</I> aliases.<br><br><b>set <I>&lt;alias-name&gt;</I> <I>&lt;command&gt;</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Creates or updates an alias named <I>&lt;alias-name&gt;</I> that executes the specified <I>&lt;command&gt;</I>. By default, <I>&lt;command&gt;</I> is interpreted as a <I>glab</I> command sequence.<br><br><b>--shell</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Used with <I>set</I> to indicate that the <I>&lt;command&gt;</I> should be executed as a shell command, rather than a <I>glab</I> command. This allows aliasing complex shell scripts or other executables.<br><br><b>delete <I>&lt;alias-name&gt;</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Removes the alias specified by <I>&lt;alias-name&gt;</I> from the configuration.<br><br><b>import</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Imports aliases from a file or standard input. This can be used to transfer alias configurations between different machines or share them.<br><br><b>export</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Exports existing aliases to standard output or a specified file. Useful for backing up or sharing alias configurations.<br><br>


title: DESCRIPTION
content:
The <I>glab-alias</I> command, part of the <I>glab</I> GitLab CLI, provides functionality to manage custom command aliases. It allows users to define shorter, more memorable names for frequently used <I>glab</I> commands or even complex shell commands, significantly improving workflow efficiency. Aliases are stored in the user's <I>glab</I> configuration file (typically <I>~/.config/glab-cli/config.yml</I>) and are automatically loaded by <I>glab</I>. This feature is essential for power users who want to customize their CLI experience and reduce repetitive typing for common GitLab operations.


