Klipper Versioning, Downgrading, and Bisecting

Knowledge Base
1

Klipper Versioning, Downgrading, and Bisecting

Table of Contents

  1. Understanding Klipper’s Versioning

  2. How to Read Version Information

  3. Downgrading to a Previous Version

  4. Using git bisect to Find Problematic Commits

Understanding Klipper’s Versioning

Klipper uses Git (hosted on GitHub) to manage its source code and version history. You can find the currently running versions of Klipper in several locations:

1. klippy.log

The klippy.log file is essential for troubleshooting. It logs version information at startup for both the host and each connected MCU:

Git version: 'v0.13.0-79-gcc6736c3e-dirty'
...
Loaded MCU 'mcu' 119 commands (v0.12.0-464-gf80df4ca1)
Loaded MCU 'MAG_TOOL' 121 commands (v0.12.0-464-gf80df4ca1)

This indicates:

  • Klippy Host: v0.13.0-79-gcc6736c3e-dirty
  • MCUs: v0.12.0-464-gf80df4ca1

2. Web Interfaces

Web UIs like Mainsail or Fluidd also display this information. In Mainsail, look under the Machine tab.

Mainsail_Versions
Mainsail_Versions934×549 28.8 KB

3. Git Commands

To check the current host version directly via Git:

git describe --always --tags --long --dirty
# Or
git log --oneline --decorate

Note: These commands only reflect the host code version.

How to Read Version Information

A version string like v0.13.0-79-gcc6736c3e-dirty contains:

  • v0.13.0: The main version tag. Depending on the development progress and type of changes, the developers “tag” the version at irregular intervals.
  • 79: A commit counter. After a main version tag is established, each subsequent commit to the Git repository increases this counter by one. This means that since tagging the v0.13.0 version, 79 changes have been committed to the repository.
  • gcc6736c3e: This is the shortened hash value of the commit, which serves as a unique identifier for the specific change.

    Note: The initial ‘g’ is not part of the hash value.

  • dirty: This indicates that the local source code has been modified compared to Klipper’s mainline code on GitHub. For more information on this topic, see this article.

MCU vs Host Version Differences

It’s normal for MCU and host versions to differ:

  • Host: v0.13.0-79-gcc6736c3e-dirty
  • MCU: v0.12.0-464-gf80df4ca1

This is expected, as firmware changes are less frequent than host changes. Klipper validates compatibility between them and will raise a protocol error if necessary. For normal operation, it is not required to keep them the same.

Downgrading to a Previous Version

Rolling back to a previous commit in Git can be done in two main ways: the soft way and the hard way. The choice depends on whether you want to retain local modifications or ensure your local repository is fully identical to the remote repository.

Identifying the Desired Commit

Browse the Klipper GitHub commit history to find the hash of the version you want. Click the clipboard icon next to a commit to copy the hash.

GitHub_Hash
GitHub_Hash1202×707 29.1 KB

Soft Reset (Keep Local Changes)

The soft way allows you to revert to a specific commit without losing any changes in your working directory. This method is useful if you want to test a previous state, but certain modifications are essential for the regular operation of the printer.

cd ~/klipper                 # Switch to the Klipper folder
sudo service klipper stop    # Shutdown the running Klipper
git checkout <commit-hash>   # <commit-hash> to be replaced by the desired hash

Note: Depending on potential changes, the checkout command may fail easily. If it fails or causes instability, use the hard reset method or re-clone the repository.

Hard Reset (Clean Slate)

Ensures your local repository exactly matches a specified commit. It completely resets your working directory, removing all local changes. It is recommended for accurate troubleshooting and bug reporting:

cd ~/klipper                     # Switch to the Klipper folder
sudo service klipper stop        # Shutdown the running Klipper
git reset --hard <commit-hash>   # <commit-hash> to be replaced by the desired hash

Using git bisect to Find Problematic Commits

Overview

git bisect helps you find the exact commit that introduced a bug or issue by performing a search through the commit history. This tool automatically narrows down the range of commits by testing a midpoint commit and adjusting the search range based on whether the issue exists in that commit.

Steps to Use git bisect

  1. Start Bisecting
    Begin by marking the good and bad commits. The relevant commit-hashes have to be determined as outlined above.

    cd ~/klipper                   # Switch to the Klipper folder
sudo service klipper stop      # Shutdown the running Klipper
git bisect start               # Start the bisecting process
git bisect bad                 # Current commit (where the bug exists)
git bisect good <commit-hash>  # Last known good commit

  2. Test the Bisected Commit
    Git will check out a commit in the middle of the good and bad range.
    To really determine the potential issue’s presence, it makes sense to also ensure that the firmware on the connected board’s always align with the host application’s version. To achieve this, the firmware should be build and flashed according to the following process:

    make clean                      # Remove all previous build artifacts
make menuconfig                 # Create matching board configuration
make                            # Build the firmware
make flash FLASH_DEVICE=<path>  # <path> being the board's known path
sudo service klipper restart    # (Re)Start Klipper

    Note: The above procedure is common. Depending on the specific board’s requirements, a different flashing procedure might be applicable.

    Now the setup needs to be tested if the unwanted behavior still exists or can be provoked

    • If the bug is present, mark the commit as bad:

      git bisect bad

    • If the bug is not present, mark the commit as good:

      git bisect good

  3. Repeat Testing
    Once a commit is classified as either good or bad, Git will continue to narrow the range. For each iteration:

    • Shut down Klipper
    • Flash firmware to match the host
    • Start Klipper and test again
    • Classify the result as good or bad

  4. Finish Bisecting
    Once git bisect has narrowed it down to a single commit, it will tell you which commit introduced the issue. To end the bisect process and return to the original branch, run:

    git bisect reset
6 Likes