gigit

README

gigit - A simple CLI tool for fetching and cloning GitHub repositories

gigit is a command-line tool for easily fetching, downloading, and cloning GitHub repositories. It allows users to retrieve repositories by specifying the user, repository name, and commit hash or branch. The tool supports downloading repository archives, cloning repositories, and handling specific subdirectories or tags with simple commands.

Features:

• Fetching Repositories: Supports fetching repositories by user/repo name, including commit hashes, branches, or tags.
• Subdirectory Fetching: Ability to fetch specific subdirectories within repositories.
• Cloning Repositories: Clone repositories from GitHub with support for shallow clones (--depth=1).
• Versioning Support: Handles specific commits or version tags (e.g., v1.0.0).
• Error Handling & Retries: Provides helpful error messages and retries the fetch or clone process if needed.

Commands:

• gigit user/repo: Fetches the latest commit of the specified repository.
• gigit user/repo/subdir: Fetches the repository and specific subdirectory.
• gigit user/repo#commit: Fetches a specific commit or branch.
• gigit clone user/repo: Clones the specified repository.
• gigit c1 user/repo: Clones the repository with --depth=1 for a shallow clone.
• gigit help: Displays help information for using the tool.

Installation:

Install the gigit CLI tool using Go:

go install github.com/nazhard/gigit@latest

Example Usage:

gigit nazhard/gigit           # Fetch the latest commit of the 'gigit' repository
gigit nazhard/gigit/cmd       # Fetch the 'cmd' subdirectory from 'gigit'
gigit nazhard/gigit#v1.0.0    # Fetch a specific version 'v1.0.0' of 'gigit'
gigit clone nazhard/gigit     # Clone the 'gigit' repository
gigit c1 nazhard/gigit        # Clone the 'gigit' repository with depth=1

Error Handling:

• Invalid commands or arguments are met with helpful error messages, guiding the user on the correct usage and providing suggestions for valid commands

Documentation

Index

• func CheckCache(path, name, commitHash string) bool
• func Clone(host, userRepo string, depth bool)
• func CommitBranch(userRepo, branch string) (string, string, error)
• func Extract(source, target, destination string, strip int)
• func Get(name, commit, destination, url string) (string, error)
• func LatestCommit(userRepo string) string
• type Branch
• type Commit

Functions

func CheckCache

func CheckCache(path, name, commitHash string) bool

CheckCache checks if a specific cache file or directory exists.

Parameters:

• path: The base directory where caches are stored.
• name: The name of the repository or resource (e.g., "nazhard/gigit").
• commitHash: The commit hash or unique identifier for the cache.

Returns:

• `true` if the cache exists.
• `false` if the cache does not exist.

Behavior:

• Constructs the full cache path by combining the base path, name, and commit hash.
• Uses `os.Stat` to check if the specified path exists.
• Returns `false` if the path does not exist or there is an error.

func Clone

func Clone(host, userRepo string, depth bool)

Clone clones a Git repository from a specified host and repository name.

Parameters:

• host: The Git server's base URL (e.g., "https://github.com").
• userRepo: The repository in the format "owner/repo" (e.g., "nazhard/gigit").
• depth: A boolean value indicating whether to perform a shallow clone.
• `true`: Clones only the latest commit (`--depth=1`).
• `false`: Clones the entire repository history.

Behavior:

• Constructs a `git clone` command based on the provided parameters.
• Executes the command and streams its output (stdout and stderr) to the console.
• Ensures that the command is properly started and waited on to finish.

func CommitBranch

func CommitBranch(userRepo, branch string) (string, string, error)

CommitBranch fetches the commit hash of a specific branch in a GitHub repository. It also constructs the URL to download the branch as a tar.gz archive.

Parameters:

• userRepo: The GitHub repository in the format "owner/repo" (e.g., "nazhard/gigit").
• branch: The branch name (e.g., "main").

Returns:

• The URL to download the branch archive.
• The commit hash of the branch.
• An error if the branch does not exist or the request fails.

func Extract

func Extract(source, target, destination string, strip int)

Extract extracts a tar.gz archive to a specified destination.

Parameters:

• source: Path to the tar.gz archive.
• target: Specific file/directory to extract (leave empty to extract all).
• destination: Directory where the extracted content will be placed.
• strip: Number of leading path components to remove from file paths.

func Get

func Get(name, commit, destination, url string) (string, error)

Get downloads a specific commit or branch tarball from a GitHub repository and saves it locally.

Parameters:

• name: The GitHub repository in the format "owner/repo" (e.g., "nazhard/gigit").
• commit: The specific commit hash or branch name to fetch (e.g., "main" or a hash like "abc123").
• destination: The directory where the tarball will be saved.
• url: (Optional) A custom URL to fetch the tarball from. If empty, the default GitHub API tarball URL is used.

Returns:

• A string containing the URL used for the fetch.
• An error if the fetch fails, the directory cannot be created, or the tarball cannot be saved.

Behavior:

• Constructs the default GitHub tarball URL if no custom URL is provided.
• Sends a GET request to fetch the tarball from the URL.
• Extracts the repository name from the `name` parameter and generates a tarball filename.
• Creates the destination directory if it does not exist.
• Writes the tarball content to a file in the destination directory.
• Returns the URL used and any encountered errors.

func LatestCommit

func LatestCommit(userRepo string) string

LatestCommit fetches the latest commit hash from a specified GitHub repository.

Parameters:

• userRepo: The GitHub repository in the format "owner/repo" (e.g., "nazhard/gigit").

Returns:

• The latest commit hash as a string.
• If the request fails or there are no commits, the function returns an empty string.

Behavior:

• Sends a GET request to the GitHub API to retrieve the list of commits for the given repository.
• Parses the JSON response to extract the hash of the most recent commit.
• If there is an error (e.g., invalid repository, no internet connection), it logs the issue and exits the program.

Types

type Branch

type Branch struct {
	Commit struct {
		Sha string `json:"sha"`
	} `json:"commit"`
}

type Commit

type Commit struct {
	Sha string `json:"sha"`
}