[](https://crates.io/crates/git-url-parse)
[](https://crates.io/crates/git-url-parse)
[](https://github.com/tjtelan/git-url-parse-rs/actions/workflows/ci.yml)
[](https://docs.rs/git-url-parse/)
[](LICENSE)
---
<!-- cargo-rdme start -->
# Git Url Parse
Parses url used by git (e.g. `git clone <url>`)
## Features
- 🔍 Parses `git clone` compatible urls into [`GitUrl`](https://docs.rs/git-url-parse/latest/git_url_parse/types/struct.GitUrl.html)
- Supports multiple Git URL schemes (SSH, HTTP, HTTPS, File)
- Inspired by [RFC 3986](https://datatracker.ietf.org/doc/html/rfc3986) with adaptations to support Git urls
- 🏗️ Host provider info extraction
- Easy to implement trait [`GitProvider`](https://docs.rs/git-url-parse/latest/git_url_parse/types/provider/trait.GitProvider.html) for custom provider parsing
- Built-in support for multiple Git hosting providers
* [Generic](https://docs.rs/git-url-parse/latest/git_url_parse/types/provider/struct.GenericProvider.html) (`git@host:owner/repo.git` style urls)
* [GitLab](https://docs.rs/git-url-parse/latest/git_url_parse/types/provider/struct.GitLabProvider.html)
* [Azure DevOps](https://docs.rs/git-url-parse/latest/git_url_parse/types/provider/struct.AzureDevOpsProvider.html)
## Quick Example
```rust
use git_url_parse::{GitUrl, GitUrlParseError};
use git_url_parse::types::provider::GitProvider;
use git_url_parse::types::provider::GenericProvider;
fn main() -> Result<(), git_url_parse::GitUrlParseError> {
let http_url = GitUrl::parse("https://github.com/tjtelan/git-url-parse-rs.git")?;
// Extract basic URL components
assert_eq!(http_url.host(), Some("github.com"));
assert_eq!(http_url.path(), "/tjtelan/git-url-parse-rs.git");
// Support ssh-based urls as well
let ssh_url = GitUrl::parse("git@github.com:tjtelan/git-url-parse-rs.git")?;
assert_eq!(ssh_url.scheme(), Some("ssh"));
assert_eq!(ssh_url.host(), Some("github.com"));
assert_eq!(ssh_url.path(), "tjtelan/git-url-parse-rs.git");
// Extract provider-specific information
// Built-in support for Github (Generic), Gitlab, Azure Devops style urls
let provider : GenericProvider = ssh_url.provider_info()?;
assert_eq!(provider.owner(), "tjtelan");
assert_eq!(provider.repo(), "git-url-parse-rs");
// Implement your own provider
#[derive(Debug, Clone, PartialEq, Eq)]
struct CustomProvider;
impl GitProvider<GitUrl<'_>, GitUrlParseError> for CustomProvider {
fn from_git_url(_url: &GitUrl) -> Result<Self, GitUrlParseError> {
// Your custom provider parsing here
Ok(Self)
}
}
let custom_provider: CustomProvider = ssh_url.provider_info()?;
let expected = CustomProvider;
assert_eq!(custom_provider, expected);
Ok(())
}
```
## Limitations
Intended only for git repo urls. Url spec [RFC 3986](https://datatracker.ietf.org/doc/html/rfc3986) is not fully implemented.
- No support for:
- Query parameters
- Fragment identifiers
- Percent-encoding
- Complex IP address formats
## Install
```shell
cargo add git-url-parse
```
### Cargo Features
#### `log`
Enable for internal `debug!` output from [log](https://docs.rs/log/latest)
#### `serde`
Enable for [serde](https://docs.rs/serde/latest/) `Serialize`/`Deserialize` on [`GitUrl`](https://docs.rs/git-url-parse/latest/git_url_parse/types/struct.GitUrl.html)
#### `url`
(**enabled by default**)
Uses [url](https://docs.rs/url/latest/) during parsing for full url validation
<!-- cargo-rdme end -->
## Migration from 0.4.x and earlier
This crate was one of my first serious projects in Rust. Because I was still learning, it had some maintenance problems and was a bit awkward to use. In version 0.5, I rewrote most of it to fix those issues.
The [`GitUrl`](https://docs.rs/git-url-parse/latest/git_url_parse/types/struct.GitUrl.html) struct is only meant to handle parsing urls used by `git`, which the [url](https://docs.rs/url/latest/url) crate doesn't handle. The recent updates make it so the input string is parsed and internally stored into a simple string slice (`&str`). And, instead of exposing all the internal fields of the struct, those details are hidden, and we use methods to interact with it.
The [`GitProvider`](https://docs.rs/git-url-parse/latest/git_url_parse/types/provider/trait.GitProvider.html) trait helps extract common pieces of information that are often found in different url patterns using the [`GitUrl::provider_info`](https://docs.rs/git-url-parse/latest/git_url_parse/types/struct.GitUrl.html#method.provider_info) method. Several example provider parsers are included to show how this works. The result of [`GitUrl::parse`](https://docs.rs/git-url-parse/latest/git_url_parse/types/struct.GitUrl.html#method.parse) is more straightforward to use, but the internal details are hidden, and working with provider-specific information at the git host level is more specialized.
The most common pattern for git url paths, like `/owner/repo.git`, is handled by [`GenericProvider`](https://docs.rs/git-url-parse/latest/git_url_parse/types/provider/struct.GenericProvider.html).
There's also [`AzureDevOpsProvider`](https://docs.rs/git-url-parse/latest/git_url_parse/types/provider/struct.AzureDevOpsProvider.html), which is designed for Azure DevOps urls that follow the `org`, `project`, `repo` pattern.
Finally, there's a new supported provider called [`GitLabProvider`](https://docs.rs/git-url-parse/latest/git_url_parse/types/provider/struct.GitLabProvider.html), which is for GitLab urls. It supports the common `owner/repo` pattern shared with [`GenericProvider`](https://docs.rs/git-url-parse/latest/git_url_parse/types/provider/struct.GenericProvider.html), and also handles GitLab’s subgroups.