Byron/gitoxide git-config-v0.6.0

git-config v0.6.0

on GitHub

New Features

• following includes is now non-fatal by default
  Otherwise it would be relatively easy to fail gitoxide startup,
  and we want to be closer to the behaviour in git which ignores
  most of the errors.

• File::from_git_dir() as comfortable way to instantiate most complete git configuration.

• File now compares actual content, ignoring whitespace and comments.

• File::new_environment_overrides() to easily instantiate overrides from the environment.

• File::new_globals() can instantiate non-local configuration with zero-configuration.

• Source::storage_location() to know where files should be located.

• file::ValueMut::(section|into_section_mut)() to go from value to the owning section.
  This can be useful if the value was obtained using raw_value_mut().

• Source::is_in_repository() to find out if a source is in the repository.

• parse::key to parse a remote.origin.url-like key to identify a value

• Add File::detect_newline_style(), which does at it says.

• File::frontmatter() and File::sections_and_postmatter().

• parse::Event::to_bstr_lossy() to get a glimpse at event content.

• File::append() can append one file to another rather losslessly.
  The loss happens as we, maybe for the wrong reasons, automatically
  insert newlines where needed which can only be done while we still know
  the file boundaries.

• file::Section::meta() to access a section's metadata.

• File::sections() to obtain an iterator over all sections, in order.

• place spaces around key = value pairs, or whatever is used in the source configuration.

• proper escaping of value bytes to allow round-tripping after mutation

• whitespace in newly pushed keys is derived from first section value.
  That way, newly added key-value pairs look like they should assuming
  all keys have the same indentation as the first key in the section.

  If there is no key, then the default whitespace will be double-tabs
  like what's commmon in git.

• File::from_str() implementation, to support let config: File = "[core]".parse()?

• whitespace in mutable sections can be finely controlled, and is derived from existing sections

• parse::Header::new(…) with sub-section name validation

• Add parse::(Event|section::Header|Comment)::write_to(…).
  Now it's possible to serialize these types in a streaming fashion and
  without arbitrarily enforcing UTF-8 on it

• serde1 feature to add limited serde support

Bug Fixes

• maintain insertion order of includes on per-section basis at least.
  Note that git inserts values right after the include directive,
  'splitting' the section, but we don't do that and insert new values
  after the section. Probably no issue in practice while keeping
  our implementation simple.

• maintain newline format depending on what's present or use platform default.
  Previously implicit newlines when adding new sections or keys to
  sections was always \n which isn't correct on windows.

  Now the newline style is detected and used according to what's present,
  or in the lack of content, defaults to what's correct for the platform.

• validate incoming conifguration keys when interpreting envirnoment variables.

• Boolean can use numbers to indicate true or false, drops support for one and zero.

• file::MutableSection::remove() now actually removes keys and values.

• file::MutableMultiValue escapes input values and maintains key separator specific whitespace.

