gem-clone

A RubyGems plugin that allows you to clone gem repositories by fetching source code URLs from gem metadata and using git goget, ghq, or git clone.

Usage

Basic Usage

# Clone a gem repository
gem clone sinatra

# Clone with verbose output
gem clone rails --verbose

# Show repository URL without cloning
gem clone rails --show-url

Options

-v, --verbose: Show verbose output during execution
-u, --show-url: Display the repository URL without executing the clone operation

Examples

# With git goget available (preferred)
$ gem clone sinatra
Executing: git goget https://github.com/sinatra/sinatra
Successfully cloned repository: https://github.com/sinatra/sinatra

# Fallback to ghq when git goget is not available
$ gem clone rails --verbose
Fetching gem metadata for 'rails'...
Found repository URL: https://github.com/rails/rails
git goget not found, falling back to ghq
Executing: ghq get https://github.com/rails/rails
Successfully cloned repository: https://github.com/rails/rails

# Fallback to git clone when neither git goget nor ghq is available
$ gem clone rails --verbose
Fetching gem metadata for 'rails'...
Found repository URL: https://github.com/rails/rails
ghq not found, falling back to git clone
Executing: git clone https://github.com/rails/rails
Successfully cloned repository: https://github.com/rails/rails

# Show URL only
$ gem clone rails --show-url
https://github.com/rails/rails

Installation

From RubyGems

gem install gem-clone

From Source

git clone https://github.com/hsbt/gem-clone.git
cd gem-clone
gem build gem-clone.gemspec
gem install gem-clone-*.gem

Prerequisites

This plugin works best with git goget but will automatically fall back to ghq or git clone if git goget is not available.

Recommended: Install git goget

git goget is a bash script for cloning Git repositories with additional features.

# Install git goget from GitHub
git clone https://github.com/hsbt/git-goget.git
cd git-goget
chmod +x git-goget
# Copy to a directory in your PATH
cp git-goget /usr/local/bin/

# Or download directly
curl -o git-goget https://raw.githubusercontent.com/hsbt/git-goget/main/git-goget
chmod +x git-goget
cp git-goget /usr/local/bin/

Alternative: Install ghq

# Install ghq (example for macOS)
brew install ghq

# Or install via Go
go install github.com/x-motemen/ghq@latest

# Or download binary from GitHub releases
# https://github.com/x-motemen/ghq/releases

Fallback: Git only

If neither git goget nor ghq is installed, the plugin will automatically use git clone instead. Make sure git is available in your PATH.

Technical Details

How it works

The plugin performs the following steps:

Fetch gem metadata from RubyGems.org API (/api/v1/gems/{gem_name}.json)
Extract repository URL from gem metadata in this priority order:
- source_code_uri metadata field
- homepage_uri (if it looks like a repository URL)
Normalize URL by removing version-specific paths (e.g., /tree/v1.0.0, /blob/main/README.md)
Clone repository using:
- git goget <url> (preferred method if available)
- ghq get <url> (fallback if git goget is not available)
- git clone <url> (fallback if neither git goget nor ghq is available)
- Display URL only if --show-url option is specified

URL Normalization

The plugin automatically normalizes repository URLs by removing common Git hosting service paths:

/tree/* → removed (GitHub, GitLab branches/tags)
/blob/* → removed (GitHub, GitLab file views)
/commits/* → removed (commit history pages)
/releases/* → removed (release pages)
/issues/* → removed (issue pages)
/pull/* → removed (pull request pages)
/tags/* → removed (tag pages)
/branches/* → removed (branch pages)

Example:

https://github.com/rails/rails/tree/v8.0.2 → https://github.com/rails/rails

Cross-platform Support

The plugin includes cross-platform command detection:

Unix/Linux/macOS: Uses which command
Windows: Uses where command
Error handling: Gracefully handles missing commands

Supported Repository Hosts

The plugin recognizes repository URLs from:

GitHub (github.com)
GitLab (gitlab.com)
Bitbucket (bitbucket.org)
Codeberg (codeberg.org)
SourceHut (sourcehut.org)

Requirements

Ruby >= 2.7.0
RubyGems
git goget (recommended), ghq (alternative), or git (fallback)

Development

Setting up the development environment

# Clone the repository
git clone https://github.com/hsbt/gem-clone.git
cd gem-clone

# Install dependencies
bundle install

# Run tests
bundle exec rake test

# Build the gem
gem build gem-clone.gemspec

Running Tests

# Run all tests
bundle exec rake test

# Run specific test file
ruby -Ilib:test test/clone_command_test.rb

# Run with verbose output
ruby -Ilib:test test/clone_command_test.rb --verbose

Contributing

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Make your changes and add tests
Run the test suite (bundle exec rake test)
Commit your changes (git commit -am 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

License

This gem is available as open source under the terms of the MIT License.

MIT License

Copyright (c) 2024 Hiroshi SHIBATA

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.