From 5bfd150fbe6b410628dffceab457accf714e1823 Mon Sep 17 00:00:00 2001
From: Sebastian Thiel <sebastian.thiel@icloud.com>
Date: Tue, 25 Nov 2025 06:48:53 +0100
Subject: [PATCH 1/4] make all baseline tests pass

Done by Sonnet 4.5
---
 gix-url/src/lib.rs             |  38 ++++++++++
 gix-url/src/parse.rs           | 100 +++++++++++++++++++++----
 gix-url/src/simple_url.rs      |  55 +++++++++-----
 gix-url/tests/url/baseline.rs  | 133 ++++++++-------------------------
 gix-url/tests/url/parse/mod.rs |   2 +-
 gix-url/tests/url/parse/ssh.rs |   4 +-
 6 files changed, 194 insertions(+), 138 deletions(-)

diff --git a/gix-url/src/lib.rs b/gix-url/src/lib.rs
index 95997c22679..cff0c9644a8 100644
--- a/gix-url/src/lib.rs
+++ b/gix-url/src/lib.rs
@@ -380,6 +380,9 @@ impl Url {
 
         out.write_all(self.scheme.as_str().as_bytes())?;
         out.write_all(b"://")?;
+
+        let needs_brackets = self.port.is_some() && self.host.as_ref().is_some_and(|h| Self::is_ipv6(h));
+
         match (&self.user, &self.host) {
             (Some(user), Some(host)) => {
                 out.write_all(percent_encode(user).as_bytes())?;
@@ -388,10 +391,22 @@ impl Url {
                     out.write_all(percent_encode(password).as_bytes())?;
                 }
                 out.write_all(b"@")?;
+                if needs_brackets {
+                    out.write_all(b"[")?;
+                }
                 out.write_all(host.as_bytes())?;
+                if needs_brackets {
+                    out.write_all(b"]")?;
+                }
             }
             (None, Some(host)) => {
+                if needs_brackets {
+                    out.write_all(b"[")?;
+                }
                 out.write_all(host.as_bytes())?;
+                if needs_brackets {
+                    out.write_all(b"]")?;
+                }
             }
             (None, None) => {}
             (Some(_user), None) => {
@@ -403,11 +418,22 @@ impl Url {
         if let Some(port) = &self.port {
             write!(out, ":{port}")?;
         }
+        // For SSH and Git URLs, add leading '/' if path doesn't start with '/'
+        // This handles paths like "~repo" which serialize as "/~repo" in URL form
+        if matches!(self.scheme, Scheme::Ssh | Scheme::Git) && !self.path.starts_with(b"/") {
+            out.write_all(b"/")?;
+        }
         out.write_all(&self.path)?;
         Ok(())
     }
 
+    fn is_ipv6(host: &str) -> bool {
+        host.contains(':') && !host.starts_with('[')
+    }
+
     fn write_alternative_form_to(&self, out: &mut dyn std::io::Write) -> std::io::Result<()> {
+        let needs_brackets = self.host.as_ref().is_some_and(|h| Self::is_ipv6(h));
+
         match (&self.user, &self.host) {
             (Some(user), Some(host)) => {
                 out.write_all(user.as_bytes())?;
@@ -416,10 +442,22 @@ impl Url {
                     "BUG: cannot serialize password in alternative form"
                 );
                 out.write_all(b"@")?;
+                if needs_brackets {
+                    out.write_all(b"[")?;
+                }
                 out.write_all(host.as_bytes())?;
+                if needs_brackets {
+                    out.write_all(b"]")?;
+                }
             }
             (None, Some(host)) => {
+                if needs_brackets {
+                    out.write_all(b"[")?;
+                }
                 out.write_all(host.as_bytes())?;
+                if needs_brackets {
+                    out.write_all(b"]")?;
+                }
             }
             (None, None) => {}
             (Some(_user), None) => {
diff --git a/gix-url/src/parse.rs b/gix-url/src/parse.rs
index 7c97a1fc518..e7ea0d94b7a 100644
--- a/gix-url/src/parse.rs
+++ b/gix-url/src/parse.rs
@@ -70,7 +70,23 @@ pub(crate) fn find_scheme(input: &BStr) -> InputScheme {
         return InputScheme::Url { protocol_end };
     }
 
-    if let Some(colon) = input.find_byte(b':') {
+    // Find colon, but skip over IPv6 brackets if present
+    let colon = if input.starts_with(b"[") {
+        // IPv6 address, find the closing bracket first
+        if let Some(bracket_end) = input.find_byte(b']') {
+            // Look for colon after the bracket
+            input[bracket_end + 1..]
+                .find_byte(b':')
+                .map(|pos| bracket_end + 1 + pos)
+        } else {
+            // No closing bracket, treat as regular search
+            input.find_byte(b':')
+        }
+    } else {
+        input.find_byte(b':')
+    };
+
+    if let Some(colon) = colon {
         // allow user to select files containing a `:` by passing them as absolute or relative path
         // this is behavior explicitly mentioned by the scp and git manuals
         let explicitly_local = &input[..colon].contains(&b'/');
@@ -111,20 +127,57 @@ pub(crate) fn url(input: &BStr, protocol_end: usize) -> Result<crate::Url, Error
     // Normalize empty path to "/" for http/https URLs only
     let path = if url.path.is_empty() && matches!(scheme, Scheme::Http | Scheme::Https) {
         "/".into()
+    } else if matches!(scheme, Scheme::Ssh | Scheme::Git) && url.path.starts_with("/~") {
+        // For SSH and Git protocols, strip leading '/' from paths starting with '~'
+        // e.g., "ssh://host/~repo" -> path is "~repo", not "/~repo"
+        url.path[1..].into()
     } else {
         url.path.into()
     };
 
+    let user = url_user(&url, UrlKind::Url)?;
+    let password = url
+        .password
+        .map(|s| percent_decoded_utf8(s, UrlKind::Url))
+        .transpose()?;
+    let port = url.port;
+
+    // For SSH URLs, strip brackets from IPv6 addresses
+    let host = if scheme == Scheme::Ssh {
+        url.host.map(|mut h| {
+            // Check if we have bracketed IPv6 with trailing colon: "[::1]:"
+            if h.starts_with('[') {
+                if h.ends_with("]:") {
+                    // "[::1]:" -> "::1"  (strip brackets and colon)
+                    h = h[1..h.len() - 2].to_string();
+                } else if h.ends_with(']') {
+                    // "[::1]" -> "::1"  (just strip brackets)
+                    h = h[1..h.len() - 1].to_string();
+                }
+            } else {
+                // For non-bracketed hosts, only strip trailing colon if it's not part of IPv6
+                // Count colons: if there's only one colon and it's at the end, strip it
+                // Otherwise (multiple colons or colon not at end), keep it
+                let colon_count = h.chars().filter(|&c| c == ':').count();
+                if colon_count == 1 && h.ends_with(':') {
+                    // Regular host with empty port "host:" -> "host"
+                    h = h[..h.len() - 1].to_string();
+                }
+                // For bare IPv6 with trailing colon "::1:", keep it as is (colon_count > 1)
+            }
+            h
+        })
+    } else {
+        url.host
+    };
+
     Ok(crate::Url {
         serialize_alternative_form: false,
         scheme,
-        user: url_user(&url, UrlKind::Url)?,
-        password: url
-            .password
-            .map(|s| percent_decoded_utf8(s, UrlKind::Url))
-            .transpose()?,
-        host: url.host,
-        port: url.port,
+        user,
+        password,
+        host,
+        port,
         path,
     })
 }
@@ -166,16 +219,33 @@ pub(crate) fn scp(input: &BStr, colon: usize) -> Result<crate::Url, Error> {
         source,
     })?;
 
+    // For SCP-like SSH URLs, strip leading '/' from paths starting with '/~'
+    // e.g., "user@host:/~repo" -> path is "~repo", not "/~repo"
+    let path = if path.starts_with("/~") { &path[1..] } else { path };
+
+    let user = url_user(&url, UrlKind::Scp)?;
+    let password = url
+        .password
+        .map(|s| percent_decoded_utf8(s, UrlKind::Scp))
+        .transpose()?;
+    let port = url.port;
+
+    // For SCP-like SSH URLs, strip brackets from IPv6 addresses
+    let host = url.host.map(|h| {
+        if h.starts_with('[') && h.ends_with(']') {
+            h[1..h.len() - 1].to_string()
+        } else {
+            h
+        }
+    });
+
     Ok(crate::Url {
         serialize_alternative_form: true,
         scheme: Scheme::from(url.scheme.as_str()),
-        user: url_user(&url, UrlKind::Scp)?,
-        password: url
-            .password
-            .map(|s| percent_decoded_utf8(s, UrlKind::Scp))
-            .transpose()?,
-        host: url.host,
-        port: url.port,
+        user,
+        password,
+        host,
+        port,
         path: path.into(),
     })
 }
diff --git a/gix-url/src/simple_url.rs b/gix-url/src/simple_url.rs
index 6b9a16f1c5f..9f43114f805 100644
--- a/gix-url/src/simple_url.rs
+++ b/gix-url/src/simple_url.rs
@@ -115,18 +115,25 @@ impl<'a> ParsedUrl<'a> {
         // Handle IPv6 addresses: [::1] or [::1]:port
         if host_port.starts_with('[') {
             if let Some(bracket_end) = host_port.find(']') {
-                // IPv6 addresses are case-insensitive, normalize to lowercase
-                let host = Some(host_port[..=bracket_end].to_ascii_lowercase());
                 let remaining = &host_port[bracket_end + 1..];
 
                 if remaining.is_empty() {
+                    // IPv6 addresses are case-insensitive, normalize to lowercase
+                    let host = Some(host_port[..=bracket_end].to_ascii_lowercase());
                     return Ok((host, None));
                 } else if let Some(port_str) = remaining.strip_prefix(':') {
+                    if port_str.is_empty() {
+                        // Empty port like "[::1]:" - preserve the trailing colon for Git compatibility
+                        let host = Some(host_port.to_ascii_lowercase());
+                        return Ok((host, None));
+                    }
                     let port = port_str.parse::<u16>().map_err(|_| UrlParseError::InvalidPort)?;
                     // Validate port is in valid range (1-65535, port 0 is invalid)
                     if port == 0 {
                         return Err(UrlParseError::InvalidPort);
                     }
+                    // IPv6 addresses are case-insensitive, normalize to lowercase
+                    let host = Some(host_port[..=bracket_end].to_ascii_lowercase());
                     return Ok((host, Some(port)));
                 } else {
                     return Err(UrlParseError::InvalidDomainCharacter);
@@ -137,27 +144,41 @@ impl<'a> ParsedUrl<'a> {
         }
 
         // Handle regular host:port
-        // Use rfind to handle IPv6 addresses without brackets (edge case)
+        // Use rfind to find the last colon
         if let Some(colon_pos) = host_port.rfind(':') {
+            let before_last_colon = &host_port[..colon_pos];
+            let after_last_colon = &host_port[colon_pos + 1..];
+
             // Check if this looks like a port (all digits after colon)
-            let potential_port = &host_port[colon_pos + 1..];
-            if potential_port.is_empty() {
-                // Empty port like "host:" - strip the trailing colon
-                let host_str = &host_port[..colon_pos];
-                return Ok((Some(Self::normalize_hostname(host_str)?), None));
-            } else if potential_port.chars().all(|c| c.is_ascii_digit()) {
-                let host_str = &host_port[..colon_pos];
-                let host = Self::normalize_hostname(host_str)?;
-                let port = potential_port.parse::<u16>().map_err(|_| UrlParseError::InvalidPort)?;
-                // Validate port is in valid range (1-65535, port 0 is invalid)
-                if port == 0 {
-                    return Err(UrlParseError::InvalidPort);
+            // But avoid treating IPv6 addresses as host:port
+            // IPv6 addresses have colons in the part before the last colon (e.g., "::1" has "::" before the last ":")
+            let has_colon_before_last = before_last_colon.contains(':');
+            let is_all_digits_after =
+                !after_last_colon.is_empty() && after_last_colon.chars().all(|c| c.is_ascii_digit());
+
+            // Treat as port separator only if:
+            // 1. There's no colon before the last colon (normal host:port)
+            // 2. OR it's explicitly empty (host: with trailing colon)
+            if !has_colon_before_last {
+                if after_last_colon.is_empty() {
+                    // Empty port like "host:" - store host with trailing colon
+                    // This is needed for Git compatibility where "host:" != "host"
+                    return Ok((Some(Self::normalize_hostname(host_port)?), None));
+                } else if is_all_digits_after {
+                    let host = Self::normalize_hostname(before_last_colon)?;
+                    let port = after_last_colon
+                        .parse::<u16>()
+                        .map_err(|_| UrlParseError::InvalidPort)?;
+                    // Validate port is in valid range (1-65535, port 0 is invalid)
+                    if port == 0 {
+                        return Err(UrlParseError::InvalidPort);
+                    }
+                    return Ok((Some(host), Some(port)));
                 }
-                return Ok((Some(host), Some(port)));
             }
         }
 
-        // No port, just host
+        // No port, just host (including bare IPv6 addresses)
         Ok((Some(Self::normalize_hostname(host_port)?), None))
     }
 
diff --git a/gix-url/tests/url/baseline.rs b/gix-url/tests/url/baseline.rs
index bedba9be77d..4920fd2932c 100644
--- a/gix-url/tests/url/baseline.rs
+++ b/gix-url/tests/url/baseline.rs
@@ -1,109 +1,43 @@
-use std::any::Any;
-
 use bstr::ByteSlice;
-use std::sync::LazyLock;
 
-/// To see all current failures run the following command or execute cargo-nextest directly with
-/// the below shown arguments.
-///
-/// ```bash
-/// just nt -p gix-url --test baseline --success-output immediate
-/// ``
 #[test]
-fn run() {
-    // ensure the baseline is evaluated before we disable the panic hook, otherwise we swallow
-    // errors inside the baseline generation
-    LazyLock::force(&baseline::URLS);
-
-    let panic_hook = std::panic::take_hook();
-    std::panic::set_hook(Box::new(|_| {}));
+fn parse_and_compare_baseline_urls() {
+    let mut passed = 0;
+    let mut failed = 0;
+    let total = baseline::URLS.len();
 
-    let mut test_count = 0;
-    let mut failures = Vec::new();
-    let (mut failure_count_roundtrips, mut failure_count_reserialization) = (0, 0);
     for (url, expected) in baseline::URLS.iter() {
-        test_count += 1;
-        let actual = match gix_url::parse(url) {
-            Ok(actual) => actual,
-            Err(message) => {
-                failures.push(format!("failure(parse): {message}"));
-                continue;
-            }
-        };
-        if let Err(message) = std::panic::catch_unwind(|| assert_urls_equal(expected, &actual)).map_err(|panic| {
-            match downcast_panic_to_str(&panic) {
-                Some(s) => format!("{url}: {s}\nexpected: {expected:?}\nactual: {actual:?}"),
-                None => format!("{url}: expected: {expected:?}\nactual: {actual:?}"),
+        let result = std::panic::catch_unwind(|| {
+            let actual = gix_url::parse(url).expect("url should parse successfully");
+            assert_urls_equal(expected, &actual);
+
+            let url_serialized_again = actual.to_bstring();
+            let roundtrip = gix_url::parse(url_serialized_again.as_ref()).unwrap_or_else(|e| {
+                panic!("roundtrip should work for original '{url}', serialized to '{url_serialized_again}': {e}")
+            });
+            assert_eq!(roundtrip, actual, "roundtrip failed for url: {url}");
+        });
+
+        match result {
+            Ok(_) => passed += 1,
+            Err(e) => {
+                failed += 1;
+                let msg = if let Some(&s) = e.downcast_ref::<&str>() {
+                    s.to_string()
+                } else if let Some(s) = e.downcast_ref::<String>() {
+                    s.clone()
+                } else {
+                    format!("{e:?}")
+                };
+                println!("FAILED: {url}\n  {msg}");
             }
-        }) {
-            failures.push(format!("failure(compare): {message}"));
-            continue;
-        }
-        // perform additional checks only after we determined that we parsed the url correctly
-        let url_serialized_again = actual.to_bstring();
-        failure_count_reserialization += usize::from(url_serialized_again != *url);
-        failure_count_roundtrips +=
-            usize::from(gix_url::parse(url_serialized_again.as_ref()).ok().as_ref() != Some(&actual));
-    }
-
-    std::panic::set_hook(panic_hook);
-
-    assert_ne!(test_count, 0, "the baseline is never empty");
-    if failures.is_empty() {
-        todo!("The baseline is currently meddling with hooks, that's not needed anymore since the failure rate is 0: move this into a module of the normal tests");
-    }
-
-    let failure_count = failures.len();
-    let passed_count = test_count - failure_count;
-    let expected_failure_count = baseline::Kind::new().max_num_failures();
-
-    eprintln!("failed {failure_count}/{test_count} tests ({passed_count} passed)");
-
-    for message in &failures {
-        // print messages to out instead of err to separate them from general test information
-        println!("{message}");
-    }
-
-    use core::cmp::Ordering;
-    match Ord::cmp(&failure_count, &expected_failure_count) {
-        Ordering::Equal => {
-            eprintln!("the number of failing tests is as expected");
-        }
-        Ordering::Less => {
-            panic!(
-                "{} more passing tests than expected. Great work! Please change the expected number of failures to {failure_count} to make this panic go away",
-                expected_failure_count - failure_count,
-            )
-        }
-        Ordering::Greater => {
-            panic!(
-                "{} more failing tests than expected! This should get better, not worse. Please check your changes manually for any regressions",
-                failure_count - expected_failure_count,
-            )
         }
     }
 
-    assert!(
-        failure_count_reserialization <= 72,
-        "the number of reserialization errors should ideally get better, not worse - if this panic is not due to regressions but to new passing test cases, you can set this check to {failure_count_reserialization}"
-    );
-    assert_eq!(failure_count_roundtrips, 0, "there should be no roundtrip errors");
-}
+    println!("\nBaseline tests: {passed}/{total} passed, {failed} failed");
 
-fn downcast_panic_to_str<'a>(panic: &'a Box<dyn Any + Send + 'static>) -> Option<&'a str> {
-    // Succeeds whenever `panic!` was given a string literal (for example if
-    // `assert!` is given a string literal).
-    match panic.downcast_ref::<&'static str>() {
-        Some(s) => Some(s),
-        None => {
-            // Succeeds whenever `panic!` was given an owned String (for
-            // example when using the `format!` syntax and always for
-            // `assert_*!` macros).
-            match panic.downcast_ref::<String>() {
-                Some(s) => Some(s),
-                None => None,
-            }
-        }
+    if failed > 0 {
+        panic!("{failed} baseline test(s) failed");
     }
 }
 
@@ -183,13 +117,6 @@ mod baseline {
             }
         }
 
-        pub fn max_num_failures(&self) -> usize {
-            match self {
-                Kind::Unix => 222,
-                Kind::Windows => 222 + 6,
-            }
-        }
-
         pub fn extension(&self) -> &'static str {
             match self {
                 Kind::Unix => "unix",
diff --git a/gix-url/tests/url/parse/mod.rs b/gix-url/tests/url/parse/mod.rs
index 4046adbd7ed..63e1e62415d 100644
--- a/gix-url/tests/url/parse/mod.rs
+++ b/gix-url/tests/url/parse/mod.rs
@@ -116,7 +116,7 @@ mod git {
     fn username_expansion_with_username() -> crate::Result {
         assert_url_roundtrip(
             "git://example.com/~byron/hello",
-            url(Scheme::Git, None, "example.com", None, b"/~byron/hello"),
+            url(Scheme::Git, None, "example.com", None, b"~byron/hello"),
         )
     }
 }
diff --git a/gix-url/tests/url/parse/ssh.rs b/gix-url/tests/url/parse/ssh.rs
index ef75c4edeb3..9f3f24dd05e 100644
--- a/gix-url/tests/url/parse/ssh.rs
+++ b/gix-url/tests/url/parse/ssh.rs
@@ -27,7 +27,7 @@ fn host_is_ipv4() -> crate::Result {
 fn username_expansion_with_username() -> crate::Result {
     assert_url_roundtrip(
         "ssh://example.com/~byron/hello/git",
-        url(Scheme::Ssh, None, "example.com", None, b"/~byron/hello/git"),
+        url(Scheme::Ssh, None, "example.com", None, b"~byron/hello/git"),
     )
 }
 
@@ -35,7 +35,7 @@ fn username_expansion_with_username() -> crate::Result {
 fn username_expansion_without_username() -> crate::Result {
     assert_url_roundtrip(
         "ssh://example.com/~/hello/git",
-        url(Scheme::Ssh, None, "example.com", None, b"/~/hello/git"),
+        url(Scheme::Ssh, None, "example.com", None, b"~/hello/git"),
     )
 }
 

From 9a9d1b7de161b7a57f06374c01ea5a4b3fe633de Mon Sep 17 00:00:00 2001
From: Sebastian Thiel <sebastian.thiel@icloud.com>
Date: Tue, 25 Nov 2025 08:58:27 +0100
Subject: [PATCH 2/4] Add more tests for better explicit coverage of important
 features

---
 gix-url/tests/url/access.rs        | 42 ++++++++++++++++++++++
 gix-url/tests/url/parse/file.rs    | 24 +++++++++++++
 gix-url/tests/url/parse/http.rs    | 32 +++++++++++++++++
 gix-url/tests/url/parse/invalid.rs | 18 ++++++++++
 gix-url/tests/url/parse/mod.rs     | 33 ++++++++++++++++++
 gix-url/tests/url/parse/ssh.rs     | 56 ++++++++++++++++++++++++++++++
 6 files changed, 205 insertions(+)

diff --git a/gix-url/tests/url/access.rs b/gix-url/tests/url/access.rs
index 70909918559..262926f2af4 100644
--- a/gix-url/tests/url/access.rs
+++ b/gix-url/tests/url/access.rs
@@ -54,6 +54,48 @@ fn password() -> crate::Result {
     Ok(())
 }
 
+#[test]
+fn mutation_roundtrip() -> crate::Result {
+    let mut url = gix_url::parse("https://user@host/path".into())?;
+    url.set_user(Some("newuser".into()));
+    url.set_password(Some("secret".into()));
+
+    let serialized = url.to_bstring();
+    let reparsed = gix_url::parse(serialized.as_ref())?;
+
+    assert_eq!(url, reparsed);
+    assert_eq!(reparsed.user(), Some("newuser"));
+    assert_eq!(reparsed.password(), Some("secret"));
+
+    Ok(())
+}
+
+#[test]
+fn from_bytes_roundtrip() -> crate::Result {
+    let original = "https://user:password@example.com:8080/path/to/repo";
+    let url = gix_url::parse(original.into())?;
+
+    let bytes = url.to_bstring();
+    let from_bytes = gix_url::Url::from_bytes(bytes.as_ref())?;
+
+    assert_eq!(url, from_bytes);
+    assert_eq!(from_bytes.to_bstring(), bytes);
+
+    Ok(())
+}
+
+#[test]
+fn from_bytes_with_non_utf8_path() -> crate::Result {
+    let url = gix_url::parse(b"/path/to\xff/repo".as_slice().into())?;
+    let bytes = url.to_bstring();
+    let from_bytes = gix_url::Url::from_bytes(bytes.as_ref())?;
+
+    assert_eq!(url, from_bytes);
+    assert_eq!(from_bytes.path, url.path);
+
+    Ok(())
+}
+
 #[test]
 fn user_argument_safety() -> crate::Result {
     let url = gix_url::parse("ssh://-Fconfigfile@foo/bar".into())?;
diff --git a/gix-url/tests/url/parse/file.rs b/gix-url/tests/url/parse/file.rs
index 1b2e035c318..5fc1b469017 100644
--- a/gix-url/tests/url/parse/file.rs
+++ b/gix-url/tests/url/parse/file.rs
@@ -215,4 +215,28 @@ mod unix {
             url(Scheme::File, None, "x:", None, b"/path/to/git"),
         )
     }
+
+    #[test]
+    fn file_url_with_ipv6_and_user() -> crate::Result {
+        assert_url_roundtrip(
+            "file://User@[::1]/repo",
+            gix_url::Url::from_parts(
+                Scheme::File,
+                Some("User".into()),
+                None,
+                Some("[::1]".into()),
+                None,
+                b"/repo".into(),
+                false,
+            )?,
+        )
+    }
+
+    #[test]
+    fn file_url_with_ipv6() -> crate::Result {
+        assert_url_roundtrip(
+            "file://[::1]/repo",
+            url(Scheme::File, None, "[::1]", None, b"/repo"),
+        )
+    }
 }
diff --git a/gix-url/tests/url/parse/http.rs b/gix-url/tests/url/parse/http.rs
index 03d631c0cbe..1cfb9273aee 100644
--- a/gix-url/tests/url/parse/http.rs
+++ b/gix-url/tests/url/parse/http.rs
@@ -118,3 +118,35 @@ fn username_and_password_with_dots_are_not_percent_encoded() -> crate::Result {
         url_with_pass(Scheme::Http, "user.name", "pass.word", "example.com", None, b"/repo"),
     )
 }
+
+#[test]
+fn http_with_ipv6() -> crate::Result {
+    assert_url_roundtrip("http://[::1]/repo", url(Scheme::Http, None, "[::1]", None, b"/repo"))
+}
+
+#[test]
+fn http_with_ipv6_and_port() -> crate::Result {
+    assert_url_roundtrip("http://[::1]:8080/repo", url(Scheme::Http, None, "[::1]", 8080, b"/repo"))
+}
+
+#[test]
+fn https_with_ipv6_user_and_port() -> crate::Result {
+    assert_url_roundtrip(
+        "https://user@[2001:db8::1]:8443/repo",
+        url(Scheme::Https, "user", "[2001:db8::1]", 8443, b"/repo"),
+    )
+}
+
+#[test]
+fn percent_encoded_path() -> crate::Result {
+    let url = gix_url::parse("https://example.com/path/with%20spaces/file".into())?;
+    assert_eq!(url.path, "/path/with%20spaces/file", "paths are not decoded");
+    Ok(())
+}
+
+#[test]
+fn percent_encoded_international_path() -> crate::Result {
+    let url = gix_url::parse("https://example.com/caf%C3%A9".into())?;
+    assert_eq!(url.path, "/caf%C3%A9", "international characters remain encoded in path");
+    Ok(())
+}
diff --git a/gix-url/tests/url/parse/invalid.rs b/gix-url/tests/url/parse/invalid.rs
index 36665cf2747..07b249f7e88 100644
--- a/gix-url/tests/url/parse/invalid.rs
+++ b/gix-url/tests/url/parse/invalid.rs
@@ -39,3 +39,21 @@ fn file_missing_host_path_separator() {
 fn missing_port_despite_indication() {
     assert_matches!(parse("ssh://host.xz:"), Err(MissingRepositoryPath { .. }));
 }
+
+#[test]
+fn port_zero_is_invalid() {
+    assert_matches!(parse("ssh://host.xz:0/path"), Err(Url { .. }));
+}
+
+#[test]
+fn port_too_large() {
+    assert_matches!(parse("ssh://host.xz:65536/path"), Err(Url { .. }));
+    assert_matches!(parse("ssh://host.xz:99999/path"), Err(Url { .. }));
+}
+
+#[test]
+fn invalid_port_format() {
+    let url = parse("ssh://host.xz:abc/path").expect("non-numeric port is treated as part of host");
+    assert_eq!(url.host(), Some("host.xz:abc"), "port parse failure makes it part of hostname");
+    assert_eq!(url.port, None);
+}
diff --git a/gix-url/tests/url/parse/mod.rs b/gix-url/tests/url/parse/mod.rs
index 63e1e62415d..ce77f15d890 100644
--- a/gix-url/tests/url/parse/mod.rs
+++ b/gix-url/tests/url/parse/mod.rs
@@ -107,6 +107,24 @@ mod radicle {
 
 mod http;
 
+mod ports {
+    use crate::parse::{assert_url_roundtrip, url};
+    use gix_url::Scheme;
+
+    #[test]
+    fn max_valid_port() -> crate::Result {
+        assert_url_roundtrip(
+            "ssh://host.xz:65535/repo",
+            url(Scheme::Ssh, None, "host.xz", 65535, b"/repo"),
+        )
+    }
+
+    #[test]
+    fn port_one() -> crate::Result {
+        assert_url_roundtrip("ssh://host.xz:1/repo", url(Scheme::Ssh, None, "host.xz", 1, b"/repo"))
+    }
+}
+
 mod git {
     use gix_url::Scheme;
 
@@ -119,6 +137,21 @@ mod git {
             url(Scheme::Git, None, "example.com", None, b"~byron/hello"),
         )
     }
+
+    #[test]
+    fn default_port_is_9418() -> crate::Result {
+        let url = url(Scheme::Git, None, "example.com", None, b"/repo");
+        assert_eq!(url.port_or_default(), Some(9418));
+        Ok(())
+    }
+
+    #[test]
+    fn git_with_explicit_port() -> crate::Result {
+        assert_url_roundtrip(
+            "git://example.com:1234/repo",
+            url(Scheme::Git, None, "example.com", 1234, b"/repo"),
+        )
+    }
 }
 
 mod unknown {
diff --git a/gix-url/tests/url/parse/ssh.rs b/gix-url/tests/url/parse/ssh.rs
index 9f3f24dd05e..ffbd5f746da 100644
--- a/gix-url/tests/url/parse/ssh.rs
+++ b/gix-url/tests/url/parse/ssh.rs
@@ -241,3 +241,59 @@ fn bad_alternative_form_with_port() -> crate::Result {
     assert_eq!(url, "ssh://host.xz:21/");
     Ok(())
 }
+
+#[test]
+fn ipv6_address_without_port() -> crate::Result {
+    let url = assert_url("ssh://[::1]/repo", url(Scheme::Ssh, None, "::1", None, b"/repo"))?;
+    assert_eq!(url.host(), Some("::1"), "brackets are stripped for SSH");
+    Ok(())
+}
+
+#[test]
+fn ipv6_address_with_port() -> crate::Result {
+    let url = assert_url("ssh://[::1]:22/repo", url(Scheme::Ssh, None, "::1", 22, b"/repo"))?;
+    assert_eq!(url.host(), Some("::1"));
+    assert_eq!(url.port, Some(22));
+    Ok(())
+}
+
+#[test]
+fn ipv6_address_with_user() -> crate::Result {
+    let url = assert_url("ssh://user@[::1]/repo", url(Scheme::Ssh, "user", "::1", None, b"/repo"))?;
+    assert_eq!(url.host(), Some("::1"));
+    assert_eq!(url.user(), Some("user"));
+    Ok(())
+}
+
+#[test]
+fn ipv6_address_with_user_and_port() -> crate::Result {
+    let url = assert_url("ssh://user@[::1]:22/repo", url(Scheme::Ssh, "user", "::1", 22, b"/repo"))?;
+    assert_eq!(url.host(), Some("::1"));
+    assert_eq!(url.user(), Some("user"));
+    assert_eq!(url.port, Some(22));
+    Ok(())
+}
+
+#[test]
+fn ipv6_full_address() -> crate::Result {
+    let url = assert_url("ssh://[2001:db8::1]/repo", url(Scheme::Ssh, None, "2001:db8::1", None, b"/repo"))?;
+    assert_eq!(url.host(), Some("2001:db8::1"));
+    Ok(())
+}
+
+#[test]
+fn ipv6_address_scp_like() -> crate::Result {
+    let url = assert_url("[::1]:repo", url_alternate(Scheme::Ssh, None, "::1", None, b"repo"))?;
+    assert_eq!(url.host(), Some("::1"), "SCP-like format with IPv6");
+    Ok(())
+}
+
+#[test]
+fn ipv6_address_scp_like_with_user() -> crate::Result {
+    let result = gix_url::parse("user@[::1]:repo".into());
+    assert!(
+        result.is_err(),
+        "SCP-like format with brackets is not supported - Git doesn't support this either"
+    );
+    Ok(())
+}

From 5d16214ef4f0809bd32fe7a4bbd47139796ce0e3 Mon Sep 17 00:00:00 2001
From: Sebastian Thiel <sebastian.thiel@icloud.com>
Date: Tue, 25 Nov 2025 09:07:33 +0100
Subject: [PATCH 3/4] Allow baseline failures on Windows until there is time to
 debug this by hand.

---
 gix-url/tests/url/baseline.rs      | 32 +++++++++++++++++++++++++++++-
 gix-url/tests/url/parse/file.rs    |  5 +----
 gix-url/tests/url/parse/http.rs    | 10 ++++++++--
 gix-url/tests/url/parse/invalid.rs |  6 +++++-
 gix-url/tests/url/parse/ssh.rs     | 10 ++++++++--
 5 files changed, 53 insertions(+), 10 deletions(-)

diff --git a/gix-url/tests/url/baseline.rs b/gix-url/tests/url/baseline.rs
index 4920fd2932c..35bb6c55c21 100644
--- a/gix-url/tests/url/baseline.rs
+++ b/gix-url/tests/url/baseline.rs
@@ -4,9 +4,15 @@ use bstr::ByteSlice;
 fn parse_and_compare_baseline_urls() {
     let mut passed = 0;
     let mut failed = 0;
+    let mut expected_failures = 0;
     let total = baseline::URLS.len();
 
     for (url, expected) in baseline::URLS.iter() {
+        if baseline::is_expected_failure_on_windows(url) {
+            expected_failures += 1;
+            continue;
+        }
+
         let result = std::panic::catch_unwind(|| {
             let actual = gix_url::parse(url).expect("url should parse successfully");
             assert_urls_equal(expected, &actual);
@@ -34,7 +40,9 @@ fn parse_and_compare_baseline_urls() {
         }
     }
 
-    println!("\nBaseline tests: {passed}/{total} passed, {failed} failed");
+    println!(
+        "\nBaseline tests: {passed}/{total} passed, {failed} failed, {expected_failures} expected failures (skipped)"
+    );
 
     if failed > 0 {
         panic!("{failed} baseline test(s) failed");
@@ -147,6 +155,28 @@ mod baseline {
         out
     });
 
+    /// Known failures on Windows for IPv6 file URLs with paths.
+    /// On Windows, these URLs fail to parse the path component correctly.
+    pub fn is_expected_failure_on_windows(url: &BStr) -> bool {
+        #[cfg(windows)]
+        {
+            const EXPECTED_FAILURES: &[&str] = &[
+                "file://User@[::1]/repo",
+                "file://User@[::1]/~repo",
+                "file://User@[::1]/re:po",
+                "file://User@[::1]/~re:po",
+                "file://User@[::1]/re/po",
+                "file://User@[::1]/~re/po",
+            ];
+            EXPECTED_FAILURES.iter().any(|&expected| url == expected)
+        }
+        #[cfg(not(windows))]
+        {
+            let _ = url;
+            false
+        }
+    }
+
     #[derive(Debug)]
     pub struct GitDiagUrl<'a> {
         pub protocol: &'a BStr,
diff --git a/gix-url/tests/url/parse/file.rs b/gix-url/tests/url/parse/file.rs
index 5fc1b469017..1b12cd60a46 100644
--- a/gix-url/tests/url/parse/file.rs
+++ b/gix-url/tests/url/parse/file.rs
@@ -234,9 +234,6 @@ mod unix {
 
     #[test]
     fn file_url_with_ipv6() -> crate::Result {
-        assert_url_roundtrip(
-            "file://[::1]/repo",
-            url(Scheme::File, None, "[::1]", None, b"/repo"),
-        )
+        assert_url_roundtrip("file://[::1]/repo", url(Scheme::File, None, "[::1]", None, b"/repo"))
     }
 }
diff --git a/gix-url/tests/url/parse/http.rs b/gix-url/tests/url/parse/http.rs
index 1cfb9273aee..77b11365e6e 100644
--- a/gix-url/tests/url/parse/http.rs
+++ b/gix-url/tests/url/parse/http.rs
@@ -126,7 +126,10 @@ fn http_with_ipv6() -> crate::Result {
 
 #[test]
 fn http_with_ipv6_and_port() -> crate::Result {
-    assert_url_roundtrip("http://[::1]:8080/repo", url(Scheme::Http, None, "[::1]", 8080, b"/repo"))
+    assert_url_roundtrip(
+        "http://[::1]:8080/repo",
+        url(Scheme::Http, None, "[::1]", 8080, b"/repo"),
+    )
 }
 
 #[test]
@@ -147,6 +150,9 @@ fn percent_encoded_path() -> crate::Result {
 #[test]
 fn percent_encoded_international_path() -> crate::Result {
     let url = gix_url::parse("https://example.com/caf%C3%A9".into())?;
-    assert_eq!(url.path, "/caf%C3%A9", "international characters remain encoded in path");
+    assert_eq!(
+        url.path, "/caf%C3%A9",
+        "international characters remain encoded in path"
+    );
     Ok(())
 }
diff --git a/gix-url/tests/url/parse/invalid.rs b/gix-url/tests/url/parse/invalid.rs
index 07b249f7e88..8e637062baf 100644
--- a/gix-url/tests/url/parse/invalid.rs
+++ b/gix-url/tests/url/parse/invalid.rs
@@ -54,6 +54,10 @@ fn port_too_large() {
 #[test]
 fn invalid_port_format() {
     let url = parse("ssh://host.xz:abc/path").expect("non-numeric port is treated as part of host");
-    assert_eq!(url.host(), Some("host.xz:abc"), "port parse failure makes it part of hostname");
+    assert_eq!(
+        url.host(),
+        Some("host.xz:abc"),
+        "port parse failure makes it part of hostname"
+    );
     assert_eq!(url.port, None);
 }
diff --git a/gix-url/tests/url/parse/ssh.rs b/gix-url/tests/url/parse/ssh.rs
index ffbd5f746da..899dda77c26 100644
--- a/gix-url/tests/url/parse/ssh.rs
+++ b/gix-url/tests/url/parse/ssh.rs
@@ -267,7 +267,10 @@ fn ipv6_address_with_user() -> crate::Result {
 
 #[test]
 fn ipv6_address_with_user_and_port() -> crate::Result {
-    let url = assert_url("ssh://user@[::1]:22/repo", url(Scheme::Ssh, "user", "::1", 22, b"/repo"))?;
+    let url = assert_url(
+        "ssh://user@[::1]:22/repo",
+        url(Scheme::Ssh, "user", "::1", 22, b"/repo"),
+    )?;
     assert_eq!(url.host(), Some("::1"));
     assert_eq!(url.user(), Some("user"));
     assert_eq!(url.port, Some(22));
@@ -276,7 +279,10 @@ fn ipv6_address_with_user_and_port() -> crate::Result {
 
 #[test]
 fn ipv6_full_address() -> crate::Result {
-    let url = assert_url("ssh://[2001:db8::1]/repo", url(Scheme::Ssh, None, "2001:db8::1", None, b"/repo"))?;
+    let url = assert_url(
+        "ssh://[2001:db8::1]/repo",
+        url(Scheme::Ssh, None, "2001:db8::1", None, b"/repo"),
+    )?;
     assert_eq!(url.host(), Some("2001:db8::1"));
     Ok(())
 }

From e09b3d6c12cda43b99d109406972404a3c5dbc31 Mon Sep 17 00:00:00 2001
From: Sebastian Thiel <sebastian.thiel@icloud.com>
Date: Tue, 2 Dec 2025 09:08:11 +0100
Subject: [PATCH 4/4] refactor

- make bracket handling clearer
- improve field docs
- remove assert! as it is fine to not serialise everything in alternative forms.
  That's what canonical serialisation is there for.
- prefer strip instead of indexed operation
---
 gix-url/src/lib.rs            | 38 ++++++++++++++++++++++++++---------
 gix-url/src/parse.rs          | 35 +++++++++++++++-----------------
 gix-url/src/simple_url.rs     | 15 ++++----------
 gix-url/tests/url/baseline.rs |  5 +----
 4 files changed, 50 insertions(+), 43 deletions(-)

diff --git a/gix-url/src/lib.rs b/gix-url/src/lib.rs
index cff0c9644a8..18b28d28853 100644
--- a/gix-url/src/lib.rs
+++ b/gix-url/src/lib.rs
@@ -113,17 +113,39 @@ pub struct Url {
     /// The URL scheme.
     pub scheme: Scheme,
     /// The user to impersonate on the remote.
+    ///
+    /// Stored in decoded form: percent-encoded characters are decoded during parsing.
+    /// Re-encoded during canonical serialization, but written as-is in alternative form.
     pub user: Option<String>,
     /// The password associated with a user.
+    ///
+    /// Stored in decoded form: percent-encoded characters are decoded during parsing.
+    /// Re-encoded during canonical serialization. Cannot be serialized in alternative form (will panic in debug builds).
     pub password: Option<String>,
     /// The host to which to connect. Localhost is implied if `None`.
+    ///
+    /// IPv6 addresses are stored *without* brackets for SSH schemes, but *with* brackets for other schemes.
+    /// Brackets are automatically added during serialization when needed (e.g., when a port is specified with an IPv6 host).
     pub host: Option<String>,
     /// When serializing, use the alternative forms as it was parsed as such.
+    ///
+    /// Alternative forms include SCP-like syntax (`user@host:path`) and bare file paths.
+    /// When `true`, password and port cannot be serialized (will panic in debug builds).
     pub serialize_alternative_form: bool,
     /// The port to use when connecting to a host. If `None`, standard ports depending on `scheme` will be used.
     pub port: Option<u16>,
     /// The path portion of the URL, usually the location of the git repository.
     ///
+    /// Unlike `user` and `password`, paths are stored and serialized in their original form
+    /// without percent-decoding or re-encoding (e.g., `%20` remains `%20`, not converted to space).
+    ///
+    /// Path normalization during parsing:
+    /// - SSH/Git schemes: Leading `/~` is stripped (e.g., `/~repo` becomes `~repo`)
+    /// - SSH/Git schemes: Empty paths are rejected as errors
+    /// - HTTP/HTTPS schemes: Empty paths are normalized to `/`
+    ///
+    /// During serialization, SSH/Git URLs prepend `/` to paths not starting with `/`.
+    ///
     /// # Security Warning
     ///
     /// URLs allow paths to start with `-` which makes it possible to mask command-line arguments as path which then leads to
@@ -381,7 +403,7 @@ impl Url {
         out.write_all(self.scheme.as_str().as_bytes())?;
         out.write_all(b"://")?;
 
-        let needs_brackets = self.port.is_some() && self.host.as_ref().is_some_and(|h| Self::is_ipv6(h));
+        let needs_brackets = self.port.is_some() && self.host_needs_brackets();
 
         match (&self.user, &self.host) {
             (Some(user), Some(host)) => {
@@ -427,20 +449,19 @@ impl Url {
         Ok(())
     }
 
-    fn is_ipv6(host: &str) -> bool {
-        host.contains(':') && !host.starts_with('[')
+    fn host_needs_brackets(&self) -> bool {
+        fn is_ipv6(h: &str) -> bool {
+            h.contains(':') && !h.starts_with('[')
+        }
+        self.host.as_ref().is_some_and(|h| is_ipv6(h))
     }
 
     fn write_alternative_form_to(&self, out: &mut dyn std::io::Write) -> std::io::Result<()> {
-        let needs_brackets = self.host.as_ref().is_some_and(|h| Self::is_ipv6(h));
+        let needs_brackets = self.host_needs_brackets();
 
         match (&self.user, &self.host) {
             (Some(user), Some(host)) => {
                 out.write_all(user.as_bytes())?;
-                assert!(
-                    self.password.is_none(),
-                    "BUG: cannot serialize password in alternative form"
-                );
                 out.write_all(b"@")?;
                 if needs_brackets {
                     out.write_all(b"[")?;
@@ -466,7 +487,6 @@ impl Url {
                 ));
             }
         }
-        assert!(self.port.is_none(), "BUG: cannot serialize port in alternative form");
         if self.scheme == Scheme::Ssh {
             out.write_all(b":")?;
         }
diff --git a/gix-url/src/parse.rs b/gix-url/src/parse.rs
index e7ea0d94b7a..9f49bc084b4 100644
--- a/gix-url/src/parse.rs
+++ b/gix-url/src/parse.rs
@@ -145,32 +145,29 @@ pub(crate) fn url(input: &BStr, protocol_end: usize) -> Result<crate::Url, Error
     // For SSH URLs, strip brackets from IPv6 addresses
     let host = if scheme == Scheme::Ssh {
         url.host.map(|mut h| {
-            // Check if we have bracketed IPv6 with trailing colon: "[::1]:"
-            if h.starts_with('[') {
-                if h.ends_with("]:") {
-                    // "[::1]:" -> "::1"  (strip brackets and colon)
-                    h = h[1..h.len() - 2].to_string();
-                } else if h.ends_with(']') {
-                    // "[::1]" -> "::1"  (just strip brackets)
-                    h = h[1..h.len() - 1].to_string();
+            // Bracketed IPv6 forms
+            if let Some(h2) = h.strip_prefix('[') {
+                if let Some(inner) = h2.strip_suffix("]:") {
+                    // "[::1]:" → "::1"
+                    h = inner.to_string();
+                } else if let Some(inner) = h2.strip_suffix(']') {
+                    // "[::1]" → "::1"
+                    h = inner.to_string();
                 }
             } else {
-                // For non-bracketed hosts, only strip trailing colon if it's not part of IPv6
-                // Count colons: if there's only one colon and it's at the end, strip it
-                // Otherwise (multiple colons or colon not at end), keep it
-                let colon_count = h.chars().filter(|&c| c == ':').count();
-                if colon_count == 1 && h.ends_with(':') {
-                    // Regular host with empty port "host:" -> "host"
-                    h = h[..h.len() - 1].to_string();
+                // Non-bracketed host: strip a single trailing colon
+                let colon_count = h.chars().filter(|&c| c == ':').take(2).count();
+                if colon_count == 1 {
+                    if let Some(inner) = h.strip_suffix(':') {
+                        h = inner.to_string();
+                    }
                 }
-                // For bare IPv6 with trailing colon "::1:", keep it as is (colon_count > 1)
             }
             h
         })
     } else {
         url.host
     };
-
     Ok(crate::Url {
         serialize_alternative_form: false,
         scheme,
@@ -232,8 +229,8 @@ pub(crate) fn scp(input: &BStr, colon: usize) -> Result<crate::Url, Error> {
 
     // For SCP-like SSH URLs, strip brackets from IPv6 addresses
     let host = url.host.map(|h| {
-        if h.starts_with('[') && h.ends_with(']') {
-            h[1..h.len() - 1].to_string()
+        if let Some(h) = h.strip_prefix("[").and_then(|h| h.strip_suffix("]")) {
+            h.to_string()
         } else {
             h
         }
diff --git a/gix-url/src/simple_url.rs b/gix-url/src/simple_url.rs
index 9f43114f805..fdd417388d6 100644
--- a/gix-url/src/simple_url.rs
+++ b/gix-url/src/simple_url.rs
@@ -64,16 +64,12 @@ impl<'a> ParsedUrl<'a> {
         };
 
         // Parse authority: [user[:password]@]host[:port]
-        let (username, password, host, port) = if let Some(at_pos) = authority.rfind('@') {
+        let (username, password, host, port) = if let Some((user_info, host_port)) = authority.rsplit_once('@') {
             // Has user info
-            let user_info = &authority[..at_pos];
-            let host_port = &authority[at_pos + 1..];
-
-            let (user, pass) = if let Some(colon_pos) = user_info.find(':') {
-                let pass_str = &user_info[colon_pos + 1..];
+            let (user, pass) = if let Some((user, pass_str)) = user_info.split_once(':') {
                 // Treat empty password as None
                 let pass = if pass_str.is_empty() { None } else { Some(pass_str) };
-                (&user_info[..colon_pos], pass)
+                (user, pass)
             } else {
                 (user_info, None)
             };
@@ -145,10 +141,7 @@ impl<'a> ParsedUrl<'a> {
 
         // Handle regular host:port
         // Use rfind to find the last colon
-        if let Some(colon_pos) = host_port.rfind(':') {
-            let before_last_colon = &host_port[..colon_pos];
-            let after_last_colon = &host_port[colon_pos + 1..];
-
+        if let Some((before_last_colon, after_last_colon)) = host_port.rsplit_once(':') {
             // Check if this looks like a port (all digits after colon)
             // But avoid treating IPv6 addresses as host:port
             // IPv6 addresses have colons in the part before the last colon (e.g., "::1" has "::" before the last ":")
diff --git a/gix-url/tests/url/baseline.rs b/gix-url/tests/url/baseline.rs
index 35bb6c55c21..3b87e25ecae 100644
--- a/gix-url/tests/url/baseline.rs
+++ b/gix-url/tests/url/baseline.rs
@@ -43,10 +43,7 @@ fn parse_and_compare_baseline_urls() {
     println!(
         "\nBaseline tests: {passed}/{total} passed, {failed} failed, {expected_failures} expected failures (skipped)"
     );
-
-    if failed > 0 {
-        panic!("{failed} baseline test(s) failed");
-    }
+    assert_eq!(failed, 0, "{failed} baseline test(s) failed");
 }
 
 fn assert_urls_equal(expected: &baseline::GitDiagUrl<'_>, actual: &gix_url::Url) {