Skip to content

Latest commit

 

History

History
128 lines (86 loc) · 3.54 KB

README.md

File metadata and controls

128 lines (86 loc) · 3.54 KB
Raw

Gitly

An Elixir library for easily downloading and extracting Git repositories from various hosting services.

codecov Elixir CI Hex.pm Hex.pm Hex.pm

Features

  • Download repositories from popular Git hosts
  • Extract downloaded archives
  • Flexible options for caching, retrying, and formatting
  • Support for various archive formats (zip, tar, tar.gz, tgz) if supported by the provider
  • Support for various hosts (GitHub, GitLab, BitBucket)

Installation

Add gitly to your list of dependencies in mix.exs:

def deps do
  [
    {:gitly, "~> 0.1.0"}
  ]
end

Then run mix deps.get to install the dependency.

Usage

Basic Usage

To download and extract a repository:

import Gitly, only: [gitly: 1, gitly: 2]
{:ok, path} = gitly("username/repo")

This will download the repository and return the path to the extracted contents.

The following inputs are supported:

  • owner/repo
  • https://host.com/owner/repo
  • https://host.com/owner/repo.git
  • host.com/owner/repo
  • host:owner/repo

Note

gitly will return the path that includes the root of the extracted directory. If there are more than one folder in the parent directory, then the path to the parent directory would be returned. This behavior may change in the future.

Download Only

If you only want to download the repository without extracting:

import Gitly, only: [download: 1, download: 2]
{:ok, _path} = download("username/repo")

Extract an Existing Archive

To extract an already downloaded archive:

import Gitly, only: [extract: 1, extract: 2]
{:ok, _path } = extract("/path/to/archive.zip")

Or to specify a destination:

import Gitly, only: [extract: 1, extract: 2]
{:ok, _path } = extract("/path/to/archive.zip", "/path/to/destination")

Note

extract will return the path that you specified.

Options

Gitly supports various options to customize its behavior:

  • :force - Force download even if the archive already exists
  • :cache - Use local cache for downloads
  • :overwrite - Overwrite existing files when extracting
  • :retry - Retry options for failed downloads
  • :retry_delay - Custom function to determine delay between retries
  • :retry_log_level - Set log level for retry attempts
  • :max_retries - Maximum number of retry attempts
  • :ref - Specify a particular Git reference to download
  • :root - Set the root path for storing archives
  • :format - Specify the archive format (:zip, :tar, :tar_gz, or :tgz)

Example with options:

import Gitly, only: [gitly: 1, gitly: 2]
gitly("username/repo", force: true, format: :zip, ref: "main")

Documentation

For more detailed documentation, run mix docs and open doc/index.html in your browser.

This project uses git-cliff for changelog generation.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License.

Changelog

See CHANGELOG.md for the latest changes.