Fossil SCM

Add wsl_caveats.wiki (now free-floating)

larrybr 2022-01-19 06:30 trunk

Commit 73ba7637be0d4e36dd67556386a1130218b3931c3d890fe90937d0a2cf5958c1

Parent fef157554fabba4…

1 file changed +134

A www/wsl_caveats.wiki

+134

		--- a/www/wsl_caveats.wiki
		+++ b/www/wsl_caveats.wiki
		@@ -0,0 +1,134 @@
	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 rlevant to those who:
	6	+
	7	+ * Are uor Linux (aka "WSL");
	8	+ * Create a Fossil checkout in a directory accessibleUse both Linux Fossil and Windows tools to modify files in a checkout;
	9	+ * Desire to or must preserve execute permissions set for repository files;
	10	+ * and Use Linux Fossil to commit changes made within the checkout.
	11	+
	12	+Note that these criteria apply conjunctively; if any are not met,
	13	+then the consequences of the issues below are at worst annoying
	14	+and otherwise harmless or absent.
	15	+
	16	+<h2>What Can Go Wrong (Why It Matters)</h2>
	17	+
	18	+The most readily seen manifestation of the problem occurs when
	19	+"<tt>fossil status</tt>" or "<tt>fossil changes</tt>" is run,
	20	+using Linux Fossil from WSL after Windows tools (including
	21	+fossil.exe) have been used to modify files within a checkout.
	22	+Unless filter options block it, those subcommands will tag
	23	+some (and often many) checkout files with <b>EXECUTABLE</b>
	24	+or <b>NOEXEC</b>, indicating that the file's user execute permission
	25	+has been altered such that it differs from what is recorded
	26	+in the repository for that version of the file.
	27	+
	28	+This "user execute permission" is referred to as "the X-bit"
	29	+hereafter, referring to either the recorded version state
	30	+or a checkout file attributes state.
	31	+
	32	+This is merely annoying and distracting if the altered X-bit
	33	+will never be committed using Linux Fossil. It can be quite
	34	+distracting because those tags tend to mask the presence or
	35	+absence of other changes whose detection is the usual
	36	+reason for using Fossil's changes or status subcommands.
	37	+
	38	+However, in the problematic usage scenario, those tags will
	39	+most often represent inadvertant toggling of the X-bit on the
	40	+affected file. The X-bit is kept in the repository for good
	41	+reason (usually), and arbitrary changes to it by means of a
	42	+commit when that change is not intend*sult. (At best, the change causes useless churn; at
	43	+worst it frustrates the intended purpose of having an X-bit.)
	44	+
	45	+<h2>Technical Discusion of the Problem</h2>
	46	+
	47	+*while not obvious at first glance,
	48	+involves obvious facts. The Windows OS does not d*<title>Caveats and Precautions for Fossil Usage with Windows Subsystem for Linux</title>
	49	+
	50	+<h2>When These Issues Matter</h2>
	51	+
	52	+The discussion followingn In the same checkout as above "Simple Example", on WSL,
	53	+run "fossil revert" to correct all t* Run "fossil status" again in WSL to verify absence of toggled X-bits.
	54	+
	55	+* Run "ls -l" from WSL to find two files, one with its X-bit set
	56	+and the other with it clear.
	57	+
	58	+* other with it clear.
	59	+
	60	+ * Fro
	61	+(1) read the_fileo a buffere_file.bak<br>
	62	+ &nb, the_file<b(Note that this sequence is similar to what many editors do when
	63	+a user modifies a file then uses undo to reverse the changes.)
	64	+
	65	+* Run "fossil status" again in WSL and observe that one of the
	66	+two files has had its X-bit toggled.
	67	+
	68	+<h3>A Fossil-Only Example</h3>
	69	+
	70	+*sil-Only Example</h3>
	71	+
	72	+ * In the another (different) checkout of the same version,
	73	+somehow cause "legitimate" X-bit toggles of two files whose
	74	+X-bits differ. (This "somehow" probably will involve WSL to
	75	+toggle* In the Simple Example checkout, use fossil.exe on Windows
	76	+to update the checkout, ostensibly bringing the X-bit toggles
	77	+into the affected checkout files.
	78	+
	79	+*le>
	80	+
	81	+<h2>When These Issues Matter</h2>
	82	+
	83	+The discussion following is relevant to those who:
	84	+
	85	+ * Are using the Windows Subsystem for Linux (aka "WSL");
	86	+ * Create a Fossil checkout in a directory accessible from WSL and Windows;
	87	+ * Use both Linux Fossil and Windows tools to modify files in a checkout;
	88	+ * Desire to or must pre< Do not use fossil on WSL for any operations which will modify
	89	+the repository. Instead, block those operations in some manner.
	90	+
	91	+* Do not use any tools on Windows, (including certain subcommands
	92	+of fossil.exe,) which may modify the X-bits on files within the
	93	+shared checkout, instead restricting use of Windows tools to those
	94	+which are known to only (and actually) modify file content in place
	95	+while preserving X-bit values. (The "actually" proviso emphasizes
	96	+that tools which only simulate in-place file modification, but do
	97	+so via create combined with delete and rename, are to be avoided.
	98	+A simulation which works flawlessly on Windows may not preserve
	99	+the WSL X-bit.)
	100	+
	101	+There are more complex ways to deal with this issue, involving
	102	+use of fossil on WSL to fix (or revert) toggled X-bits prior
	103	+to any commit, together with actions needed to preserve all
	104	+intended changes to the checkout as fossil revert is done.
	105	+Such methods are overly clever or fragile for elaboration here.
	106	+
	107	+Another way to deal with this issue is to correct any toggled
	108	+X-bits within a checkout before using "fossil commit" on WSL
	109	+by means other than "fossil revert".
	110	+
	111	+<h2>Corrective Measures or Mitigation</h2>
	112	+
	113	+It is possible, by either manual or automated means, to perform
	114	+a pre-commit check and/or correction for mis-toggled X-bits.
	115	+
	116	+The X-bit states are available from the repository for whatever
	117	+versions it has stored. And several Linux tools are able to read
	118	+or alter the X-bit state of files. With these components, a tool
	119	+can be readily built to aid avoidance of a commit (via fossil on
	120	+WSL) that would record mis-toggled X-bits into the repository.
	121	+
	122	+Fossil itself on WSL will detect mis-toggled X-bits for files
	123	+which have not been otherise modified, but altered file content
	124	+masks such detection, and it is just such modification that is
	125	+among the problematic scenarios. So Fossil alone cannot yet
	126	+reliably do the detection or correction needed to avoid or
	127	+remedy the mis-toggled X-bit commit problem.
	128	+
	129	+It is also feasible to detect or correct the mis-toggled X-bit
	130	+problem within Windows with a special-purpose tool which can
	131	+read, create or modify the X-bits stored by WSL for any file
	132	+which has been subject to the Linux chmod(...) system call.
	133	+
	134	+Creation of these tools is beyond t

	--- a/www/wsl_caveats.wiki
	+++ b/www/wsl_caveats.wiki
	@@ -0,0 +1,134 @@

	--- a/www/wsl_caveats.wiki
	+++ b/www/wsl_caveats.wiki
	@@ -0,0 +1,134 @@
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 rlevant to those who:
6
7	* Are uor Linux (aka "WSL");
8	* Create a Fossil checkout in a directory accessibleUse both Linux Fossil and Windows tools to modify files in a checkout;
9	* Desire to or must preserve execute permissions set for repository files;
10	* and Use Linux Fossil to commit changes made within the checkout.
11
12	Note that these criteria apply conjunctively; if any are not met,
13	then the consequences of the issues below are at worst annoying
14	and otherwise harmless or absent.
15
16	<h2>What Can Go Wrong (Why It Matters)</h2>
17
18	The most readily seen manifestation of the problem occurs when
19	"<tt>fossil status</tt>" or "<tt>fossil changes</tt>" is run,
20	using Linux Fossil from WSL after Windows tools (including
21	fossil.exe) have been used to modify files within a checkout.
22	Unless filter options block it, those subcommands will tag
23	some (and often many) checkout files with <b>EXECUTABLE</b>
24	or <b>NOEXEC</b>, indicating that the file's user execute permission
25	has been altered such that it differs from what is recorded
26	in the repository for that version of the file.
27
28	This "user execute permission" is referred to as "the X-bit"
29	hereafter, referring to either the recorded version state
30	or a checkout file attributes state.
31
32	This is merely annoying and distracting if the altered X-bit
33	will never be committed using Linux Fossil. It can be quite
34	distracting because those tags tend to mask the presence or
35	absence of other changes whose detection is the usual
36	reason for using Fossil's changes or status subcommands.
37
38	However, in the problematic usage scenario, those tags will
39	most often represent inadvertant toggling of the X-bit on the
40	affected file. The X-bit is kept in the repository for good
41	reason (usually), and arbitrary changes to it by means of a
42	commit when that change is not intend*sult. (At best, the change causes useless churn; at
43	worst it frustrates the intended purpose of having an X-bit.)
44
45	<h2>Technical Discusion of the Problem</h2>
46
47	*while not obvious at first glance,
48	involves obvious facts. The Windows OS does not d*<title>Caveats and Precautions for Fossil Usage with Windows Subsystem for Linux</title>
49
50	<h2>When These Issues Matter</h2>
51
52	The discussion followingn In the same checkout as above "Simple Example", on WSL,
53	run "fossil revert" to correct all t* Run "fossil status" again in WSL to verify absence of toggled X-bits.
54
55	* Run "ls -l" from WSL to find two files, one with its X-bit set
56	and the other with it clear.
57
58	* other with it clear.
59
60	* Fro
61	(1) read the_fileo a buffere_file.bak<br>
62	&nb, the_file<b(Note that this sequence is similar to what many editors do when
63	a user modifies a file then uses undo to reverse the changes.)
64
65	* Run "fossil status" again in WSL and observe that one of the
66	two files has had its X-bit toggled.
67
68	<h3>A Fossil-Only Example</h3>
69
70	*sil-Only Example</h3>
71
72	* In the another (different) checkout of the same version,
73	somehow cause "legitimate" X-bit toggles of two files whose
74	X-bits differ. (This "somehow" probably will involve WSL to
75	toggle* In the Simple Example checkout, use fossil.exe on Windows
76	to update the checkout, ostensibly bringing the X-bit toggles
77	into the affected checkout files.
78
79	*le>
80
81	<h2>When These Issues Matter</h2>
82
83	The discussion following is relevant to those who:
84
85	* Are using the Windows Subsystem for Linux (aka "WSL");
86	* Create a Fossil checkout in a directory accessible from WSL and Windows;
87	* Use both Linux Fossil and Windows tools to modify files in a checkout;
88	* Desire to or must pre< Do not use fossil on WSL for any operations which will modify
89	the repository. Instead, block those operations in some manner.
90
91	* Do not use any tools on Windows, (including certain subcommands
92	of fossil.exe,) which may modify the X-bits on files within the
93	shared checkout, instead restricting use of Windows tools to those
94	which are known to only (and actually) modify file content in place
95	while preserving X-bit values. (The "actually" proviso emphasizes
96	that tools which only simulate in-place file modification, but do
97	so via create combined with delete and rename, are to be avoided.
98	A simulation which works flawlessly on Windows may not preserve
99	the WSL X-bit.)
100
101	There are more complex ways to deal with this issue, involving
102	use of fossil on WSL to fix (or revert) toggled X-bits prior
103	to any commit, together with actions needed to preserve all
104	intended changes to the checkout as fossil revert is done.
105	Such methods are overly clever or fragile for elaboration here.
106
107	Another way to deal with this issue is to correct any toggled
108	X-bits within a checkout before using "fossil commit" on WSL
109	by means other than "fossil revert".
110
111	<h2>Corrective Measures or Mitigation</h2>
112
113	It is possible, by either manual or automated means, to perform
114	a pre-commit check and/or correction for mis-toggled X-bits.
115
116	The X-bit states are available from the repository for whatever
117	versions it has stored. And several Linux tools are able to read
118	or alter the X-bit state of files. With these components, a tool
119	can be readily built to aid avoidance of a commit (via fossil on
120	WSL) that would record mis-toggled X-bits into the repository.
121
122	Fossil itself on WSL will detect mis-toggled X-bits for files
123	which have not been otherise modified, but altered file content
124	masks such detection, and it is just such modification that is
125	among the problematic scenarios. So Fossil alone cannot yet
126	reliably do the detection or correction needed to avoid or
127	remedy the mis-toggled X-bit commit problem.
128
129	It is also feasible to detect or correct the mis-toggled X-bit
130	problem within Windows with a special-purpose tool which can
131	read, create or modify the X-bits stored by WSL for any file
132	which has been subject to the Linux chmod(...) system call.
133
134	Creation of these tools is beyond t

Fossil SCM

Keyboard Shortcuts