improve docs around worktree-filters and renormalization

Author: Byron

gix-filter/src/eol/convert_to_git.rs

@@ -57,8 +57,10 @@ pub(crate) mod function {
     /// Return `true` if `buf` was written or `false` if nothing had to be done.
     /// Depending on the state in `buf`, `index_object` is called to write the version of `src` as stored in the index
     /// into the buffer and if it is a blob, or return `Ok(None)` if no such object exists.
-    /// If renormalization is desired, let it return `Ok(None)` at all times to not let it have any influence over the
-    /// outcome of this function.
+    ///
+    /// *If renormalization is desired*, let it return `Ok(None)` at all times to not let it have any influence over the
+    /// outcome of this function. Otherwise, it will check if the in-index buffer already has newlines that it would now
+    /// want to change, and avoid doing so as what's in Git should be what's desired (except for when *renormalizing*).
     /// If `round_trip_check` is not `None`, round-tripping will be validated and handled accordingly.
     pub fn convert_to_git(
         src: &[u8],

gix-filter/src/pipeline/convert.rs

@@ -91,7 +91,7 @@ impl Pipeline {
             self.options.eol_config,
         )?;
 
-        let mut in_buffer = false;
+        let mut in_src_buffer = false;
         // this is just an approximation, but it's as good as it gets without reading the actual input.
         let would_convert_eol = eol::convert_to_git(
             b"\r\n",
@@ -119,13 +119,13 @@ impl Pipeline {
                 }
                 self.bufs.clear();
                 read.read_to_end(&mut self.bufs.src)?;
-                in_buffer = true;
+                in_src_buffer = true;
             }
         }
-        if !in_buffer && (apply_ident_filter || encoding.is_some() || would_convert_eol) {
+        if !in_src_buffer && (apply_ident_filter || encoding.is_some() || would_convert_eol) {
             self.bufs.clear();
             src.read_to_end(&mut self.bufs.src)?;
-            in_buffer = true;
+            in_src_buffer = true;
         }
 
         if let Some(encoding) = encoding {
@@ -158,7 +158,7 @@ impl Pipeline {
         if apply_ident_filter && ident::undo(&self.bufs.src, &mut self.bufs.dest)? {
             self.bufs.swap();
         }
-        Ok(if in_buffer {
+        Ok(if in_src_buffer {
             ToGitOutcome::Buffer(&self.bufs.src)
         } else {
             ToGitOutcome::Unchanged(src)