Fossil SCM
Assorted improvements to globs.md, especially to the discussion of * expansion on Windows vs POSIX.
Commit
bb292b64ae7358911fdc1fd2120270050f239496a6e7f3a1954474fd72999792
Parent
21929d37a36bce7…
1 file changed
+42
-25
+42
-25
| --- www/globs.md | ||
| +++ www/globs.md | ||
| @@ -381,81 +381,98 @@ | ||
| 381 | 381 | * whether the command is built against a runtime system that does this |
| 382 | 382 | at all |
| 383 | 383 | * whether the Fossil command is being run from a file named `*.BAT` vs |
| 384 | 384 | being named `*.CMD` |
| 385 | 385 | |
| 386 | -These factors also affect how a program like `fossil.exe` interprets | |
| 387 | -quotation marks on its command line. | |
| 388 | - | |
| 389 | -The fifth item above does not apply to `fossil.exe` when built with | |
| 390 | -typical tool chains, but we will see an example below where the exception | |
| 391 | -applies in a way that affects how Fossil interprets the glob pattern. | |
| 386 | +Usually (but not always!) the C runtime library that your `fossil.exe` | |
| 387 | +executable is built against does this glob expansion on Windows so the | |
| 388 | +program proper does not have to. This may then interact with the way the | |
| 389 | +Windows command shell you’re using handles argument quoting. Because of | |
| 390 | +these differences, it is common to find perfectly valid Fossil command | |
| 391 | +examples that were written and tested on a POSIX system which then fail | |
| 392 | +when tried on Windows. | |
| 392 | 393 | |
| 393 | 394 | The most common problem is figuring out how to get a glob pattern passed |
| 394 | 395 | on the command line into `fossil.exe` without it being expanded by the C |
| 395 | 396 | runtime library that your particular Fossil executable is linked to, |
| 396 | 397 | which tries to act like [the POSIX systems described above](#posix). Windows is |
| 397 | 398 | not strongly governed by POSIX, so it has not historically hewed closely |
| 398 | 399 | to its strictures. |
| 399 | 400 | |
| 400 | 401 | For example, consider how you would set `crlf-glob` to `*` in order to |
| 401 | -disable Fossil's "looks like a binary file" checks. The naïve | |
| 402 | -approach will not work: | |
| 402 | +get normal Windows text files with CR+LF line endings past Fossil's | |
| 403 | +"looks like a binary file" check. The naïve approach will not work: | |
| 403 | 404 | |
| 404 | 405 | C:\...> fossil setting crlf-glob * |
| 405 | 406 | |
| 406 | 407 | The C runtime library will expand that to the list of all files in the |
| 407 | 408 | current directory, which will probably cause a Fossil error because |
| 408 | 409 | Fossil expects either nothing or option flags after the setting's new |
| 409 | -value. | |
| 410 | +value, not a list of file names. (To be fair, the same thing will happen | |
| 411 | +on POSIX systems, only at the shell level, before `.../bin/fossil` even | |
| 412 | +gets run by the shell.) | |
| 410 | 413 | |
| 411 | 414 | Let's try again: |
| 412 | 415 | |
| 413 | 416 | C:\...> fossil setting crlf-glob '*' |
| 414 | 417 | |
| 415 | -That may or may not work. Either `'*'` or `*` needs to be passed through | |
| 416 | -to Fossil untouched for this to do what you expect, which may or may not | |
| 417 | -happen, depending on the factors listed above. | |
| 418 | +Quoting the argument like that will work reliably on POSIX, but it may | |
| 419 | +or may not work on Windows. If your Windows command shell interprets the | |
| 420 | +quotes, it means `fossil.exe` will see only the bare `*` so the C | |
| 421 | +runtime library it is linked to will likely expand the list of files in | |
| 422 | +the current directory before the `setting` command gets a chance to | |
| 423 | +parse the command line arguments, causing the same failure as above. | |
| 424 | +This alternative only works if you’re using a Windows command shell that | |
| 425 | +passes the quotes through to the executable *and* you have linked Fossil | |
| 426 | +to a C runtime library that interprets the quotes properly itself, | |
| 427 | +resulting in a bare `*` getting clear down to Fossil’s `setting` command | |
| 428 | +parser. | |
| 418 | 429 | |
| 419 | 430 | An approach that *will* work reliably is: |
| 420 | 431 | |
| 421 | 432 | C:\...> echo * | fossil setting crlf-glob --args - |
| 422 | 433 | |
| 423 | -This works because the built-in command `echo` does not expand its | |
| 424 | -arguments, and the `--args -` option makes it read further command | |
| 425 | -arguments from Fossil's standard input, which is connected to the output | |
| 434 | +This works because the built-in Windows command `echo` does not expand its | |
| 435 | +arguments, and the `--args -` option makes Fossil read further command | |
| 436 | +arguments from its standard input, which is connected to the output | |
| 426 | 437 | of `echo` by the pipe. (`-` is a common Unix convention meaning |
| 427 | -"standard input.") A [batch script][fng.cmd] to automate this trick was | |
| 428 | -posted on the (now inactive) Fossil Mailing List. | |
| 438 | +"standard input," which Fossil obeys.) A [batch script][fng.cmd] to automate this trick was | |
| 439 | +posted on the now-inactive Fossil Mailing List. | |
| 429 | 440 | |
| 430 | 441 | [fng.cmd]: https://www.mail-archive.com/[email protected]/msg25099.html |
| 431 | 442 | |
| 432 | -Another (usually) correct approach is: | |
| 443 | +(Ironically, this method will *not* work on POSIX systems because it is | |
| 444 | +not up to the command to expand globs. The shell will expand the `*` in | |
| 445 | +the `echo` command, so the list of file names will be passed to the | |
| 446 | +`fossil` standard input, just as with the first example above!) | |
| 447 | + | |
| 448 | +Another (usually) correct approach which will work on both Windows and | |
| 449 | +POSIX systems: | |
| 433 | 450 | |
| 434 | 451 | C:\...> fossil setting crlf-glob *, |
| 435 | 452 | |
| 436 | 453 | This works because the trailing comma prevents the glob pattern from |
| 437 | 454 | matching any files, unless you happen to have files named with a |
| 438 | 455 | trailing comma in the current directory. If the pattern matches no |
| 439 | 456 | files, it is passed into Fossil's `main()` function as-is by the C |
| 440 | 457 | runtime system. Since Fossil uses commas to separate multiple glob |
| 441 | -patterns, this means "all files at the root of the Fossil checkout | |
| 442 | -directory and nothing else." | |
| 458 | +patterns, this means "all files from the root of the Fossil checkout | |
| 459 | +directory downward and nothing else," which is of course equivalent to | |
| 460 | +"all managed files in this repository," our original goal. | |
| 443 | 461 | |
| 444 | 462 | |
| 445 | 463 | ## Experimenting |
| 446 | 464 | |
| 447 | 465 | To preview the effects of command line glob pattern expansion for |
| 448 | 466 | various glob patterns (unquoted, quoted, comma-terminated), for any |
| 449 | -combination of command shell and Fossil executable, on both POSIX | |
| 450 | -systems and Windows, the [`test-echo`][] command can be injected as | |
| 451 | -the first argument on the Fossil command line: | |
| 467 | +combination of command shell, OS, C run time, and Fossil version, | |
| 468 | +preceed the command you want to test with [`test-echo`][] like so: | |
| 452 | 469 | |
| 453 | 470 | $ fossil test-echo setting crlf-glob "*" |
| 454 | - $ echo * | fossil test-echo setting crlf-glob --args - | |
| 471 | + C:\> echo * | fossil test-echo setting crlf-glob --args - | |
| 455 | 472 | |
| 456 | -Moreover, the [`test-glob`][] command is handy to test if a string | |
| 473 | +The [`test-glob`][] command is also handy to test if a string | |
| 457 | 474 | matches a glob pattern. |
| 458 | 475 | |
| 459 | 476 | [`test-echo`]: /help?cmd=test-echo |
| 460 | 477 | [`test-glob`]: /help?cmd=test-glob |
| 461 | 478 | |
| 462 | 479 |
| --- www/globs.md | |
| +++ www/globs.md | |
| @@ -381,81 +381,98 @@ | |
| 381 | * whether the command is built against a runtime system that does this |
| 382 | at all |
| 383 | * whether the Fossil command is being run from a file named `*.BAT` vs |
| 384 | being named `*.CMD` |
| 385 | |
| 386 | These factors also affect how a program like `fossil.exe` interprets |
| 387 | quotation marks on its command line. |
| 388 | |
| 389 | The fifth item above does not apply to `fossil.exe` when built with |
| 390 | typical tool chains, but we will see an example below where the exception |
| 391 | applies in a way that affects how Fossil interprets the glob pattern. |
| 392 | |
| 393 | The most common problem is figuring out how to get a glob pattern passed |
| 394 | on the command line into `fossil.exe` without it being expanded by the C |
| 395 | runtime library that your particular Fossil executable is linked to, |
| 396 | which tries to act like [the POSIX systems described above](#posix). Windows is |
| 397 | not strongly governed by POSIX, so it has not historically hewed closely |
| 398 | to its strictures. |
| 399 | |
| 400 | For example, consider how you would set `crlf-glob` to `*` in order to |
| 401 | disable Fossil's "looks like a binary file" checks. The naïve |
| 402 | approach will not work: |
| 403 | |
| 404 | C:\...> fossil setting crlf-glob * |
| 405 | |
| 406 | The C runtime library will expand that to the list of all files in the |
| 407 | current directory, which will probably cause a Fossil error because |
| 408 | Fossil expects either nothing or option flags after the setting's new |
| 409 | value. |
| 410 | |
| 411 | Let's try again: |
| 412 | |
| 413 | C:\...> fossil setting crlf-glob '*' |
| 414 | |
| 415 | That may or may not work. Either `'*'` or `*` needs to be passed through |
| 416 | to Fossil untouched for this to do what you expect, which may or may not |
| 417 | happen, depending on the factors listed above. |
| 418 | |
| 419 | An approach that *will* work reliably is: |
| 420 | |
| 421 | C:\...> echo * | fossil setting crlf-glob --args - |
| 422 | |
| 423 | This works because the built-in command `echo` does not expand its |
| 424 | arguments, and the `--args -` option makes it read further command |
| 425 | arguments from Fossil's standard input, which is connected to the output |
| 426 | of `echo` by the pipe. (`-` is a common Unix convention meaning |
| 427 | "standard input.") A [batch script][fng.cmd] to automate this trick was |
| 428 | posted on the (now inactive) Fossil Mailing List. |
| 429 | |
| 430 | [fng.cmd]: https://www.mail-archive.com/[email protected]/msg25099.html |
| 431 | |
| 432 | Another (usually) correct approach is: |
| 433 | |
| 434 | C:\...> fossil setting crlf-glob *, |
| 435 | |
| 436 | This works because the trailing comma prevents the glob pattern from |
| 437 | matching any files, unless you happen to have files named with a |
| 438 | trailing comma in the current directory. If the pattern matches no |
| 439 | files, it is passed into Fossil's `main()` function as-is by the C |
| 440 | runtime system. Since Fossil uses commas to separate multiple glob |
| 441 | patterns, this means "all files at the root of the Fossil checkout |
| 442 | directory and nothing else." |
| 443 | |
| 444 | |
| 445 | ## Experimenting |
| 446 | |
| 447 | To preview the effects of command line glob pattern expansion for |
| 448 | various glob patterns (unquoted, quoted, comma-terminated), for any |
| 449 | combination of command shell and Fossil executable, on both POSIX |
| 450 | systems and Windows, the [`test-echo`][] command can be injected as |
| 451 | the first argument on the Fossil command line: |
| 452 | |
| 453 | $ fossil test-echo setting crlf-glob "*" |
| 454 | $ echo * | fossil test-echo setting crlf-glob --args - |
| 455 | |
| 456 | Moreover, the [`test-glob`][] command is handy to test if a string |
| 457 | matches a glob pattern. |
| 458 | |
| 459 | [`test-echo`]: /help?cmd=test-echo |
| 460 | [`test-glob`]: /help?cmd=test-glob |
| 461 | |
| 462 |
| --- www/globs.md | |
| +++ www/globs.md | |
| @@ -381,81 +381,98 @@ | |
| 381 | * whether the command is built against a runtime system that does this |
| 382 | at all |
| 383 | * whether the Fossil command is being run from a file named `*.BAT` vs |
| 384 | being named `*.CMD` |
| 385 | |
| 386 | Usually (but not always!) the C runtime library that your `fossil.exe` |
| 387 | executable is built against does this glob expansion on Windows so the |
| 388 | program proper does not have to. This may then interact with the way the |
| 389 | Windows command shell you’re using handles argument quoting. Because of |
| 390 | these differences, it is common to find perfectly valid Fossil command |
| 391 | examples that were written and tested on a POSIX system which then fail |
| 392 | when tried on Windows. |
| 393 | |
| 394 | The most common problem is figuring out how to get a glob pattern passed |
| 395 | on the command line into `fossil.exe` without it being expanded by the C |
| 396 | runtime library that your particular Fossil executable is linked to, |
| 397 | which tries to act like [the POSIX systems described above](#posix). Windows is |
| 398 | not strongly governed by POSIX, so it has not historically hewed closely |
| 399 | to its strictures. |
| 400 | |
| 401 | For example, consider how you would set `crlf-glob` to `*` in order to |
| 402 | get normal Windows text files with CR+LF line endings past Fossil's |
| 403 | "looks like a binary file" check. The naïve approach will not work: |
| 404 | |
| 405 | C:\...> fossil setting crlf-glob * |
| 406 | |
| 407 | The C runtime library will expand that to the list of all files in the |
| 408 | current directory, which will probably cause a Fossil error because |
| 409 | Fossil expects either nothing or option flags after the setting's new |
| 410 | value, not a list of file names. (To be fair, the same thing will happen |
| 411 | on POSIX systems, only at the shell level, before `.../bin/fossil` even |
| 412 | gets run by the shell.) |
| 413 | |
| 414 | Let's try again: |
| 415 | |
| 416 | C:\...> fossil setting crlf-glob '*' |
| 417 | |
| 418 | Quoting the argument like that will work reliably on POSIX, but it may |
| 419 | or may not work on Windows. If your Windows command shell interprets the |
| 420 | quotes, it means `fossil.exe` will see only the bare `*` so the C |
| 421 | runtime library it is linked to will likely expand the list of files in |
| 422 | the current directory before the `setting` command gets a chance to |
| 423 | parse the command line arguments, causing the same failure as above. |
| 424 | This alternative only works if you’re using a Windows command shell that |
| 425 | passes the quotes through to the executable *and* you have linked Fossil |
| 426 | to a C runtime library that interprets the quotes properly itself, |
| 427 | resulting in a bare `*` getting clear down to Fossil’s `setting` command |
| 428 | parser. |
| 429 | |
| 430 | An approach that *will* work reliably is: |
| 431 | |
| 432 | C:\...> echo * | fossil setting crlf-glob --args - |
| 433 | |
| 434 | This works because the built-in Windows command `echo` does not expand its |
| 435 | arguments, and the `--args -` option makes Fossil read further command |
| 436 | arguments from its standard input, which is connected to the output |
| 437 | of `echo` by the pipe. (`-` is a common Unix convention meaning |
| 438 | "standard input," which Fossil obeys.) A [batch script][fng.cmd] to automate this trick was |
| 439 | posted on the now-inactive Fossil Mailing List. |
| 440 | |
| 441 | [fng.cmd]: https://www.mail-archive.com/[email protected]/msg25099.html |
| 442 | |
| 443 | (Ironically, this method will *not* work on POSIX systems because it is |
| 444 | not up to the command to expand globs. The shell will expand the `*` in |
| 445 | the `echo` command, so the list of file names will be passed to the |
| 446 | `fossil` standard input, just as with the first example above!) |
| 447 | |
| 448 | Another (usually) correct approach which will work on both Windows and |
| 449 | POSIX systems: |
| 450 | |
| 451 | C:\...> fossil setting crlf-glob *, |
| 452 | |
| 453 | This works because the trailing comma prevents the glob pattern from |
| 454 | matching any files, unless you happen to have files named with a |
| 455 | trailing comma in the current directory. If the pattern matches no |
| 456 | files, it is passed into Fossil's `main()` function as-is by the C |
| 457 | runtime system. Since Fossil uses commas to separate multiple glob |
| 458 | patterns, this means "all files from the root of the Fossil checkout |
| 459 | directory downward and nothing else," which is of course equivalent to |
| 460 | "all managed files in this repository," our original goal. |
| 461 | |
| 462 | |
| 463 | ## Experimenting |
| 464 | |
| 465 | To preview the effects of command line glob pattern expansion for |
| 466 | various glob patterns (unquoted, quoted, comma-terminated), for any |
| 467 | combination of command shell, OS, C run time, and Fossil version, |
| 468 | preceed the command you want to test with [`test-echo`][] like so: |
| 469 | |
| 470 | $ fossil test-echo setting crlf-glob "*" |
| 471 | C:\> echo * | fossil test-echo setting crlf-glob --args - |
| 472 | |
| 473 | The [`test-glob`][] command is also handy to test if a string |
| 474 | matches a glob pattern. |
| 475 | |
| 476 | [`test-echo`]: /help?cmd=test-echo |
| 477 | [`test-glob`]: /help?cmd=test-glob |
| 478 | |
| 479 |