git_url_parse/
lib.rs

1#![deny(missing_docs)]
2#![deny(clippy::missing_docs_in_private_items)]
3#![allow(rustdoc::redundant_explicit_links)] // for cargo-rdme
4
5//! # Git Url Parse
6//!
7//! Parses  url used by git (e.g. `git clone <url>`)
8//!
9//! ## Features
10//!
11//! - 🔍 Parses `git clone` compatible urls into [`GitUrl`](crate::types::GitUrl)
12//!   - Supports multiple Git URL schemes (SSH, HTTP, HTTPS, File)
13//!   - Inspired by [RFC 3986](https://datatracker.ietf.org/doc/html/rfc3986) with adaptations to support Git urls
14//!
15//! - 🏗️ Host provider info extraction
16//!   - Easy to implement trait [`GitProvider`](crate::types::provider::GitProvider) for custom provider parsing
17//!   - Built-in support for multiple Git hosting providers
18//!       * [Generic](crate::types::provider::GenericProvider) (`git@host:owner/repo.git` style urls)
19//!       * [GitLab](crate::types::provider::GitLabProvider)
20//!       * [Azure DevOps](crate::types::provider::AzureDevOpsProvider)
21//!
22//! ## Quick Example
23//!
24//! ```rust
25//! use git_url_parse::{GitUrl, GitUrlParseError};
26//! use git_url_parse::types::provider::GitProvider;
27//! use git_url_parse::types::provider::GenericProvider;
28//!
29//! fn main() -> Result<(), git_url_parse::GitUrlParseError> {
30//!     let http_url = GitUrl::parse("https://github.com/tjtelan/git-url-parse-rs.git")?;
31//!     
32//!     // Extract basic URL components
33//!     assert_eq!(http_url.host(), Some("github.com"));
34//!     assert_eq!(http_url.path(), "/tjtelan/git-url-parse-rs.git");
35//!
36//!     // Support ssh-based urls as well
37//!     let ssh_url = GitUrl::parse("git@github.com:tjtelan/git-url-parse-rs.git")?;
38//!
39//!     assert_eq!(ssh_url.scheme(), Some("ssh"));
40//!     assert_eq!(ssh_url.host(), Some("github.com"));
41//!     assert_eq!(ssh_url.path(), "tjtelan/git-url-parse-rs.git");
42//!     
43//!     // Extract provider-specific information
44//!     // Built-in support for Github (Generic), Gitlab, Azure Devops style urls
45//!     let provider : GenericProvider = ssh_url.provider_info()?;
46//!     assert_eq!(provider.owner(), "tjtelan");
47//!     assert_eq!(provider.repo(), "git-url-parse-rs");
48//!
49//!     // Implement your own provider
50//!     #[derive(Debug, Clone, PartialEq, Eq)]
51//!     struct CustomProvider;
52//!     
53//!     impl GitProvider<GitUrl<'_>, GitUrlParseError> for CustomProvider {
54//!         fn from_git_url(_url: &GitUrl) -> Result<Self, GitUrlParseError> {
55//!             // Your custom provider parsing here
56//!             Ok(Self)
57//!         }
58//!     }
59//!
60//!     let custom_provider: CustomProvider = ssh_url.provider_info()?;
61//!     let expected = CustomProvider;
62//!     assert_eq!(custom_provider, expected);
63//!     
64//!     Ok(())
65//! }
66//! ```
67//!
68//! ## Limitations
69//!
70//!  Intended only for git repo urls. Url spec [RFC 3986](https://datatracker.ietf.org/doc/html/rfc3986) is not fully implemented.
71//!
72//! - No support for:
73//!   - Query parameters
74//!   - Fragment identifiers
75//!   - Percent-encoding
76//!   - Complex IP address formats
77//!
78//! ## Install
79//!
80//! ```shell
81//! cargo add git-url-parse
82//! ```
83//!
84//! ### Cargo Features
85//!
86//! #### `log`
87//! Enable for internal `debug!` output from [log](https://docs.rs/log/latest)
88//! #### `serde`
89//! Enable for [serde](https://docs.rs/serde/latest/) `Serialize`/`Deserialize` on [`GitUrl`](crate::types::GitUrl)
90//! #### `url`
91//! (**enabled by default**)
92//!
93//! Uses [url](https://docs.rs/url/latest/) during parsing for full url validation
94//!
95
96pub mod types;
97
98/// Re-exports
99pub use types::{GitUrl, GitUrlParseError};
git_url_parse/lib.rs

git_url_parse/
lib.rs
