An Elixir library for easily downloading and extracting Git repositories from various hosting services.
- 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)
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.
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
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.
If you only want to download the repository without extracting:
import Gitly, only: [download: 1, download: 2]
{:ok, _path} = download("username/repo")
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")
extract
will return the path that you specified.
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")
For more detailed documentation, run mix docs
and open doc/index.html
in your browser.
This project uses git-cliff for changelog generation.
Contributions are welcome! Please feel free to submit a Pull Request.
This project is licensed under the MIT License.
See CHANGELOG.md for the latest changes.