Fossil SCM
Add some hints about translating from .gitignore to ignore-glob. I only scratched the surface: this could easily become the subject of a book.
Commit
ddea92ad417f2afb83e1fc9f523752a9644ecbcd595918377126ebb785b8ee71
Parent
daf2ada2bff0fc3…
1 file changed
+73
+73
| --- www/globs.md | ||
| +++ www/globs.md | ||
| @@ -308,10 +308,83 @@ | ||
| 308 | 308 | fossil setting crlf-glob '*' |
| 309 | 309 | |
| 310 | 310 | also works. Here the single quotes are unneeded since no white space |
| 311 | 311 | is mentioned in the pattern, but do no harm. The GLOB still matches |
| 312 | 312 | all the files. |
| 313 | + | |
| 314 | + | |
| 315 | +## Converting `.gitignore` to `ignore-glob` | |
| 316 | + | |
| 317 | +Many other version control systems handle the specific case of | |
| 318 | +ignoring certain files differently from fossil: they have you create | |
| 319 | +individual "ignore" files in each folder, which specify things ignored | |
| 320 | +in that folder and below. Usually some form of glob patterns are used | |
| 321 | +in those files, but the details differ from fossil. | |
| 322 | + | |
| 323 | +In many simple cases, you can just store a top level "ignore" file in | |
| 324 | +`.fossil-settings/ignore-glob`. But as usual, there will be lots of | |
| 325 | +edge cases. | |
| 326 | + | |
| 327 | +[Git has a rich collection of ignore files][gitignore] which | |
| 328 | +accumulate rules that affect the current command. There are global | |
| 329 | +files, per-user files, per workspace unmanaged files, and fully | |
| 330 | +version controlled files. Some of the files used have no set name, but | |
| 331 | +are called out in configuration files. | |
| 332 | + | |
| 333 | +[gitignore]: https://git-scm.com/docs/gitignore | |
| 334 | + | |
| 335 | +In contrast, fossil has a global setting and a local setting, but the local setting | |
| 336 | +overrides the global rather than extending it. Similarly, a fossil | |
| 337 | +command's `--ignore` option replaces the `ignore-glob` setting rather | |
| 338 | +than extending it. | |
| 339 | + | |
| 340 | +With that in mind, translating a `.gitignore` file into | |
| 341 | +`.fossil-settings/ignore-glob` may be possible in many cases. Here are | |
| 342 | +some of features of `.gitignore` and comments on how they relate to | |
| 343 | +fossil: | |
| 344 | + | |
| 345 | + * "A blank line matches no files..." is the same in fossil. | |
| 346 | + * "A line starting with # serves as a comment...." not in fossil. | |
| 347 | + * "Trailing spaces are ignored unless they are quoted..." is similar | |
| 348 | + in fossil. All whitespace before and after a glob is trimmed in | |
| 349 | + fossil unless quoted with single or double quotes. Git uses | |
| 350 | + backslash quoting instead, which fossil does not. | |
| 351 | + * "An optional prefix "!" which negates the pattern..." not in | |
| 352 | + fossil. | |
| 353 | + * Git's globs are relative to the location of the `.gitignore` file; | |
| 354 | + fossil's globs are relative to the root of the workspace. | |
| 355 | + * Git's globs and fossil's globs treat directory separators | |
| 356 | + differently. Git includes a notation for zero or more directories | |
| 357 | + that is not needed in fossil. | |
| 358 | + | |
| 359 | +### Example | |
| 360 | + | |
| 361 | +In a project with source and documentation: | |
| 362 | + | |
| 363 | + work | |
| 364 | + +-- doc | |
| 365 | + +-- src | |
| 366 | + | |
| 367 | +The file `doc/.gitignore` might contain: | |
| 368 | + | |
| 369 | + # Finished documents by pandoc via LaTeX | |
| 370 | ||
| 371 | + # Intermediate files | |
| 372 | + *.tex | |
| 373 | + *.toc | |
| 374 | + *.log | |
| 375 | + *.out | |
| 376 | + *.tmp | |
| 377 | + | |
| 378 | +Entries in `.fossil-settings/ignore-glob` with similar effect, also | |
| 379 | +limited to the `doc` folder: | |
| 380 | + | |
| 381 | + doc/*.pdf | |
| 382 | + doc/*.tex, doc/*.toc, doc/*.log, doc/*.out, doc/*.tmp | |
| 383 | + | |
| 384 | + | |
| 385 | + | |
| 313 | 386 | |
| 314 | 387 | |
| 315 | 388 | ## Implementation and References |
| 316 | 389 | |
| 317 | 390 | Most of the implementation of glob pattern handling in fossil is found |
| 318 | 391 |
| --- www/globs.md | |
| +++ www/globs.md | |
| @@ -308,10 +308,83 @@ | |
| 308 | fossil setting crlf-glob '*' |
| 309 | |
| 310 | also works. Here the single quotes are unneeded since no white space |
| 311 | is mentioned in the pattern, but do no harm. The GLOB still matches |
| 312 | all the files. |
| 313 | |
| 314 | |
| 315 | ## Implementation and References |
| 316 | |
| 317 | Most of the implementation of glob pattern handling in fossil is found |
| 318 |
| --- www/globs.md | |
| +++ www/globs.md | |
| @@ -308,10 +308,83 @@ | |
| 308 | fossil setting crlf-glob '*' |
| 309 | |
| 310 | also works. Here the single quotes are unneeded since no white space |
| 311 | is mentioned in the pattern, but do no harm. The GLOB still matches |
| 312 | all the files. |
| 313 | |
| 314 | |
| 315 | ## Converting `.gitignore` to `ignore-glob` |
| 316 | |
| 317 | Many other version control systems handle the specific case of |
| 318 | ignoring certain files differently from fossil: they have you create |
| 319 | individual "ignore" files in each folder, which specify things ignored |
| 320 | in that folder and below. Usually some form of glob patterns are used |
| 321 | in those files, but the details differ from fossil. |
| 322 | |
| 323 | In many simple cases, you can just store a top level "ignore" file in |
| 324 | `.fossil-settings/ignore-glob`. But as usual, there will be lots of |
| 325 | edge cases. |
| 326 | |
| 327 | [Git has a rich collection of ignore files][gitignore] which |
| 328 | accumulate rules that affect the current command. There are global |
| 329 | files, per-user files, per workspace unmanaged files, and fully |
| 330 | version controlled files. Some of the files used have no set name, but |
| 331 | are called out in configuration files. |
| 332 | |
| 333 | [gitignore]: https://git-scm.com/docs/gitignore |
| 334 | |
| 335 | In contrast, fossil has a global setting and a local setting, but the local setting |
| 336 | overrides the global rather than extending it. Similarly, a fossil |
| 337 | command's `--ignore` option replaces the `ignore-glob` setting rather |
| 338 | than extending it. |
| 339 | |
| 340 | With that in mind, translating a `.gitignore` file into |
| 341 | `.fossil-settings/ignore-glob` may be possible in many cases. Here are |
| 342 | some of features of `.gitignore` and comments on how they relate to |
| 343 | fossil: |
| 344 | |
| 345 | * "A blank line matches no files..." is the same in fossil. |
| 346 | * "A line starting with # serves as a comment...." not in fossil. |
| 347 | * "Trailing spaces are ignored unless they are quoted..." is similar |
| 348 | in fossil. All whitespace before and after a glob is trimmed in |
| 349 | fossil unless quoted with single or double quotes. Git uses |
| 350 | backslash quoting instead, which fossil does not. |
| 351 | * "An optional prefix "!" which negates the pattern..." not in |
| 352 | fossil. |
| 353 | * Git's globs are relative to the location of the `.gitignore` file; |
| 354 | fossil's globs are relative to the root of the workspace. |
| 355 | * Git's globs and fossil's globs treat directory separators |
| 356 | differently. Git includes a notation for zero or more directories |
| 357 | that is not needed in fossil. |
| 358 | |
| 359 | ### Example |
| 360 | |
| 361 | In a project with source and documentation: |
| 362 | |
| 363 | work |
| 364 | +-- doc |
| 365 | +-- src |
| 366 | |
| 367 | The file `doc/.gitignore` might contain: |
| 368 | |
| 369 | # Finished documents by pandoc via LaTeX |
| 370 | |
| 371 | # Intermediate files |
| 372 | *.tex |
| 373 | *.toc |
| 374 | *.log |
| 375 | *.out |
| 376 | *.tmp |
| 377 | |
| 378 | Entries in `.fossil-settings/ignore-glob` with similar effect, also |
| 379 | limited to the `doc` folder: |
| 380 | |
| 381 | doc/*.pdf |
| 382 | doc/*.tex, doc/*.toc, doc/*.log, doc/*.out, doc/*.tmp |
| 383 | |
| 384 | |
| 385 | |
| 386 | |
| 387 | |
| 388 | ## Implementation and References |
| 389 | |
| 390 | Most of the implementation of glob pattern handling in fossil is found |
| 391 |