• value normalization (via value::normalize() handles escape sequences.
  The latter ones are \n, \t and \b which are the only supported
  ones in values of git-config files.

• stable sort order for File::sections_by_name_with_header()

• count newlines (for error display) in multi-line values as well

• auto-normalize string values to support quote removal in case of strings.
  Related to starship/starship#3883 .

Other

• :Events::from_bytes()withfilter` support.

Changed (BREAKING)

• add File::resolve_includes() and move its error type to file::includes.

• add File::from_bytes_owned() and remove File::from_path_with_buf()

• remove File::from_env_paths().
  It's replaced by its more comfortable new_globals().

• untangle file::init::… Option and Error types.
  This moves types to where they belong which is more specific instead
  of having a catch-all Error and Options type.

• rename parse::Comment::(comment_tag|comment) to ::tag|text and parse::Section::section_header to ::header.

• Associate file::Metadata with each File.
  This is the first step towards knowing more about the source of each
  value to filter them based on some properties.

  This breaks various methods handling the instantiation of configuration
  files as file::Metadata typically has to be provided by the caller
  now or be associated with each path to read configuration from.

• rename file::SectionBody to file::section::Body.

• Remove File::sections_by_name_with_header() as ::sections_by_name() now returns entire sections.

• create resolve_includes options to make space for more options when loading paths.

• rename path::Options into path::Context.
  It's not an option if it's required context to perform a certain
  operation.

• All accessors in File are now using impl AsRef<str> where possible for added comfort.

• Much more comfortable API file::*Mut types thanks to impl Into/AsRef.

• Rename Mutable* into $1Mut for consistency.

• conform APIs of file::MutableValue and file::MutableMultiValue.
  There are more renames and removals than worth mentioning here given the
  current adoption of the crate.

• rename file::MutableSection::set_leading_space() to set_leading_whitespace().
  The corresponding getter was renamed as well to leading_whitespace().

• Enforce parse::section::Header::new() by making its fields private.

• Add File::write_to() and File::to_bstring(); remove some TryFrom impls.
  Now File can be serialized in a streaming fashion and without the
  possibility for UTF8 conversion issues.

  Note that Display is still imlpemented with the usual caveats.

• remove Integer::to_bstring() as well as some TryFrom impls.
  Note that it can still display itself like before via
  std::fmt::Display.

• remove Boolean::to_bstring() along with a few From impls.
  These were superfluous and aren't useful in practice.
  Note that serialization is still implemented via Display.

• allocation free File::sections_by_name() and File::sections_by_name_with_header().

• Path::interpolate() now takes path::interpolate::Options instead of three parameters.

• remove String type in favor of referring to the File::string() method.
  The wrapper had no effect whatsoever except for adding complexity.

• Simplify Boolean to be a wrapper around bool.
  Previously it tried hard not to degenerate information, making it a
  complicated type.

  However, in practice nobody cares about the exact makeup of the boolean,
  and there is no need to serialize a boolean faithfully either.

  Instead, those who want to set a value just set any value as a string,
  no need for type safety there, and we take care of escaping values
  properly on write.

• Use bitflags for color::Attribute instead of Vec of enums.
  This is less wasteful and sufficient for git, so it should be sufficient
  for us, especially since attributes are indeed a set and declaring
  one twice has no effect.

• simplify Color API.
  For now we only parse and serialize for display, but more uses are
  enabled when needed and trivially.

• remove parse::Events::from_path and File::at
  The latter has been replaced with File::from_path_with_buf(…) and
  is a low-level way to load just a single config file, purposefully
  uncomfortable as it will not resolve includes.

  The initialization API will need some time to stabilize.

• Slim down API surface of parse::Events.
  It's more of a 'dumb' structure now than before, merely present
  to facilitate typical parsing than something special on its own.

• remove File::new() method in favor of File::default().

• rename parse::event::List to parse::Events

• rename parse::State to parse::event::List

• move value::* into the crate root, except for Error and normalize_*().

• rename value::parse::Error to value::Error.

• rename value::TrueVariant to value::boolean::True

• rename IntegerSuffix to integer::Suffix

• rename value::Color(Attribute|Value) to value::color::Attribute and value::color::Name.

• Turn parse::ParseOrIoError into parse::state::from_path::Error

• rename parse::ParsedComment into parse::Comment

• rename parse::Section* related types.
  These are now located in section::*.

• rename parse::Parser to parse::State.
  Furthermore, make State the entry point for all parsing, removing
  all free-standing functions that returned a State.

• rename parser module to parse

• rename normalize_cow() to normalize() and move all normalize* functions from values to the value module

• move Path from values to value module

• Move Boolean and String from values into value module

• move values::Integer into value module

• move Color to own value module

• remove values::Bytes - use values::String instead.
  Note that these values are always normalized and it's only possible
  to get a raw values using the raw_value() API.

New Features (BREAKING)

• Support for lossy load mode.
  There is a lot of breaking changes as file::from_paths::Options now
  became file::init::Options, and the same goes for the error type.

• add _filter() versions to most access methods.
  That way it's possible to filter values by their origin.

  Note that the remove_section() methods now return the entire
  removed section, not just the body, which yields more information
  than before including section metadata.

• section names are now validated.

• filtering supportort for parse::Events.
  That way it's possible to construct Files which are not destined to be
  written back as they only keep events necessary for value access,
  greatly reducing allocations.

• change mostily internal uses of [u8] to BString/BStr

• Path-interpolation makes home-dir configurable.
  That way the caller has full control over how the environment is used,
  which also allows more fine-grained control over which config files
  can be included.

Bug Fixes (BREAKING)

• Simplify specifying keys when mutating config values.

• File::rename_section() with validation of input arguments.

• improve normalization; assure no extra copies are made on query.
  We now return our own content, rather than the originals with their
  lifetimes, meaning we bind lifetimes of returned values to our own
  File instance. This allows them to be referenced more often, and
  smarter normalization assures we don't copy in the simple cases
  either.

  More tests were added as well.
  This is breaking as lifetime changes can cause distruptions, and
  values?_as() was removed as well as it's somewhat duplicate
  to higher-level APIs and it wasn't tested at all.

• Remove git-config test utilities from git-path.

Other (BREAKING)

• File::raw_multi_value() to File::raw_values()
• File::raw_multi_value_mut() to File::raw_values_mut()
• File::multi_value() to File::values().
  The latter is better in line with string()/strings()

Commit Statistics

• 314 commits contributed to the release over the course of 33 calendar days.
• 39 days passed between releases.
• 93 commits where understood as conventional.
• 1 unique issue was worked on: #331

Thanks Clippy

Clippy helped 19 times to make code idiomatic.

Commit Details