Skip to main content

Architecture - Under the Hood

This section describes the inner workings of HighFlux, specifically how it's interacting with git and GitHub.

HighFlux uses git for all its storage and networking. None of your source code ever gets sent to HighFlux-controlled servers, only to the remote repository that was already part of your git setup.

General architecture of the HighFlux desktop application​

The HighFlux desktop application is a Rust program built using Tauri.

The HighFlux main binary contains the following components:

The HighFlux daemon​

The HighFlux daemon runs in the background, watches file changes on the git repositories you specify, and processes those changes. (see How HighFlux uses git for storage and networking below) The daemon is automatically started together with the desktop app.

If you use the command line interface, the daemon receives those, handles them and returns the results to the CLI.

CLI interface​

The HighFlux binary has a modern command line interface. Type :

hf --help

to explore it.

How HighFlux uses git for its underlying storage and networking​

The 'current WIP' and storage branches​

Under the hood HighFlux keeps a git branch for every WIP you have.

When you work on a WIP, HighFlux creates a branch called current-wip/XX-123-[your wip title], and this branch points to the commit of trunk that you're working off of. While you work on your code, HighFlux synchronizes all changes to a commit on the "storage" branch, which looks like wip/XX-123.... That branch is also periodically pushed to your remote git repository (usually hosted on GitHub, GitLab and the likes).

After you save a change to a file in your repository:

  1. The HighFlux filesystem monitor detects the changed file
  2. HighFlux adds the file to the storage branch and commits the storage branch.
  3. After a few seconds, HighFlux pushes the storage branch to your remote git repository.
  4. HighFlux adds and stages the file on your 'current-wip' branch.

As you can see, the 'current-wip' branch is never pushed to the remote repository. Thus only the storage branch will be visible on your remote git repository.

The reason HighFlux has a 'current-wip' branch and a storage branch, is to support traditional git tools better. If HighFlux had only the storage branch on which you would work while auto-committing all your changes, your IDE can't show you which lines are changed compared to the current commit, HEAD is then always the same as your current state etc. With the current setup, Intellij and VS code show your open changes and modified files as usual and you can do git diff HEAD to get the diff, etc.

HighFlux ensures that whenever you work on a WIP, your current git branch is always set to the 'current-wip' one while the files on disk are set to the latest committed state of the storage branch.

The code review branch​

When you create a code review, HighFlux creates a branch called review/XX-123 and places all of the changes made on the current WIP there. You could then send this branch to your reviewers using your favorite code review tool. Once you get suggestions for changes from your peers, you implement them regularly on your current WIP. When you’re ready to send the reviewer another version for review, the “Update Review” UI action, or the hf review update, causes all of the changes you made to your WIP since the last time you “updated” the review or “created” it, to be applied to the review-branch as a single commit.

(You can also open a code review on your WIP storage branch, which will then make it hard for the reviewer to track what happens between different rounds of the review, as the commit on the storage branch keeps getting rewritten).