Add documentation with example for optional path feature

Co-authored-by: Byron <[email protected]>

Author: Copilot

gix-config-value/src/types.rs

@@ -41,6 +41,27 @@ pub struct Boolean(pub bool);
 /// Any value that can be interpreted as a path to a resource on disk.
 ///
 /// Git represents file paths as byte arrays, modeled here as owned or borrowed byte sequences.
+///
+/// ## Optional Paths
+///
+/// Paths can be marked as optional by prefixing them with `:(optional)` in the configuration.
+/// This indicates that it's acceptable if the file doesn't exist, which is useful for
+/// configuration values like `blame.ignorerevsfile` that may only exist in some repositories.
+///
+/// ```
+/// use std::borrow::Cow;
+/// use gix_config_value::Path;
+/// use bstr::ByteSlice;
+///
+/// // Regular path - file is expected to exist
+/// let path = Path::from(Cow::Borrowed(b"/etc/gitconfig".as_bstr()));
+/// assert!(!path.is_optional());
+///
+/// // Optional path - it's okay if the file doesn't exist
+/// let path = Path::from(Cow::Borrowed(b":(optional)~/.gitignore".as_bstr()));
+/// assert!(path.is_optional());
+/// assert_eq!(path.value.as_ref(), b"~/.gitignore"); // prefix is stripped
+/// ```
 #[derive(Clone, Eq, PartialEq, Ord, PartialOrd, Hash, Debug)]
 pub struct Path<'a> {
     /// The path string, un-interpolated