|
1
|
<title>Caveats and Precautions for Fossil Usage with Windows Subsystem for Linux</title> |
|
2
|
|
|
3
|
<h2>When These Issues Matter</h2> |
|
4
|
|
|
5
|
The discussion following is relevant to those who: |
|
6
|
|
|
7
|
* Are using the Windows Subsystem for Linux (aka "WSL"); |
|
8
|
* Create a Fossil checkout in a directory accessible from WSL and Windows; |
|
9
|
* Use both Linux Fossil and Windows tools to modify files in a checkout; |
|
10
|
* Desire to or must preserve execute permissions set for repository files; |
|
11
|
* and Use Linux Fossil to commit changes made within the checkout. |
|
12
|
|
|
13
|
Note that these criteria apply conjunctively; if any are not met, |
|
14
|
then the consequences of the issues below are at worst annoying |
|
15
|
and otherwise harmless or absent. |
|
16
|
|
|
17
|
<h2>What Can Go Wrong (Why It Matters)</h2> |
|
18
|
|
|
19
|
The most readily seen manifestation of the problem occurs when |
|
20
|
"<tt>fossil status</tt>" or "<tt>fossil changes</tt>" is run, |
|
21
|
using Linux Fossil from WSL after Windows tools (including |
|
22
|
fossil.exe) have been used to modify files within a checkout. |
|
23
|
Unless filter options block it, those subcommands will tag |
|
24
|
some (and often many) checkout files with <b>EXECUTABLE</b> |
|
25
|
or <b>NOEXEC</b>, indicating that the file's user execute permission |
|
26
|
has been altered such that it differs from what is recorded |
|
27
|
in the repository for that version of the file. |
|
28
|
|
|
29
|
This "user execute permission" is referred to as "the X-bit" |
|
30
|
hereafter, referring to either the recorded version state |
|
31
|
or a checkout file attributes state. |
|
32
|
|
|
33
|
This is merely annoying and distracting if the altered X-bit |
|
34
|
will never be committed using Linux Fossil. It can be quite |
|
35
|
distracting because those tags tend to mask the presence or |
|
36
|
absence of other changes whose detection is the usual |
|
37
|
reason for using Fossil's changes or status subcommands. |
|
38
|
|
|
39
|
However, in the problematic usage scenario, those tags will |
|
40
|
most often represent inadvertant toggling of the X-bit on the |
|
41
|
affected file. The X-bit is kept in the repository for good |
|
42
|
reason (usually), and arbitrary changes to it by means of a |
|
43
|
commit when that change is not intended is virtually always |
|
44
|
a bad result. (At best, the change causes useless churn; at |
|
45
|
worst it frustrates the intended purpose of having an X-bit.) |
|
46
|
|
|
47
|
<h2>Technical Discusion of the Problem</h2> |
|
48
|
|
|
49
|
The genesis of altered X-bits, while not obvious at first glance, |
|
50
|
involves obvious facts. The Windows OS does not deal with the |
|
51
|
triple of user/group/other executable permissions the way that |
|
52
|
Unix and similar operating systems do. Hence, tools which run |
|
53
|
on Windows, including Fossil built for Windows, do not manage |
|
54
|
the X-bit; it may not even exist yet for files which have not |
|
55
|
had their permissions set by any Linux program running in WSL. |
|
56
|
When such tools modify a file which has had its X-bit set (or |
|
57
|
cleared) by a program in WSL, an existing X-bit value may not |
|
58
|
be preserved depending upon how the modification is effected. |
|
59
|
|
|
60
|
The WSL infrastructure (or virtual system) compensates for the |
|
61
|
absence of an X-bit in Windows filesystems with two stratagems: |
|
62
|
(1) Establishing a default for its value when no Linux program |
|
63
|
has yet set it; and (2) stashing Linux "mode" bits in a "special" |
|
64
|
place for each file once it has been subject to a chmod() call. |
|
65
|
That default's default can be changed by way of /etc/wsl.conf |
|
66
|
content. However, this default cannot be right for files which |
|
67
|
are tracked in a Fossil repository as having the other value. |
|
68
|
And Windows tools generally are not written to deal with "mode" |
|
69
|
bits in that "special" place. (They are kept in a NTFS extended |
|
70
|
file attribute named $LXMOD, not accessible through the WIN32 |
|
71
|
API; the OS layer below WIN32 must be used to get at them.) |
|
72
|
Hence, inadvertant X-bit changes are unavoidable, or avoided |
|
73
|
only by luck, in the general usage case noted above. |
|
74
|
|
|
75
|
<h2>Problematic Usage Scenarios</h2> |
|
76
|
|
|
77
|
<h3>A Simple Example</h3> |
|
78
|
|
|
79
|
* Open a checkout in Windows (using fossil.exe) from a project |
|
80
|
whose files have a mixture of executable and non-executable files. |
|
81
|
Use a checkout directory visible when running under WSL. |
|
82
|
|
|
83
|
* Navigate to the same directory in a Linux shell on WSL, then |
|
84
|
run "fossil status". |
|
85
|
|
|
86
|
* Depending upon /etc/wsl.conf content (or defaults in its absence), |
|
87
|
the status ouput will tag checkout files as EXECUTABLE or NOEXEC. |
|
88
|
|
|
89
|
<h3>Continuation of Simple Example</h3> |
|
90
|
|
|
91
|
* In the same checkout as above "Simple Example", on WSL, |
|
92
|
run "fossil revert" to correct all those errant X-bit values. |
|
93
|
|
|
94
|
* Run "fossil status" again in WSL to verify absence of toggled X-bits. |
|
95
|
|
|
96
|
* Run "ls -l" from WSL to find two files, one with its X-bit set |
|
97
|
and the other with it clear. |
|
98
|
|
|
99
|
* From Windows, perform these steps on each of those files:<br> |
|
100
|
(1) read the_file content into a buffer<br> |
|
101
|
(2) rename the_file the_file.bak<br> |
|
102
|
(3) write buffer content to new file, the_file<br> |
|
103
|
(4) del the_file.bak (or leave it)<br> |
|
104
|
(Note that this sequence is similar to what many editors do when |
|
105
|
a user modifies a file then uses undo to reverse the changes.) |
|
106
|
|
|
107
|
* Run "fossil status" again in WSL and observe that one of the |
|
108
|
two files has had its X-bit toggled. |
|
109
|
|
|
110
|
<h3>A Fossil-Only Example</h3> |
|
111
|
|
|
112
|
* In the another (different) checkout of the same version, |
|
113
|
somehow cause "legitimate" X-bit toggles of two files whose |
|
114
|
X-bits differ. (This "somehow" probably will involve WSL to |
|
115
|
toggle file bits and fossil on WSL to commit the toggles.) |
|
116
|
|
|
117
|
* In the Simple Example checkout, use fossil.exe on Windows |
|
118
|
to update the checkout, ostensibly bringing the X-bit toggles |
|
119
|
into the affected checkout files. |
|
120
|
|
|
121
|
* In the Simple Example checkout, use fossil on WSL to run |
|
122
|
"fossil status", and observe at least one X-bit discrepancy. |
|
123
|
|
|
124
|
<h2>Recommended Workflow</h2> |
|
125
|
|
|
126
|
There are two simple approaches for dealing with this issue when |
|
127
|
one wishes to continue using the same checkout directory from |
|
128
|
Windows and WSL. Either one is effective. These are: |
|
129
|
|
|
130
|
* Do not use fossil on WSL for any operations which will modify |
|
131
|
the repository. Instead, block those operations in some manner. |
|
132
|
|
|
133
|
* Do not use any tools on Windows, (including certain subcommands |
|
134
|
of fossil.exe,) which may modify the X-bits on files within the |
|
135
|
shared checkout, instead restricting use of Windows tools to those |
|
136
|
which are known to only (and actually) modify file content in place |
|
137
|
while preserving X-bit values. (The "actually" proviso emphasizes |
|
138
|
that tools which only simulate in-place file modification, but do |
|
139
|
so via create combined with delete and rename, are to be avoided. |
|
140
|
A simulation which works flawlessly on Windows may not preserve |
|
141
|
the WSL X-bit.) |
|
142
|
|
|
143
|
There are more complex ways to deal with this issue, involving |
|
144
|
use of fossil on WSL to fix (or revert) toggled X-bits prior |
|
145
|
to any commit, together with actions needed to preserve all |
|
146
|
intended changes to the checkout as fossil revert is done. |
|
147
|
Such methods are overly clever or fragile for elaboration here. |
|
148
|
|
|
149
|
Another way to deal with this issue is to correct any toggled |
|
150
|
X-bits within a checkout before using "fossil commit" on WSL |
|
151
|
by means other than "fossil revert". |
|
152
|
|
|
153
|
<h2>Corrective Measures or Mitigation</h2> |
|
154
|
|
|
155
|
It is possible, by either manual or automated means, to perform |
|
156
|
a pre-commit check and/or correction for mis-toggled X-bits. |
|
157
|
|
|
158
|
The X-bit states are available from the repository for whatever |
|
159
|
versions it has stored. And several Linux tools are able to read |
|
160
|
or alter the X-bit state of files. With these components, a tool |
|
161
|
can be readily built to aid avoidance of a commit (via fossil on |
|
162
|
WSL) that would record mis-toggled X-bits into the repository. |
|
163
|
|
|
164
|
Fossil itself on WSL will detect mis-toggled X-bits for files |
|
165
|
which have not been otherise modified, but altered file content |
|
166
|
masks such detection, and it is just such modification that is |
|
167
|
among the problematic scenarios. So Fossil alone cannot yet |
|
168
|
reliably do the detection or correction needed to avoid or |
|
169
|
remedy the mis-toggled X-bit commit problem. |
|
170
|
|
|
171
|
It is also feasible to detect or correct the mis-toggled X-bit |
|
172
|
problem within Windows with a special-purpose tool which can |
|
173
|
read, create or modify the X-bits stored by WSL for any file |
|
174
|
which has been subject to the Linux chmod(...) system call. |
|
175
|
|
|
176
|
Creation of these tools is beyond the scope of this document. |
|
177
|
|