mirrors/jj
1
0
Fork 1
mirror of https://github.com/martinvonz/jj.git synced 2024-11-24 15:18:53 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 11
jj/docs/filesets.md

81 lines
2.5 KiB
Markdown
Raw Normal View History

fileset: add basic pattern parsing functions Naming convention is described in FilePattern::from_str_kind(). It's based on Mercurial's pattern prefixes, but hopefully fixes some inconsistencies. https://github.com/martinvonz/jj/issues/2915#issuecomment-1956401114 #3239
2024-04-05 12:39:59 +00:00
# Filesets
Jujutsu supports a functional language for selecting a set of files.
Expressions in this language are called "filesets" (the idea comes from
[Mercurial](https://repo.mercurial-scm.org/hg/help/filesets)). The language
fileset: implement name resolution stage, add all()/none() functions #3239
2024-04-07 12:14:17 +00:00
consists of file patterns, operators, and functions.
fileset: add basic pattern parsing functions Naming convention is described in FilePattern::from_str_kind(). It's based on Mercurial's pattern prefixes, but hopefully fixes some inconsistencies. https://github.com/martinvonz/jj/issues/2915#issuecomment-1956401114 #3239
2024-04-05 12:39:59 +00:00
cli: add ui.allow-filesets to experiment with fileset/pattern syntax The pattern syntax could be enabled unconditionally, but I want to fully replace the ad-hoc pattern parsing function.
2024-04-11 09:04:38 +00:00
**Filesets support is still experimental.** It can be enabled by
`ui.allow-filesets`.
```toml
ui.allow-filesets = true
```
fileset: fall back to bare pattern/string if no operator-like character found While I like strict parsing, it's not uncommon that we have to deal with file names containing spaces, and doubly-quoted strings such as '"Foo Bar"' look ugly. So, this patch adds an exception that accepts top-level bare strings. This parsing rule is specific to command arguments, and won't be enabled when loading fileset aliases.
2024-04-10 09:47:56 +00:00
Many `jj` commands accept fileset expressions as positional arguments. File
names passed to these commands must be quoted if they contain whitespace or meta
characters. However, as a special case, quotes can be omitted if the expression
has no operators nor function calls. For example:
* `jj diff 'Foo Bar'` (shell quotes are required, but inner quotes are optional)
* `jj diff '~"Foo Bar"'` (both shell and inner quotes are required)
* `jj diff '"Foo(1)"'` (both shell and inner quotes are required)
fileset: add basic pattern parsing functions Naming convention is described in FilePattern::from_str_kind(). It's based on Mercurial's pattern prefixes, but hopefully fixes some inconsistencies. https://github.com/martinvonz/jj/issues/2915#issuecomment-1956401114 #3239
2024-04-05 12:39:59 +00:00
## File patterns
The following patterns are supported:
* `"path"`, `path` (the quotes are optional), or `cwd:"path"`: Matches
cwd-relative path prefix (file or files under directory recursively.)
* `cwd-file:"path"` or `file:"path"`: Matches cwd-relative file (or exact) path.
fileset: parse cwd/root-glob patterns Mercurial appears to resolve cwd-relative path first, so "glob:*.c" could be parsed as "**/*.c" if cwd was literally "**". It wouldn't practically matter, but isn't correct. Instead, jj's parser first splits glob into literal part and pattern. That's mainly because we want to parse the user input texts into type-safe objects, and (RepoPathBuf, glob::Pattern) pairs are the simplest ones. The current parser can't handle patterns like "foo/*/.." (= "foo" ?), and errors out. I believe this restriction is acceptable. Unlike literal paths, the 'glob:' pattern anchors to the whole file path. I don't think "prefix"-matching glob is useful, and making it the default would be rather confusing.
2024-04-14 02:33:55 +00:00
* `cwd-glob:"pattern"` or `glob:"pattern"`: Matches file paths with cwd-relative
Unix-style shell [wildcard `pattern`][glob]. For example, `glob:"*.c"` will
match all `.c` files in the current working directory non-recursively.
fileset: add basic pattern parsing functions Naming convention is described in FilePattern::from_str_kind(). It's based on Mercurial's pattern prefixes, but hopefully fixes some inconsistencies. https://github.com/martinvonz/jj/issues/2915#issuecomment-1956401114 #3239
2024-04-05 12:39:59 +00:00
* `root:"path"`: Matches workspace-relative path prefix (file or files under
directory recursively.)
* `root-file:"path"`: Matches workspace-relative file (or exact) path.
fileset: parse cwd/root-glob patterns Mercurial appears to resolve cwd-relative path first, so "glob:*.c" could be parsed as "**/*.c" if cwd was literally "**". It wouldn't practically matter, but isn't correct. Instead, jj's parser first splits glob into literal part and pattern. That's mainly because we want to parse the user input texts into type-safe objects, and (RepoPathBuf, glob::Pattern) pairs are the simplest ones. The current parser can't handle patterns like "foo/*/.." (= "foo" ?), and errors out. I believe this restriction is acceptable. Unlike literal paths, the 'glob:' pattern anchors to the whole file path. I don't think "prefix"-matching glob is useful, and making it the default would be rather confusing.
2024-04-14 02:33:55 +00:00
* `root-glob:"pattern"`: Matches file paths with workspace-relative Unix-style
shell [wildcard `pattern`][glob].
[glob]: https://docs.rs/glob/latest/glob/struct.Pattern.html
fileset: implement name resolution stage, add all()/none() functions #3239
2024-04-07 12:14:17 +00:00
## Operators
The following operators are supported. `x` and `y` below can be any fileset
expressions.
* `x & y`: Matches both `x` and `y`.
* `x | y`: Matches either `x` or `y` (or both).
* `x ~ y`: Matches `x` but not `y`.
* `~x`: Matches everything but `x`.
You can use parentheses to control evaluation order, such as `(x & y) | z` or
`x & (y | z)`.
## Functions
You can also specify patterns by using functions.
* `all()`: Matches everything.
* `none()`: Matches nothing.
cli: if enabled, parse path arguments as fileset expressions If this doesn't work out, maybe we can try one of these: a. fall back to bare file name if expression doesn't contain any operator-like characters (e.g. "f(x" is an error, but "f x" can be parsed as bare string) b. introduce command-line flag to opt in (e.g. -e FILESET) c. introduce pattern prefix to opt in (e.g. set:FILESET) Closes #3239, #2915, #2286
2024-04-08 07:43:18 +00:00
## Examples
Show diff excluding `Cargo.lock`.
```
jj diff '~Cargo.lock'
```
fileset: parse cwd/root-glob patterns Mercurial appears to resolve cwd-relative path first, so "glob:*.c" could be parsed as "**/*.c" if cwd was literally "**". It wouldn't practically matter, but isn't correct. Instead, jj's parser first splits glob into literal part and pattern. That's mainly because we want to parse the user input texts into type-safe objects, and (RepoPathBuf, glob::Pattern) pairs are the simplest ones. The current parser can't handle patterns like "foo/*/.." (= "foo" ?), and errors out. I believe this restriction is acceptable. Unlike literal paths, the 'glob:' pattern anchors to the whole file path. I don't think "prefix"-matching glob is useful, and making it the default would be rather confusing.
2024-04-14 02:33:55 +00:00
List files in `src` excluding Rust sources.
```
jj files 'src ~ glob:"**/*.rs"'
```
cli: if enabled, parse path arguments as fileset expressions If this doesn't work out, maybe we can try one of these: a. fall back to bare file name if expression doesn't contain any operator-like characters (e.g. "f(x" is an error, but "f x" can be parsed as bare string) b. introduce command-line flag to opt in (e.g. -e FILESET) c. introduce pattern prefix to opt in (e.g. set:FILESET) Closes #3239, #2915, #2286
2024-04-08 07:43:18 +00:00
Split a revision in two, putting `foo` into the second commit.
```
jj split '~foo'
```
Reference in a new issue Copy permalink