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

83 lines
2.6 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
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
fileset, revset, templater: add support for single-quoted raw string literals Since fileset/revset/template expressions are specified as command-line arguments, it's sometimes convenient to use single quotes instead of double quotes. Various scripting languages parse single-quoted strings in various ways, but I choose the TOML rule because it's simple and practically useful. TOML is our config language, so copying the TOML syntax would be less surprising than borrowing it from another language. https://github.com/toml-lang/toml/issues/188
2024-04-17 12:17:40 +00:00
names passed to these commands [must be quoted][string-literals] 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:
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
* `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: parse glob characters as identifier It's inconvenient that we have to quote glob patterns as 'glob:"*.rs"'. Suppose filesets are usually specified in shell, it's better to allow unquoted strings if possible. This change also means we'll probably abandon #2101 "make the parsing of string arguments stricter." Note that we can no longer introduce ? operator or [] subscript syntax in filesets. Closes #4053
2024-07-17 12:18:41 +00:00
Glob characters aren't considered meta characters, but shell quotes are still
required:
* `jj diff '~glob:**/*.rs'`
fileset, revset, templater: add support for single-quoted raw string literals Since fileset/revset/template expressions are specified as command-line arguments, it's sometimes convenient to use single quotes instead of double quotes. Various scripting languages parse single-quoted strings in various ways, but I choose the TOML rule because it's simple and practically useful. TOML is our config language, so copying the TOML syntax would be less surprising than borrowing it from another language. https://github.com/toml-lang/toml/issues/188
2024-04-17 12:17:40 +00:00
[string-literals]: templates.md#string-literals
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.
docs: sort list of operators in order of binding strengths We can add a separate precedence/associativity table, but I think the ordered list is good enough. Nullary :: and .. have no binding, but inserted after the infix versions for brevity.
2024-06-06 07:19:26 +00:00
* `~x`: Matches everything but `x`.
fileset: implement name resolution stage, add all()/none() functions #3239
2024-04-07 12:14:17 +00:00
* `x & y`: Matches both `x` and `y`.
* `x ~ y`: Matches `x` but not `y`.
docs: sort list of operators in order of binding strengths We can add a separate precedence/associativity table, but I think the ordered list is good enough. Nullary :: and .. have no binding, but inserted after the infix versions for brevity.
2024-06-06 07:19:26 +00:00
* `x | y`: Matches either `x` or `y` (or both).
(listed in order of binding strengths)
fileset: implement name resolution stage, add all()/none() functions #3239
2024-04-07 12:14:17 +00:00
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.
```
docs: replace `jj files` -> `jj file list` `jj files` is now deprecated
2024-06-25 03:35:09 +00:00
jj file list 'src ~ glob:"**/*.rs"'
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
```
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