gix_filter/
lib.rs

1//! A library for implementing everything needed to deal with git filter pipelines.
2//!
3//! Generally, multiple filters are applied in a row forming a pipeline, with each filter being a stage in that pipeline.
4//! This pipeline is pre-determined with each stage being configurable.
5//!
6//! The transformation on an input buffer goes in two ways: either a filter is applied, or its effects are undone. Differentiating
7//! between these states is important to avoid comparing unfiltered buffers with filtered ones, for example.
8//!
9//! This crate implements the building blocks in terms of applying and undoing filters, along with logic to decide whether
10//! or not to apply such a filter.
11#![deny(rust_2018_idioms, missing_docs, unsafe_code)]
12
13use bstr::BString;
14/// A forwarding of the `encoding_rs` crate for its types and convenience.
15pub use encoding_rs as encoding;
16/// The `gix-attributes` crate whose types are mentioned in the public API of [Pipeline::convert_to_worktree()].
17pub use gix_attributes as attributes;
18
19/// a filter to replace `$Id$` with a git-hash of the buffer.
20pub mod ident;
21
22/// convert line endings in buffers
23pub mod eol;
24
25/// change encodings based on the `working-tree-encoding` attribute.
26pub mod worktree;
27
28/// use filter programs to perform any kind of conversion.
29pub mod driver;
30
31///
32pub mod pipeline;
33
34/// The standard git filter pipeline comprised of multiple standard filters and support for external filters.
35///
36/// It's configuring itself for each provided path based on the path's attributes, implementing the complex logic that governs it.
37#[derive(Clone)]
38pub struct Pipeline {
39    /// Various options that are all defaultable.
40    options: pipeline::Options,
41    /// Storage for the attributes of each item we should process, configured for use with all attributes that concern us.
42    attrs: gix_attributes::search::Outcome,
43    /// Additional context to pass to process filters.
44    context: pipeline::Context,
45    /// State needed to keep running filter processes.
46    processes: driver::State,
47    /// A utility to handle multiple buffers to keep results of various filters.
48    bufs: gix_utils::Buffers,
49}
50
51/// A declaration of a driver program.
52///
53/// It consists of up to three program declarations.
54#[derive(Debug, Clone)]
55pub struct Driver {
56    /// The name of the driver as stored in the configuration.
57    pub name: BString,
58
59    /// The program invocation that cleans a worktree file for storage in `git`.
60    ///
61    /// Note that the command invocation may need its `%f` argument substituted with the name of the file to process. It will be quoted.
62    pub clean: Option<BString>,
63    /// The program invocation that readies a file stored in `git` for the worktree.
64    ///
65    /// Note that the command invocation may need its `%f` argument substituted with the name of the file to process. It will be quoted.
66    pub smudge: Option<BString>,
67    /// the long-running program that can typically handle both smudge and clean, and possibly delay processing as well.
68    pub process: Option<BString>,
69    /// If `true`, the `clean` or `smudge` programs need to succeed in order to make their content usable. Otherwise their
70    /// exit code is ignored.
71    /// Note that this is more of a suggestion as we will always report errors as they happen as the driver API is streaming in nature,
72    /// which makes soft-failures impossible unless the caller takes precautions.
73    pub required: bool,
74}
75
76fn clear_and_set_capacity(buf: &mut Vec<u8>, cap: usize) -> Result<(), std::collections::TryReserveError> {
77    buf.clear();
78    if buf.capacity() < cap {
79        buf.try_reserve(cap)?;
80        debug_assert!(buf.capacity() >= cap, "{} >= {}", buf.capacity(), cap);
81    }
82    Ok(())
83}
gix_filter/lib.rs

gix_filter/
lib.rs
