Git Url Parse

Parses url used by git (e.g. git clone <url>)

Features

• 🔍 Parses git clone compatible urls into GitUrl

  • Supports multiple Git URL schemes (SSH, HTTP, HTTPS, File)
  • Inspired by RFC 3986 with adaptations to support Git urls

• 🏗️ Host provider info extraction

  • Easy to implement trait GitProvider for custom provider parsing
  • Built-in support for multiple Git hosting providers
    • Generic (git@host:owner/repo.git style urls)
    • GitLab
    • Azure DevOps

Quick Example

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 is not fully implemented.

• No support for:
  • Query parameters
  • Fragment identifiers
  • Percent-encoding
  • Complex IP address formats

Install

cargo add git-url-parse

Cargo Features

log

Enable for internal debug! output from log

serde

Enable for serde Serialize/Deserialize on GitUrl

url

(enabled by default)

GitUrl parsing finishes with url during parsing for full url validation

[GitUrl::parse_to_url] will normalize an ssh-based url and return url::Url

You can use url::Url with the built-in GitProvider host parsers. See the url_interop tests for examples

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 struct is only meant to handle parsing urls used by git, which the 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 trait helps extract common pieces of information that are often found in different url patterns using the GitUrl::provider_info method. Several example provider parsers are included to show how this works. The result of GitUrl::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.

There's also AzureDevOpsProvider, which is designed for Azure DevOps urls that follow the org, project, repo pattern.

Finally, there's a new supported provider called GitLabProvider, which is for GitLab urls. It supports the common owner/repo pattern shared with GenericProvider, and also handles GitLab’s subgroups.