Today marks the release of gfold 4 🎉!

Before we talk about what’s been changed, let’s talk about how far the project has come. Here are some present day statistics of note:

As some of you might recognize, these metrics are the same as those introduced in the gfold 3 announcement. Here are the statistics from that post:

Those are big leaps! I’m excited for all new and existing users to try out gfold 4, which I think is the best release yet.

There’s two technical reasons that fuel a significant portion of my excitement.

  1. I hope this release will contain the last major semver bump that will be needed for a long time (i.e. no more user-facing breaking changes for a long time). It’s a polishing iteration on the domain-driven refactor of gfold 3.
  2. There will likely be significant performance improvements for most users. In recent tests mimicking real world use, I’ve seen up to 5.1x speed increases when loosely benchmarking the most recent release candidate on macOS 12.3.1.
Average: 686.645865ms - /Users/nick - 4.0.0-rc.4
Average: 810.047984ms - /Users/nick - 3.0.0
Average: 6.156336ms - /Users/nick/src - 4.0.0-rc.4
Average: 31.491704ms - /Users/nick/src - 3.0.0

Please note: I use the term “loose benchmarking” to mean measuring average runtime duration with realistically-shaped dummy data and execution scenarios reflecting real world use. The latter translates to direct invocations of the gfold binary on mobile hardware.

True benchmarking is difficult, especially when using consumer-grade mobile processors that can produce highly variable results based on temperature and battery. However, gfold users will likely be using consumer-grade mobile hardware (i.e. laptops) on battery power, so I’ve been mostly happy with “loosely” benchmarking real world usage scenarios on similar hardware.

TLDR: these benchmarks aren’t precise, but they have been useful in making changes that can help result in perceptible performance enhancements for most gfold users.

If gfold 3 was the domain-driven refactor that helped revitalize the project, gfold 4 is the follow-up that takes lessons learned from the initial design and makes breaking changes based on them whilst retaining the skeleton of the previous release. In fact, gfold 4 was originally slated to release as gfold 3.1 due to its core execution loop remaining the same, but I am generally not a fan of deviating from semver rules and since there were user-breaking changes, I bumped the major semver field.

So… what are these major breaking changes that prompted the major semver field bump? Let’s go over them.

  • git2-rs returns and has replaced calling git subcommands
    • In previous versions of gfold, git subcommands replaced git2-rs in order to decrease binary size and allow for customization (i.e. “bring your own git”)
    • Since “speed” was a key driver of gfold 4’s design, substantial speed increases could not have been achieved without git2-rs, even if that meant increasing binary size
  • The --git-path flag has been removed since git subcommands are no longer used
  • Config file type has changed from JSON to TOML
    • JSON is difficult for users to write and edit and since gfold configuration options are pretty “flat”
    • TOML felt best for the task
  • Config file location has been moved from <prefix>/.config/gfold/gfold.json to <prefix>/.config/gfold.toml
    • The nested directory structure is unnecessary
  • The -d/--debug flag has been removed in favor of using RUST_LOG
    • This allows for more customization and removes unnecessary code (i.e. the flag set RUST_LOG=debug anyway, which env_logger can handle)
  • Remove -c/--classic flag in favor of -d/--display flag

Despite these big changes, gfold still follows the same execution pattern as before: no subcommands and operates on the current working directory (or config file setting) if a positional argument is not provided. Migrating exciting scripts, config files, aliases, etc. should be relatively painless since user-facing changes were limited to configuration and not to execution patterns.

That leads us into the best part: what are the improvements, features, and enhancements in this release?

  • Significant performance gains (observed up to 5.1x speed increases in loose benchmarks of real world usage scenarios on macOS 12.3.1)
    • No longer reliant on git subcommand calls
    • More consistent behavior since git2-rs is directly tested at a locked version
  • Color mode option with the following choices: “always”, “compatibility” and “never”
    • “always”: display with rich colors (default)
    • “compatibility”: display with portable colors
    • “never”: display with no color
  • Display flag with the following choices: “standard” (or “default”), “json” and “classic”
    • “standard” (or “default”) and “classic” output options return from gfold 3
    • “json” output is a new option that displays all results in valid JSON, which is useful for third party applications, plugins, parsers, etc.
  • Overhauled “help” (-h/--help) output with titled sections
    • includes a troubleshooting section that explains when to use RUST_LOG and RUST_BACKTRACE
    • includes a config file usage section that was originally included in gfold 3

There have also been significant non-user-facing changes both internally and externally to the application that have helped ensure this release is stable.

  • A large integration test has been added that creates dummy repositories in the crate’s target directory
    • Past and present GitHub issues have been used to create test scenarios covered by the integration test
    • This test has significantly helped in gfold 4 development
  • Bors has been added to avoid merge / skew conflicts
  • Documentation comments have been added nearly everywhere for cargo doc
  • The module layout has been refactored to ensure subdomains exist as submodules when applicable
    • display now contains its child, color
    • report now contains its child, target
  • color now uses a harness rather than individual functions for speed and domain separation

Finally, a major shoutout to a community member, AcksID! AcksID has released the excellent Neovim plugin for gfold, nvim-gfold.lua. Please show AcksID some love. The plugin is great and has a bright future ahead of it. I highly recommend Neovim users to try it out!

All in all, this is my favorite release of gfold yet. I’m excited for you to try it out and I hope you enjoy using it.

For more information, access the 4.0.0 changelog or the rolling changelog.