Fossil SCM

Brought the globs doc back into line with the underlying implementation, and to mention the new treatement of the empty-dirs setting's value.

wyoung 2023-05-22 22:23 trunk

Commit 2c0b70eb5a758dd456afa215cc5015f0b0a8c91a0b420ef3a59717535d8de6dd

Parent f12609fcaa95ac4…

1 file changed +22 -22

~ www/globs.md

M www/globs.md

+22 -22

		--- www/globs.md
		+++ www/globs.md
		@@ -1,50 +1,50 @@
1	1	# File Name Glob Patterns
2	2
3		-
4	3	A [glob pattern][glob] is a text expression that matches one or more
5		-file names using wild cards familiar to most users of a command line.
6		-For example, `*` is a glob that matches any name at all and
	4	+file names using wildcards familiar to most users of a command line.
	5	+For example, `*` is a glob that matches any name at all, and
7	6	`Readme.txt` is a glob that matches exactly one file. For purposes of
8		-Fossil's globs, a file name with a directory prefix is "just a string"
	7	+Fossil's globs, a complete path name is just a string,
9	8	and the globs do not apply any special meaning to the directory part
10		-of the name. Thus the glob `*` matches any name, including any
	9	+of the name. Thus, the glob `*` matches any name, including any
11	10	directory prefix, and `/` matches a name with _one or more_
12	11	directory components.
13	12
14		-A glob should not be confused with a [regular expression][regexp] (RE),
	13	+A glob should not be confused with a [regular expression][regexp] (RE)
15	14	even though they use some of the same special characters for similar
16		-purposes, because [they are not fully compatible][greinc] pattern
	15	+purposes. [They are not fully compatible][greinc] pattern
17	16	matching languages. Fossil uses globs when matching file names with the
18	17	settings described in this document, not REs.
19	18
20	19	[glob]: https://en.wikipedia.org/wiki/Glob_(programming)
21	20	[greinc]: https://unix.stackexchange.com/a/57958/138
22	21	[regexp]: https://en.wikipedia.org/wiki/Regular_expression
23	22
24		-These settings hold one or more file glob patterns to cause Fossil to
	23	+Fossil’s `*-glob` settings hold one or more patterns to cause Fossil to
