x-motemen/ghq
Ghq
ghq is a command line tool and repository manager designed to automate the cloning, organization, and lifecycle management of remote version control repositories. It functions as a wrapper for cloning that maps remote repository URLs to a consistent, structured local directory hierarchy.
The tool differentiates itself by implementing deterministic URL-to-path mapping and a VCS-agnostic cloning pipeline. It supports shallow copies, recursive submodule fetching, and the ability to resolve repository locations from various hosts and version control systems.
Its broader capabilities cover repository discovery through local indexing and filtering, maintenance via automated updates, and migration tools that identify linked worktrees. It also provides utilities for URL normalization and the safe removal of managed repositories from the filesystem.
Features
- Deterministic Path Mapping - Translates remote repository URLs into deterministic local filesystem paths for consistent project organization.
- Repository Cloning Tools - Provides automated cloning of remote repositories with support for shallow copies and recursive submodules.
- Local Repository Initializers - Creates new repositories within a designated managed directory structure to start projects locally.
- Git Repository Managers - Manages the cloning, organization, and local storage of multiple Git repositories in a structured hierarchy.
- Local Repository Updaters - Refreshes existing local clones with the latest changes from their remote source repositories.
- Repository Path Mapping - Assigns remote repository URLs to specific local directory paths to ensure consistent project placement.
- Cross-VCS Cloning - Fetches source code from multiple version control systems by parsing the remote repository URL.
- Shallow Cloning - Implements shallow cloning and partial clones to minimize disk and network overhead.
- Multi-Repository Cloning - Organizes the cloning of multiple remote repositories into a consistent and structured local workspace.
- Repository Lifecycle Management - Manages the full lifecycle of local clones, including initialization, updates, migration, and deletion.
- VCS-Agnostic Cloning Interfaces - Abstracts multiple version control systems and hosts into a common interface for fetching source code.
- Local Repository Organization - Downloads source code from various version control systems and arranges them into predictable local filesystem paths.
- Git Wrappers - Functions as a wrapper that extends standard git clone with automated path resolution and shallow copies.
- Directory-Based Organization - Arranges downloaded repositories into a consistent, structured directory hierarchy for local management.
- Project Organization - Structures repositories into a consistent directory hierarchy based on remote URLs to improve navigation.
- Repository Name Searches - Provides the ability to search and locate cloned projects on the local machine by name or URL.
- Local Repository Listings - Displays cloned repositories with options to filter by name and show full filesystem paths.
- Hosting Provider API Integrations - Integrates with various remote hosting providers and version control backends to fetch source code.
- Managed Repository Deletions - Deletes local repositories and their associated linked worktrees from the file system.
- Meta-Tag Repository Discovery - Extracts version control system data from HTML meta tags to resolve import paths to actual remote repositories.
- Repository Root Detection - Identifies and displays the local filesystem paths where managed repositories are stored.
- Source Code Mirroring - Enables downloading and managing large collections of remote repositories for offline reference.
- VCS Repository Detectors - Identifies the version control system and extracts the remote repository URL from provided input strings.
- Managed Repository Filters - Retrieves lists of cloned repositories using query filters and case-sensitivity toggles.
- Submodule and Worktree Management - Analyzes linked Git worktrees and submodules to ensure safe repository migration without breaking references.
- Managed Repository Migrations - Moves local repositories into a managed directory structure while updating linked worktrees and submodules.
- URL Normalizers - Converts various address formats and shorthand notations into standard SSH or HTTPS URLs.
- Project Root Resolution - Provides configurable logic to determine the local project root using environment variables and configuration files.
- Source Root Configurators - Defines base storage directories for managed repositories via environment variables and configuration files.
