mirrors/jj
1
0
Fork 0
mirror of https://github.com/jj-vcs/jj.git synced 2025-12-23 06:01:01 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 1
jj/docs/filesets.md
Steve Klabnik 97c03ea8a3
Some checks are pending
binaries / Build binary artifacts (push) Waiting to run
Details
website / prerelease-docs-build-deploy (ubuntu-24.04) (push) Waiting to run
Details
Scorecards supply-chain security / Scorecards analysis (push) Waiting to run
Details
docs: clarify that some template parameters require literal strings 
Rename parameter type `String` to `StringLiteral` where methods require
a literal string known at parse time rather than a dynamic expression.
This makes the documentation faithful to the underlying code, which uses
`expect_string_literal()` and reports "Expected string literal" errors.

Add a new `StringLiteral` type section explaining the distinction.

Fixes #7068
2025-12-19 19:57:54 +00:00

3.3 KiB
Raw Permalink Blame History

Filesets

Jujutsu supports a functional language for selecting a set of files. Expressions in this language are called "filesets" (the idea comes from Mercurial). The language consists of file patterns, operators, and functions.

Quoting file names

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)

Glob characters aren't considered meta characters, but shell quotes are still required:

  • jj diff '~glob:**/*.rs'

File patterns

The following patterns are supported. In all cases, we do not mention any shell quoting that might be necessary, and the quotes around "path" are optional if the path has no special characters.

By default, "path" is parsed as a prefix-glob: pattern, which matches cwd-relative path prefix.

  • cwd:"path": Matches cwd-relative path prefix (file or files under directory recursively.)
  • file:"path" or cwd-file:"path": Matches cwd-relative file (or exact) path.
  • glob:"pattern" or cwd-glob:"pattern": Matches file paths with cwd-relative Unix-style shell wildcard pattern. For example, glob:"*.c" will match all .c files in the current working directory non-recursively.
  • prefix-glob:"pattern" or cwd-prefix-glob:"pattern": Like glob:, but also matches path prefix (file or files under directory recursively.) For example, prefix-glob:"*.d" is equivalent to glob:"*.d" | glob:"*.d/**".
  • root:"path": Matches workspace-relative path prefix (file or files under directory recursively.)
  • root-file:"path": Matches workspace-relative file (or exact) path.
  • root-glob:"pattern": Matches file paths with workspace-relative Unix-style shell wildcard pattern.
  • root-prefix-glob:"pattern": Like root-glob:, but also matches path prefix (file or files under directory recursively.)

Glob patterns support case-insensitive matching by appending -i to the pattern name. For example, glob-i:"*.TXT" will match both file.txt and FILE.TXT.

Operators

The following operators are supported. x and y below can be any fileset expressions.

  • ~x: Matches everything but x.
  • x & y: Matches both x and y.
  • x ~ y: Matches x but not y.
  • x | y: Matches either x or y (or both).

(listed in order of binding strengths)

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.

Examples

Show diff excluding Cargo.lock.

jj diff '~Cargo.lock'

List files in src excluding Rust sources.

jj file list 'src ~ glob:"**/*.rs"'

Split a revision in two, putting foo into the second commit.

jj split '~foo'