25	24	give matching named files special treatment. Glob patterns are also
26	25	accepted in options to certain commands and as query parameters to
27		-certain Fossil UI web pages.
	26	+certain Fossil UI web pages. For consistency, settings such as
	27	+`empty-dirs` are parsed as a glob even though they aren’t then applied
	28	+as a glob since it allows [the same syntax rules](#syntax) to apply.
28	29
29	30	Where Fossil also accepts globs in commands, this handling may interact
30	31	with your OS’s command shell or its C runtime system, because they may
31	32	have their own glob pattern handling. We will detail such interactions
32	33	below.
33	34
34	35
35		-## Syntax
	36	+## <a id="syntax"></a>Syntax
36	37
37	38	Where Fossil accepts glob patterns, it will usually accept a list of
38		-such patterns, each individual pattern separated from the others
39		-by white space or commas. If a glob must contain white spaces or
40		-commas, it can be quoted with either single or double quotation marks.
41		-A list is said to match if any one glob in the list
42		-matches.
43		-
44		-A glob pattern matches a given file name if it successfully consumes and
45		-matches the entire name. Partial matches are failed matches.
	39	+individual patterns separated from the others
	40	+by whitespace or commas. Whitespace and
	41	+commas may be quoted with either single or double quotation marks.
	42	+A list matches a file when any pattern in that list matches.
	43	+
	44	+A pattern must consume and
	45	+match the entire file name to succeed. Partial matches are failed matches.
46	46
47	47	Most characters in a glob pattern consume a single character of the file
48	48	name and must match it exactly. For instance, “a” in a glob simply
49	49	matches the letter “a” in the file name unless it is inside a special
50	50	character sequence.
		@@ -61,11 +61,11 @@
61	61
62	62	Note that unlike [POSIX globs][pg], these special characters and
63	63	sequences are allowed to match `/` directory separators as well as the
64	64	initial `.` in the name of a hidden file or directory. This is because
65	65	Fossil file names are stored as complete path names. The distinction
66		-between file name and directory name is “below” Fossil in this sense.
	66	+between file name and directory name is “underneath” Fossil in this sense.
67	67
68	68	[pg]: https://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#tag_18_13
69	69
70	70	The bracket expressions above require some additional explanation:
71	71
		@@ -357,16 +357,16 @@
357	357
358	358	It bears repeating that the two glob patterns here are not interpreted
359	359	the same way when running this command from a subdirectory of the top
360	360	checkout directory as when running it at the top of the checkout tree.
361	361	If these files were in a subdirectory of the checkout tree called `doc`
362		-and that was your current working directory, the command would have to
363		-be:
	362	+and that was your current working directory, the command would instead
	363	+have to be:
364	364
365	365	$ fossil add --ignore "'doc/REALLY SECRET STUFF.txt'" READ*
366	366
367		-instead. The Fossil glob pattern still needs the `doc/` prefix because
	367	+The Fossil glob pattern still needs the `doc/` prefix because
368	368	Fossil always interprets glob patterns from the base of the checkout
369	369	directory, not from the current working directory as POSIX shells do.
370	370
371	371	When in doubt, use `fossil status` after running commands like the
372	372	above to make sure the right set of files were scheduled for insertion
373	373

	--- www/globs.md
	+++ www/globs.md
	@@ -1,50 +1,50 @@
1	# File Name Glob Patterns
2
3
4	A [glob pattern][glob] is a text expression that matches one or more
5	file names using wild cards familiar to most users of a command line.
6	For example, `*` is a glob that matches any name at all and
7	`Readme.txt` is a glob that matches exactly one file. For purposes of
8	Fossil's globs, a file name with a directory prefix is "just a string"
9	and the globs do not apply any special meaning to the directory part
10	of the name. Thus the glob `*` matches any name, including any
11	directory prefix, and `/` matches a name with _one or more_
12	directory components.
13
14	A glob should not be confused with a [regular expression][regexp] (RE),
15	even though they use some of the same special characters for similar
16	purposes, because [they are not fully compatible][greinc] pattern
17	matching languages. Fossil uses globs when matching file names with the
18	settings described in this document, not REs.
19
20	[glob]: https://en.wikipedia.org/wiki/Glob_(programming)
21	[greinc]: https://unix.stackexchange.com/a/57958/138
22	[regexp]: https://en.wikipedia.org/wiki/Regular_expression
23
24	These settings hold one or more file glob patterns to cause Fossil to
25	give matching named files special treatment. Glob patterns are also
26	accepted in options to certain commands and as query parameters to
27	certain Fossil UI web pages.


28
29	Where Fossil also accepts globs in commands, this handling may interact
30	with your OS’s command shell or its C runtime system, because they may
31	have their own glob pattern handling. We will detail such interactions
32	below.
33
34
35	## Syntax
36
37	Where Fossil accepts glob patterns, it will usually accept a list of
38	such patterns, each individual pattern separated from the others
39	by white space or commas. If a glob must contain white spaces or
40	commas, it can be quoted with either single or double quotation marks.
41	A list is said to match if any one glob in the list
42	matches.
43
44	A glob pattern matches a given file name if it successfully consumes and
45	matches the entire name. Partial matches are failed matches.
46
47	Most characters in a glob pattern consume a single character of the file
48	name and must match it exactly. For instance, “a” in a glob simply
49	matches the letter “a” in the file name unless it is inside a special
50	character sequence.
	@@ -61,11 +61,11 @@
61
62	Note that unlike [POSIX globs][pg], these special characters and
63	sequences are allowed to match `/` directory separators as well as the
64	initial `.` in the name of a hidden file or directory. This is because
65	Fossil file names are stored as complete path names. The distinction
66	between file name and directory name is “below” Fossil in this sense.
67
68	[pg]: https://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#tag_18_13
69
70	The bracket expressions above require some additional explanation:
71
	@@ -357,16 +357,16 @@
357
358	It bears repeating that the two glob patterns here are not interpreted
359	the same way when running this command from a subdirectory of the top
360	checkout directory as when running it at the top of the checkout tree.
361	If these files were in a subdirectory of the checkout tree called `doc`
362	and that was your current working directory, the command would have to
363	be:
364
365	$ fossil add --ignore "'doc/REALLY SECRET STUFF.txt'" READ*
366
367	instead. The Fossil glob pattern still needs the `doc/` prefix because
368	Fossil always interprets glob patterns from the base of the checkout
369	directory, not from the current working directory as POSIX shells do.
370
371	When in doubt, use `fossil status` after running commands like the
372	above to make sure the right set of files were scheduled for insertion
373

	--- www/globs.md
	+++ www/globs.md
	@@ -1,50 +1,50 @@
1	# File Name Glob Patterns
2

3	A [glob pattern][glob] is a text expression that matches one or more
4	file names using wildcards familiar to most users of a command line.
5	For example, `*` is a glob that matches any name at all, and
6	`Readme.txt` is a glob that matches exactly one file. For purposes of
7	Fossil's globs, a complete path name is just a string,
8	and the globs do not apply any special meaning to the directory part
9	of the name. Thus, the glob `*` matches any name, including any
10	directory prefix, and `/` matches a name with _one or more_
11	directory components.
12
13	A glob should not be confused with a [regular expression][regexp] (RE)
14	even though they use some of the same special characters for similar
15	purposes. [They are not fully compatible][greinc] pattern
16	matching languages. Fossil uses globs when matching file names with the
17	settings described in this document, not REs.
18
19	[glob]: https://en.wikipedia.org/wiki/Glob_(programming)
20	[greinc]: https://unix.stackexchange.com/a/57958/138
21	[regexp]: https://en.wikipedia.org/wiki/Regular_expression
22
23	Fossil’s `*-glob` settings hold one or more patterns to cause Fossil to
24	give matching named files special treatment. Glob patterns are also
25	accepted in options to certain commands and as query parameters to
26	certain Fossil UI web pages. For consistency, settings such as
27	`empty-dirs` are parsed as a glob even though they aren’t then applied
28	as a glob since it allows [the same syntax rules](#syntax) to apply.
29
30	Where Fossil also accepts globs in commands, this handling may interact
31	with your OS’s command shell or its C runtime system, because they may
32	have their own glob pattern handling. We will detail such interactions
33	below.
34
35
36	## <a id="syntax"></a>Syntax
37
38	Where Fossil accepts glob patterns, it will usually accept a list of
39	individual patterns separated from the others
40	by whitespace or commas. Whitespace and
41	commas may be quoted with either single or double quotation marks.
42	A list matches a file when any pattern in that list matches.
43
44	A pattern must consume and
45	match the entire file name to succeed. Partial matches are failed matches.

46
47	Most characters in a glob pattern consume a single character of the file
48	name and must match it exactly. For instance, “a” in a glob simply
49	matches the letter “a” in the file name unless it is inside a special
50	character sequence.
	@@ -61,11 +61,11 @@
61
62	Note that unlike [POSIX globs][pg], these special characters and
63	sequences are allowed to match `/` directory separators as well as the
64	initial `.` in the name of a hidden file or directory. This is because
65	Fossil file names are stored as complete path names. The distinction
66	between file name and directory name is “underneath” Fossil in this sense.
67
68	[pg]: https://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#tag_18_13
69
70	The bracket expressions above require some additional explanation:
71
	@@ -357,16 +357,16 @@
357
358	It bears repeating that the two glob patterns here are not interpreted
359	the same way when running this command from a subdirectory of the top
360	checkout directory as when running it at the top of the checkout tree.
361	If these files were in a subdirectory of the checkout tree called `doc`
362	and that was your current working directory, the command would instead
363	have to be:
364
365	$ fossil add --ignore "'doc/REALLY SECRET STUFF.txt'" READ*
366
367	The Fossil glob pattern still needs the `doc/` prefix because
368	Fossil always interprets glob patterns from the base of the checkout
369	directory, not from the current working directory as POSIX shells do.
370
371	When in doubt, use `fossil status` after running commands like the
372	above to make sure the right set of files were scheduled for insertion
373

Fossil SCM

Keyboard Shortcuts