Fossil: Caveats and Precautions for Fossil Usage with Windows Subsystem for Linux

Fossil SCM

When These Issues Matter

The discussion following is relevant to those who:

Note that these criteria apply conjunctively; if any are not met, then the consequences of the issues below are at worst annoying and otherwise harmless or absent.

What Can Go Wrong (Why It Matters)

The most readily seen manifestation of the problem occurs when "fossil status" or "fossil changes" is run, using Linux Fossil from WSL after Windows tools (including fossil.exe) have been used to modify files within a checkout. Unless filter options block it, those subcommands will tag some (and often many) checkout files with EXECUTABLE or NOEXEC, indicating that the file's user execute permission has been altered such that it differs from what is recorded in the repository for that version of the file.

This "user execute permission" is referred to as "the X-bit" hereafter, referring to either the recorded version state or a checkout file attributes state.

This is merely annoying and distracting if the altered X-bit will never be committed using Linux Fossil. It can be quite distracting because those tags tend to mask the presence or absence of other changes whose detection is the usual reason for using Fossil's changes or status subcommands.

However, in the problematic usage scenario, those tags will most often represent inadvertant toggling of the X-bit on the affected file. The X-bit is kept in the repository for good reason (usually), and arbitrary changes to it by means of a commit when that change is not intended is virtually always a bad result. (At best, the change causes useless churn; at worst it frustrates the intended purpose of having an X-bit.)

Technical Discusion of the Problem

The genesis of altered X-bits, while not obvious at first glance, involves obvious facts. The Windows OS does not deal with the triple of user/group/other executable permissions the way that Unix and similar operating systems do. Hence, tools which run on Windows, including Fossil built for Windows, do not manage the X-bit; it may not even exist yet for files which have not had their permissions set by any Linux program running in WSL. When such tools modify a file which has had its X-bit set (or cleared) by a program in WSL, an existing X-bit value may not be preserved depending upon how the modification is effected.

The WSL infrastructure (or virtual system) compensates for the absence of an X-bit in Windows filesystems with two stratagems: (1) Establishing a default for its value when no Linux program has yet set it; and (2) stashing Linux "mode" bits in a "special" place for each file once it has been subject to a chmod() call. That default's default can be changed by way of /etc/wsl.conf content. However, this default cannot be right for files which are tracked in a Fossil repository as having the other value. And Windows tools generally are not written to deal with "mode" bits in that "special" place. (They are kept in a NTFS extended file attribute named $LXMOD, not accessible through the WIN32 API; the OS layer below WIN32 must be used to get at them.) Hence, inadvertant X-bit changes are unavoidable, or avoided only by luck, in the general usage case noted above.

Problematic Usage Scenarios

A Simple Example

Continuation of Simple Example

A Fossil-Only Example

Recommended Workflow

There are two simple approaches for dealing with this issue when one wishes to continue using the same checkout directory from Windows and WSL. Either one is effective. These are:

There are more complex ways to deal with this issue, involving use of fossil on WSL to fix (or revert) toggled X-bits prior to any commit, together with actions needed to preserve all intended changes to the checkout as fossil revert is done. Such methods are overly clever or fragile for elaboration here.

Another way to deal with this issue is to correct any toggled X-bits within a checkout before using "fossil commit" on WSL by means other than "fossil revert".

Corrective Measures or Mitigation

It is possible, by either manual or automated means, to perform a pre-commit check and/or correction for mis-toggled X-bits.

The X-bit states are available from the repository for whatever versions it has stored. And several Linux tools are able to read or alter the X-bit state of files. With these components, a tool can be readily built to aid avoidance of a commit (via fossil on WSL) that would record mis-toggled X-bits into the repository.

Fossil itself on WSL will detect mis-toggled X-bits for files which have not been otherise modified, but altered file content masks such detection, and it is just such modification that is among the problematic scenarios. So Fossil alone cannot yet reliably do the detection or correction needed to avoid or remedy the mis-toggled X-bit commit problem.

It is also feasible to detect or correct the mis-toggled X-bit problem within Windows with a special-purpose tool which can read, create or modify the X-bits stored by WSL for any file which has been subject to the Linux chmod(...) system call.

Creation of these tools is beyond the scope of this document.