Merge branch 'main' into add-lore-page

Author: Piratebird

contributing-guides/style-guide.md

@@ -410,7 +410,7 @@ In general, placeholders should make it as intuitive as possible to figure out h
 
 - If a particular extension is expected for the file, append it.
 - If the extension represents the most common format but the command accepts related variations (such as multi-volume `.r00` or `.part1.rar` archives), keep it **inside** the placeholder: `unrar x {{path/to/archive.rar}}`.
-- If the command strictly requires one specific extension and no others to function, keep the extension **outside** the placeholder to indicate it is mandatory: `java -jar {{path/to/filename}}.jar`.
+- If the command strictly requires one specific extension and no others to function or if it always produces that type of file despite the provided extension, keep the extension **outside** the placeholder to indicate it is mandatory: `java -jar {{path/to/filename}}.jar`.
 - In case a generic extension is needed, use `{{.ext}}`, but **only** if an extension is required.
 - For instance, in `find.md`'s example "Find files by extension" (`find {{path/to/root}} -name '{{*.ext}}'`), using `{{*.ext}}` explains the command without being unnecessarily specific.
 - In `wc -l {{path/to/file}}`, using `{{path/to/file}}` (without an extension) is sufficient.

pages/common/jj-file-annotate.md

@@ -0,0 +1,16 @@
+# jj file annotate
+
+> Show the source change for each line of a target file in a `jj` repository.
+> More information: <https://docs.jj-vcs.dev/latest/cli-reference/#jj-file-annotate>.
+
+- Annotate a file line by line in the working copy:
+
+`jj file annotate {{path/to/file}}`
+
+- Annotate a file starting at a specific revision:
+
+`jj file annotate {{[-r|--revision]}} {{revision}} {{path/to/file}}`
+
+- Annotate a file using a custom template:
+
+`jj file annotate {{[-T|--template]}} "{{template}}" {{path/to/file}}`

pages/common/jj-file-list.md

@@ -0,0 +1,20 @@
+# jj file list
+
+> List files in a revision of a `jj` repository.
+> More information: <https://docs.jj-vcs.dev/latest/cli-reference/#jj-file-list>.
+
+- List all files in the current working copy:
+
+`jj file list`
+
+- List all files in a specific revision:
+
+`jj file list {{[-r|--revision]}} {{revision}}`
+
+- List files matching a specific prefix or path:
+
+`jj file list {{path/to/directory}}`
+
+- List files rendered using a custom template:
+
+`jj file list {{[-T|--template]}} "{{template}}"`

pages/common/jj-file-search.md

@@ -0,0 +1,20 @@
+# jj file search
+
+> Search for content in files in a `jj` repository.
+> More information: <https://docs.jj-vcs.dev/latest/cli-reference/#jj-file-search>.
+
+- Search for files containing a `regex` in the working copy:
+
+`jj file search {{[-p|--pattern]}} "{{regex}}"`
+
+- Search for files containing a glob pattern:
+
+`jj file search {{[-p|--pattern]}} "{{glob:*pattern*}}"`
+
+- Search for content in files in a specific revision:
+
+`jj file search {{[-r|--revision]}} {{revision}} {{[-p|--pattern]}} "{{pattern}}"`
+
+- Search only within specific paths or files:
+
+`jj file search {{[-p|--pattern]}} "{{pattern}}" {{path/to/file_or_directory}}`

pages/common/jj-file-show.md

@@ -0,0 +1,20 @@
+# jj file show
+
+> Print contents of files in a revision of a `jj` repository.
+> More information: <https://docs.jj-vcs.dev/latest/cli-reference/#jj-file-show>.
+
+- Print the contents of a file in the working copy:
+
+`jj file show {{path/to/file}}`
+
+- Print the contents of a file in a specific revision:
+
+`jj file show {{[-r|--revision]}} {{revision}} {{path/to/file}}`
+
+- Print all files under a directory recursively:
+
+`jj file show {{path/to/directory}}`
+
+- Print file metadata using a custom template:
+
+`jj file show {{[-T|--template]}} "{{template}}" {{path/to/file}}`

pages/common/jj-file.md

@@ -0,0 +1,33 @@
+# jj file
+
+> Manage and inspect files in a `jj` repository.
+> Some subcommands such as `annotate`, `list`, `search`, `show` have their own usage documentation.
+> More information: <https://docs.jj-vcs.dev/latest/cli-reference/#jj-file>.
+
+- List files tracked in the working copy:
+
+`jj file list`
+
+- Print the contents of a file in the working copy:
+
+`jj file show {{path/to/file}}`
+
+- Search for a pattern across tracked files:
+
+`jj file search {{[-p|--pattern]}} "{{pattern}}"`
+
+- Show line-by-line source change annotation for a file:
+
+`jj file annotate {{path/to/file}}`
+
+- Track specified paths in the working copy:
+
+`jj file track {{path/to/file_or_directory}}`
+
+- Stop tracking specified paths in the working copy:
+
+`jj file untrack {{path/to/file_or_directory}}`
+
+- Set or remove the executable bit for a file:
+
+`jj file chmod {{[-x|--executable]}} {{path/to/file}}`