ok/jj
1
0
Fork 0
forked from mirrors/jj
Code Pull requests Activity
jj/cli/tests/cli-reference@.md.snap

2059 lines
65 KiB
Text
Raw Normal View History

docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
---
source: cli/tests/test_generate_md_cli_help.rs
test_generate_cli_reference: Fixup to 16ec185 That old commit made a piece of documentation obsolete, but I didn't realize it at the time.
2024-06-15 22:08:24 +00:00
description: "AUTO-GENERATED FILE, DO NOT EDIT. This cli reference is generated by a test as an `insta` snapshot. MkDocs includes this snapshot from docs/cli-reference.md."
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
---
docs, CLI reference: use `include-markdown` instead of a symlink The main goal is to avoid having a symlink in our source tree. Currently, there is no good way to work with the `jj` repo with `jj` on Windows. Currently `jj` just crashes with symlinks. This is being worked on, see e.g. #2939, but it will always depend on whether Developer Mode is enabled in Windows or whether symlinks are materialized as text files with symlinks. Finally, MkDocs has trouble following symlinks on Windows, so building docs wouldn't work there. Another advantage is that, previously, we were lucky that MkDocs treats `insta` header in `cli-reference@.md.snap` as a Markdown header and follows symlinks at all. Now, we no longer depend on that.
2024-02-07 20:09:39 +00:00
<!-- BEGIN MARKDOWN-->
docs CLI reference: add a warning that it is experimental There are many minor bugs that are difficult to fix in the short-term. See also the commit message for a197409b2b
2024-02-04 02:11:18 +00:00
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
# Command-Line Help for `jj`
This document contains the help content for the `jj` command-line program.
**Command Overview:**
* [`jj`↴](#jj)
* [`jj abandon`↴](#jj-abandon)
* [`jj backout`↴](#jj-backout)
* [`jj branch`↴](#jj-branch)
* [`jj branch create`↴](#jj-branch-create)
* [`jj branch delete`↴](#jj-branch-delete)
* [`jj branch forget`↴](#jj-branch-forget)
* [`jj branch list`↴](#jj-branch-list)
cli: branch: add "move" command that can update branches by revset or name This basically supersedes the current "branch set" command. The plan is to turn "branch set" into an "upsert" command, and deprecate "branch create". (#3584) Maybe we can also add "branch set --new" flag to only allow creation of new branches. One reason behind this proposed change is that "set" usually allows both "creation" and "update". However, we also need a typo-safe version of "set" to not create new branches by accident. "jj branch move" is useful when advancing ancestor branches. Let's say you've added a couple of commits on top of an existing PR branch, you can advance the branch by "jj branch move --from 'heads(::@- & branches())' --to @-". If this pattern is super common, maybe we can add --advance flag for short. One drawback of this change is that "git branch --move" is equivalent to "jj branch rename". I personally don't find this is confusing, but it's true that "move" sometimes means "rename".
2024-06-16 06:40:53 +00:00
* [`jj branch move`↴](#jj-branch-move)
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
* [`jj branch rename`↴](#jj-branch-rename)
* [`jj branch set`↴](#jj-branch-set)
* [`jj branch track`↴](#jj-branch-track)
* [`jj branch untrack`↴](#jj-branch-untrack)
* [`jj commit`↴](#jj-commit)
* [`jj config`↴](#jj-config)
* [`jj config edit`↴](#jj-config-edit)
cli: sort config/sparse subcommands in lexicographical order
2024-06-20 07:54:28 +00:00
* [`jj config get`↴](#jj-config-get)
* [`jj config list`↴](#jj-config-list)
cli `jj config`: add `jj config path` command
2024-02-01 04:53:23 +00:00
* [`jj config path`↴](#jj-config-path)
cli: sort config/sparse subcommands in lexicographical order
2024-06-20 07:54:28 +00:00
* [`jj config set`↴](#jj-config-set)
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
* [`jj describe`↴](#jj-describe)
* [`jj diff`↴](#jj-diff)
* [`jj diffedit`↴](#jj-diffedit)
* [`jj duplicate`↴](#jj-duplicate)
* [`jj edit`↴](#jj-edit)
feat: Create a `file` command containing `print` and `chmod` - rearrange the files involved to be more clear about structure - deprecate existing `jj cat` and `jj chmod`
2024-06-14 14:34:17 +00:00
* [`jj file`↴](#jj-file)
* [`jj file chmod`↴](#jj-file-chmod)
cli: create `jj file list` and deprecate `jj files`
2024-06-15 17:27:01 +00:00
* [`jj file list`↴](#jj-file-list)
cli: file: sort subcommands chronologically Otherwise they wouldn't be sorted in help. I also reordered the match statement. Since subcommands are split to per-file modules, there's no point to keep some logical ordering.
2024-06-18 01:28:20 +00:00
* [`jj file print`↴](#jj-file-print)
cli: implement enough of `jj fix` to run a single tool on all files
2024-05-15 22:19:55 +00:00
* [`jj fix`↴](#jj-fix)
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
* [`jj git`↴](#jj-git)
cli: sort debug/git subcommands lexicographically
2024-06-19 11:07:30 +00:00
* [`jj git clone`↴](#jj-git-clone)
* [`jj git export`↴](#jj-git-export)
* [`jj git fetch`↴](#jj-git-fetch)
* [`jj git import`↴](#jj-git-import)
* [`jj git init`↴](#jj-git-init)
* [`jj git push`↴](#jj-git-push)
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
* [`jj git remote`↴](#jj-git-remote)
* [`jj git remote add`↴](#jj-git-remote-add)
cli: sort debug/git subcommands lexicographically
2024-06-19 11:07:30 +00:00
* [`jj git remote list`↴](#jj-git-remote-list)
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
* [`jj git remote remove`↴](#jj-git-remote-remove)
* [`jj git remote rename`↴](#jj-git-remote-rename)
cli: git: add `jj git remote set-url` command
2024-06-21 11:11:22 +00:00
* [`jj git remote set-url`↴](#jj-git-remote-set-url)
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
* [`jj init`↴](#jj-init)
* [`jj interdiff`↴](#jj-interdiff)
* [`jj log`↴](#jj-log)
* [`jj new`↴](#jj-new)
* [`jj next`↴](#jj-next)
* [`jj obslog`↴](#jj-obslog)
* [`jj operation`↴](#jj-operation)
* [`jj operation abandon`↴](#jj-operation-abandon)
* [`jj operation log`↴](#jj-operation-log)
* [`jj operation restore`↴](#jj-operation-restore)
cli: sort operation subcommands
2024-06-22 01:19:38 +00:00
* [`jj operation undo`↴](#jj-operation-undo)
Implement jj parallelize Parallelize revisions by making them siblings Running `jj parallelize 1::2` will transform the history like this: ```text 3 | 3 2 / \ | -> 1 2 1 \ / | 0 0 ``` Each of the target revisions is rebased onto the parents of the root(s) of the target revset (not to be confused with the repo root). The children of the head(s) of the target revset are rebased onto the target revisions. The target revset is the union of the REVISIONS arguments. The target revset being parallelized must satisfy several conditions, otherwise the command will fail. 1. The heads of the target revset must not have different children. 2. The roots of the target revset must not have different parents. 3. The parents of all target revisions except the roots must also be parallelized. This means that the target revisions must be connected.
2024-03-31 12:46:55 +00:00
* [`jj parallelize`↴](#jj-parallelize)
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
* [`jj prev`↴](#jj-prev)
* [`jj rebase`↴](#jj-rebase)
* [`jj resolve`↴](#jj-resolve)
* [`jj restore`↴](#jj-restore)
* [`jj root`↴](#jj-root)
* [`jj show`↴](#jj-show)
* [`jj sparse`↴](#jj-sparse)
cli: sort config/sparse subcommands in lexicographical order
2024-06-20 07:54:28 +00:00
* [`jj sparse edit`↴](#jj-sparse-edit)
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
* [`jj sparse list`↴](#jj-sparse-list)
sparse: extract "set --reset" to subcommand Since --reset conflicts with the other flags, "set --reset" seems odd.
2024-03-28 12:19:24 +00:00
* [`jj sparse reset`↴](#jj-sparse-reset)
cli: sort config/sparse subcommands in lexicographical order
2024-06-20 07:54:28 +00:00
* [`jj sparse set`↴](#jj-sparse-set)
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
* [`jj split`↴](#jj-split)
* [`jj squash`↴](#jj-squash)
* [`jj status`↴](#jj-status)
* [`jj tag`↴](#jj-tag)
* [`jj tag list`↴](#jj-tag-list)
* [`jj util`↴](#jj-util)
* [`jj util completion`↴](#jj-util-completion)
* [`jj util gc`↴](#jj-util-gc)
* [`jj util mangen`↴](#jj-util-mangen)
* [`jj util markdown-help`↴](#jj-util-markdown-help)
* [`jj util config-schema`↴](#jj-util-config-schema)
* [`jj undo`↴](#jj-undo)
* [`jj unsquash`↴](#jj-unsquash)
* [`jj untrack`↴](#jj-untrack)
* [`jj version`↴](#jj-version)
* [`jj workspace`↴](#jj-workspace)
* [`jj workspace add`↴](#jj-workspace-add)
* [`jj workspace forget`↴](#jj-workspace-forget)
* [`jj workspace list`↴](#jj-workspace-list)
* [`jj workspace root`↴](#jj-workspace-root)
* [`jj workspace update-stale`↴](#jj-workspace-update-stale)
## `jj`
Jujutsu (An experimental VCS)
To get started, see the tutorial at https://github.com/martinvonz/jj/blob/main/docs/tutorial.md.
**Usage:** `jj [OPTIONS] [COMMAND]`
###### **Subcommands:**
* `abandon` — Abandon a revision
* `backout` — Apply the reverse of a revision on top of another revision
* `branch` — Manage branches
* `commit` — Update the description and create a new change on top
* `config` — Manage config options
* `describe` — Update the change description or other metadata
cli: restore documentation of `jj diff` lost in split of commands module The description of `jj diff` was lost in commit b5e4e670. We later got a short description for it in b5e4e670. This patch restores the original description.
2024-02-23 16:32:46 +00:00
* `diff` — Compare file contents between two revisions
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
* `diffedit` — Touch up the content changes in a revision with a diff editor
* `duplicate` — Create a new change with the same content as an existing one
cli: update help message for `jj edit` This change updates the language of `jj edit`'s help message to be more clear as to the nature of the command. It also adds a recommendation for a more idiomatic/safer workflow.
2024-03-07 20:01:17 +00:00
* `edit` — Sets the specified revision as the working-copy revision
feat: Create a `file` command containing `print` and `chmod` - rearrange the files involved to be more clear about structure - deprecate existing `jj cat` and `jj chmod`
2024-06-14 14:34:17 +00:00
* `file` — File operations
cli: implement enough of `jj fix` to run a single tool on all files
2024-05-15 22:19:55 +00:00
* `fix` — Update files with formatting fixes or other changes
`jj help git`: Include "Git remotes" in the title Previously, it sounded like `jj git` might only include highly-technical commands, while IMO the most important commands in here are `jj git fetch` and `jj git push`.
2024-06-03 04:54:31 +00:00
* `git` — Commands for working with Git remotes and the underlying Git repo
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
* `init` — Create a new repo in the given directory
* `interdiff` — Compare the changes of two commits
log: add some documentation The `jj log` command had basically no documentation. Let's at least start adding some.
2024-03-08 17:06:06 +00:00
* `log` — Show revision history
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
* `new` — Create a new, empty change and (by default) edit it in the working copy
next/prev: make first line of help text consistent This drops the trailing period for consistency with other commands, and rephrases them a bit for consistency between each other.
2024-03-13 05:15:59 +00:00
* `next` — Move the working-copy commit to the child revision
docs: update obslog description
2024-04-29 13:41:49 +00:00
* `obslog` — Show how a change has evolved over time
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
* `operation` — Commands for working with the operation log
Implement jj parallelize Parallelize revisions by making them siblings Running `jj parallelize 1::2` will transform the history like this: ```text 3 | 3 2 / \ | -> 1 2 1 \ / | 0 0 ``` Each of the target revisions is rebased onto the parents of the root(s) of the target revset (not to be confused with the repo root). The children of the head(s) of the target revset are rebased onto the target revisions. The target revset is the union of the REVISIONS arguments. The target revset being parallelized must satisfy several conditions, otherwise the command will fail. 1. The heads of the target revset must not have different children. 2. The roots of the target revset must not have different parents. 3. The parents of all target revisions except the roots must also be parallelized. This means that the target revisions must be connected.
2024-03-31 12:46:55 +00:00
* `parallelize` — Parallelize revisions by making them siblings
Improve the documentation of `jj prev` This will hopefully make it clear that `jj prev` does not move by [OFFSET] relative to `@`, which is a misconception that I had and I think others may also have. I am suggesting this change as a result of the vigorous discussion in these two issues: - https://github.com/martinvonz/jj/issues/3426 - https://github.com/martinvonz/jj/pull/3445 We should make similar changes to `jj next` as well since it follows similar rules.
2024-04-04 17:04:49 +00:00
* `prev` — Change the working copy revision relative to the parent revision
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
* `rebase` — Move revisions to different parent(s)
* `resolve` — Resolve a conflicted file with an external merge tool
* `restore` — Restore paths from another revision
* `root` — Show the current workspace root directory
* `show` — Show commit description and changes in a revision
* `sparse` — Manage which paths from the working-copy commit are present in the working copy
* `split` — Split a revision in two
squash: learn `--from/--into` flags This was proposed by @Brixy in https://github.com/martinvonz/jj/discussions/2882 a while ago. There seems to be pretty strong consensus that it's a good idea. I've copied the added test cases from `test_move_command.rs`, just replacing `move` by `squash`, `--to` by `--into`, and deleting the test of a no-arg invocation (`jj move` fails, `jj squash` does not - it defaults to squashing into the parent).
2024-03-10 18:50:14 +00:00
* `squash` — Move changes from a revision into another revision
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
* `status` — Show high-level repo status
* `tag` — Manage tags
* `util` — Infrequently used commands such as for generating shell completions
* `undo` — Undo an operation (shortcut for `jj op undo`)
* `unsquash` — Move changes from a revision's parent into the revision
* `untrack` — Stop tracking specified paths in the working copy
* `version` — Display version information
* `workspace` — Commands for working with workspaces
###### **Options:**
* `-R`, `--repository <REPOSITORY>` — Path to repository to operate on
docs CLI Reference: upgrade `clap-markdown` to 0.1.4 Fixes important bugs. 🎉
2024-06-15 21:52:17 +00:00
By default, Jujutsu searches for the closest .jj/ directory in an ancestor of the current working directory.
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
* `--ignore-working-copy` — Don't snapshot the working copy, and don't update it
docs CLI Reference: upgrade `clap-markdown` to 0.1.4 Fixes important bugs. 🎉
2024-06-15 21:52:17 +00:00
By default, Jujutsu snapshots the working copy at the beginning of every command. The working copy is also updated at the end of the command, if the command modified the working-copy commit (`@`). If you want to avoid snapshotting the working copy and instead see a possibly stale working copy commit, you can use `--ignore-working-copy`. This may be useful e.g. in a command prompt, especially if you have another process that commits the working copy.
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
docs CLI Reference: upgrade `clap-markdown` to 0.1.4 Fixes important bugs. 🎉
2024-06-15 21:52:17 +00:00
Loading the repository at a specific operation with `--at-operation` implies `--ignore-working-copy`.
cli `--ignore-immutable` help: remove double negative
2024-05-02 05:27:00 +00:00
* `--ignore-immutable` — Allow rewriting immutable commits
cli: add global `--ignore-immutable` Closes #3576
2024-04-25 23:56:03 +00:00
docs CLI Reference: upgrade `clap-markdown` to 0.1.4 Fixes important bugs. 🎉
2024-06-15 21:52:17 +00:00
By default, Jujutsu prevents rewriting commits in the configured set of immutable commits. This option disables that check and lets you rewrite any commit but the root commit.
cli: add global `--ignore-immutable` Closes #3576
2024-04-25 23:56:03 +00:00
docs CLI Reference: upgrade `clap-markdown` to 0.1.4 Fixes important bugs. 🎉
2024-06-15 21:52:17 +00:00
This option only affects the check. It does not affect the `immutable_heads()` revset or the `immutable` template keyword.
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
* `--at-operation <AT_OPERATION>` — Operation to load the repo at
docs CLI Reference: upgrade `clap-markdown` to 0.1.4 Fixes important bugs. 🎉
2024-06-15 21:52:17 +00:00
Operation to load the repo at. By default, Jujutsu loads the repo at the most recent operation. You can use `--at-op=<operation ID>` to see what the repo looked like at an earlier operation. For example `jj --at-op=<operation ID> st` will show you what `jj st` would have shown you when the given operation had just finished.
Use `jj op log` to find the operation ID you want. Any unambiguous prefix of the operation ID is enough.
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
docs CLI Reference: upgrade `clap-markdown` to 0.1.4 Fixes important bugs. 🎉
2024-06-15 21:52:17 +00:00
When loading the repo at an earlier operation, the working copy will be ignored, as if `--ignore-working-copy` had been specified.
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
docs CLI Reference: upgrade `clap-markdown` to 0.1.4 Fixes important bugs. 🎉
2024-06-15 21:52:17 +00:00
It is possible to run mutating commands when loading the repo at an earlier operation. Doing that is equivalent to having run concurrent commands starting at the earlier operation. There's rarely a reason to do that, but it is possible.
Default value: `@`
* `--debug` — Enable debug logging
cli: add `ui.color = "debug"` When using `ui.color = "debug"`, changes in the output style additionally include delimiters << and >>, as well as all active labels at this point separated by ::. The output is otherwise unformatted and the delimiters and labels inherit the style of the content they apply to.
2024-05-06 16:23:36 +00:00
* `--color <WHEN>` — When to colorize output (always, never, debug, auto)
cli: add a global `--quiet` flag, which silences status messages Note that `jj resolve` already had its own `--quiet` flag. The output with `--quiet` for that command got a lot quieter with the global `--quiet` also taking effect. That seems reasonable to me.
2024-03-30 17:18:56 +00:00
* `--quiet` — Silence non-primary command output
docs CLI Reference: upgrade `clap-markdown` to 0.1.4 Fixes important bugs. 🎉
2024-06-15 21:52:17 +00:00
For example, `jj files` will still list files, but it won't tell you if the working copy was snapshotted or if descendants were rebased.
cli: add a global `--quiet` flag, which silences status messages Note that `jj resolve` already had its own `--quiet` flag. The output with `--quiet` for that command got a lot quieter with the global `--quiet` also taking effect. That seems reasonable to me.
2024-03-30 17:18:56 +00:00
docs CLI Reference: upgrade `clap-markdown` to 0.1.4 Fixes important bugs. 🎉
2024-06-15 21:52:17 +00:00
Warnings and errors will still be printed.
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
* `--no-pager` — Disable the pager
* `--config-toml <TOML>` — Additional configuration options (can be repeated)
## `jj abandon`
Abandon a revision
Abandon a revision, rebasing descendants onto its parent(s). The behavior is similar to `jj restore --changes-in`; the difference is that `jj abandon` gives you a new change, while `jj restore` updates the existing change.
cli: document that we create a new working-copy commit for abandoned one When we abandon a working-copy commit, we create a new working-copy commit on top. This behave is very useful, but it's not obvious. Let's document it. Thankfully, 2bbefcc3383f (rewrite: default to not simplifying ancestor merges) means that there are much fewer commands where we need to document this behavior.
2024-02-26 00:39:35 +00:00
If a working-copy commit gets abandoned, it will be given a new, empty commit. This is true in general; it is not specific to this command.
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
**Usage:** `jj abandon [OPTIONS] [REVISIONS]...`
###### **Arguments:**
* `<REVISIONS>` — The revision(s) to abandon
Default value: `@`
###### **Options:**
* `-s`, `--summary` — Do not print every abandoned commit on a separate line
## `jj backout`
Apply the reverse of a revision on top of another revision
**Usage:** `jj backout [OPTIONS]`
###### **Options:**
* `-r`, `--revision <REVISION>` — The revision to apply the reverse of
Default value: `@`
* `-d`, `--destination <DESTINATION>` — The revision to apply the reverse changes on top of
Default value: `@`
## `jj branch`
cli: branch: remove trailing period from command/arg summary lines That's the convention of clap.
2024-06-20 04:01:55 +00:00
Manage branches
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
For information about branches, see https://github.com/martinvonz/jj/blob/main/docs/branches.md.
**Usage:** `jj branch <COMMAND>`
###### **Subcommands:**
* `create` — Create a new branch
* `delete` — Delete an existing branch and propagate the deletion to remotes on the next push
* `forget` — Forget everything about a branch, including its local and remote targets
* `list` — List branches and their targets
cli: branch: add "move" command that can update branches by revset or name This basically supersedes the current "branch set" command. The plan is to turn "branch set" into an "upsert" command, and deprecate "branch create". (#3584) Maybe we can also add "branch set --new" flag to only allow creation of new branches. One reason behind this proposed change is that "set" usually allows both "creation" and "update". However, we also need a typo-safe version of "set" to not create new branches by accident. "jj branch move" is useful when advancing ancestor branches. Let's say you've added a couple of commits on top of an existing PR branch, you can advance the branch by "jj branch move --from 'heads(::@- & branches())' --to @-". If this pattern is super common, maybe we can add --advance flag for short. One drawback of this change is that "git branch --move" is equivalent to "jj branch rename". I personally don't find this is confusing, but it's true that "move" sometimes means "rename".
2024-06-16 06:40:53 +00:00
* `move` — Move existing branches to target revision
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
* `rename` — Rename `old` branch name to `new` branch name
cli: branch: make "set" do upsert as before Since "set <thing>" often adds a <thing> if not exists, it make some sense that "branch set" does upsert. The current "branch set" use case is now covered by "branch move", so it's okay to change the "set" behavior. If new branch is created by "branch set", status message and hint will be printed to help migration. The user should be able to undo creation if it was a mistake. Closes #3584
2024-06-21 09:00:04 +00:00
* `set` — Create or update a branch to point to a certain commit
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
* `track` — Start tracking given remote branches
* `untrack` — Stop tracking given remote branches
## `jj branch create`
Create a new branch
**Usage:** `jj branch create [OPTIONS] <NAMES>...`
###### **Arguments:**
* `<NAMES>` — The branches to create
###### **Options:**
* `-r`, `--revision <REVISION>` — The branch's target revision
## `jj branch delete`
Delete an existing branch and propagate the deletion to remotes on the next push
cli: branch: drop support for deprecated --glob option It's been 8 months since the option got deprecated by 8dbe12da2a6d.
2024-06-20 11:20:01 +00:00
**Usage:** `jj branch delete <NAMES>...`
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
###### **Arguments:**
* `<NAMES>` — The branches to delete
docs CLI Reference: upgrade `clap-markdown` to 0.1.4 Fixes important bugs. 🎉
2024-06-15 21:52:17 +00:00
By default, the specified name matches exactly. Use `glob:` prefix to select branches by wildcard pattern. For details, see https://github.com/martinvonz/jj/blob/main/docs/revsets.md#string-patterns.
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
## `jj branch forget`
cli: branch: remove trailing period from command/arg summary lines That's the convention of clap.
2024-06-20 04:01:55 +00:00
Forget everything about a branch, including its local and remote targets
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
A forgotten branch will not impact remotes on future pushes. It will be recreated on future pulls if it still exists in the remote.
cli: branch: drop support for deprecated --glob option It's been 8 months since the option got deprecated by 8dbe12da2a6d.
2024-06-20 11:20:01 +00:00
**Usage:** `jj branch forget <NAMES>...`
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
###### **Arguments:**
* `<NAMES>` — The branches to forget
docs CLI Reference: upgrade `clap-markdown` to 0.1.4 Fixes important bugs. 🎉
2024-06-15 21:52:17 +00:00
By default, the specified name matches exactly. Use `glob:` prefix to select branches by wildcard pattern. For details, see https://github.com/martinvonz/jj/blob/main/docs/revsets.md#string-patterns.
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
## `jj branch list`
List branches and their targets
By default, a tracking remote branch will be included only if its target is different from the local target. A non-tracking remote branch won't be listed. For a conflicted branch (both local and remote), old target revisions are preceded by a "-" and new target revisions are preceded by a "+".
For information about branches, see https://github.com/martinvonz/jj/blob/main/docs/branches.md.
**Usage:** `jj branch list [OPTIONS] [NAMES]...`
###### **Arguments:**
* `<NAMES>` — Show branches whose local name matches
docs CLI Reference: upgrade `clap-markdown` to 0.1.4 Fixes important bugs. 🎉
2024-06-15 21:52:17 +00:00
By default, the specified name matches exactly. Use `glob:` prefix to select branches by wildcard pattern. For details, see https://github.com/martinvonz/jj/blob/main/docs/revsets.md#string-patterns.
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
###### **Options:**
cli: rename --all to --all-remotes for branch list
2024-03-31 09:54:11 +00:00
* `-a`, `--all-remotes` — Show all tracking and non-tracking remote branches including the ones whose targets are synchronized with the local branches
cli `branch list`: list tracked branches Add an option to list tracked branches only This option keeps most of the current `--all` printing logic, but: - Omits local Git-tracking branches by default (can be extended to support filtering by remote). - Skip over the branch altogether if it doesn't contain tracked remotes - Don't print the untracked_remote_refs at the end Usage: `jj branch list -t` `jj branch list --tracked` `jj branch list --tracked <branch name>`
2024-02-21 18:27:50 +00:00
* `-t`, `--tracked` — Show remote tracked branches only. Omits local Git-tracking branches by default
cli: add option to list only conflicted branches As requested in #1471, I added a new flag for `jj branch list` to only show branches that are conflicted. Adds a unit test to check for listing only conflicted branches and regenerates the cli output to incorporate the new flag. Closes #1471 reformat
2024-03-22 12:43:43 +00:00
* `-c`, `--conflicted` — Show conflicted branches only
cli: branch: remove trailing period from command/arg summary lines That's the convention of clap.
2024-06-20 04:01:55 +00:00
* `-r`, `--revisions <REVISIONS>` — Show branches whose local targets are in the given revisions
cli: add option to list only conflicted branches As requested in #1471, I added a new flag for `jj branch list` to only show branches that are conflicted. Adds a unit test to check for listing only conflicted branches and regenerates the cli output to incorporate the new flag. Closes #1471 reformat
2024-03-22 12:43:43 +00:00
docs CLI Reference: upgrade `clap-markdown` to 0.1.4 Fixes important bugs. 🎉
2024-06-15 21:52:17 +00:00
Note that `-r deleted_branch` will not work since `deleted_branch` wouldn't have a local target.
cli: port "branch list" to template Perhaps, this can be used to generate parsable branches list. The hint for deleted branches isn't migrated to the template. I'm thinking of moving it out of the loop and printed once at the end. If we want to generate a hint in template, we'll probably need local_ref.tracking_remote_refs(), etc. that return a list of RefNames.
2024-04-30 06:00:07 +00:00
* `-T`, `--template <TEMPLATE>` — Render each branch using the given template
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
docs CLI Reference: upgrade `clap-markdown` to 0.1.4 Fixes important bugs. 🎉
2024-06-15 21:52:17 +00:00
All 0-argument methods of the `RefName` type are available as keywords.
For the syntax, see https://github.com/martinvonz/jj/blob/main/docs/templates.md
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
cli: branch: add "move" command that can update branches by revset or name This basically supersedes the current "branch set" command. The plan is to turn "branch set" into an "upsert" command, and deprecate "branch create". (#3584) Maybe we can also add "branch set --new" flag to only allow creation of new branches. One reason behind this proposed change is that "set" usually allows both "creation" and "update". However, we also need a typo-safe version of "set" to not create new branches by accident. "jj branch move" is useful when advancing ancestor branches. Let's say you've added a couple of commits on top of an existing PR branch, you can advance the branch by "jj branch move --from 'heads(::@- & branches())' --to @-". If this pattern is super common, maybe we can add --advance flag for short. One drawback of this change is that "git branch --move" is equivalent to "jj branch rename". I personally don't find this is confusing, but it's true that "move" sometimes means "rename".
2024-06-16 06:40:53 +00:00
## `jj branch move`
Move existing branches to target revision
If branch names are given, the specified branches will be updated to point to the target revision.
If `--from` options are given, branches currently pointing to the specified revisions will be updated. The branches can also be filtered by names.
Example: pull up the nearest branches to the working-copy parent
$ jj branch move --from 'heads(::@- & branches())' --to @-
**Usage:** `jj branch move [OPTIONS] <--from <REVISIONS>|NAMES>`
###### **Arguments:**
* `<NAMES>` — Move branches matching the given name patterns
By default, the specified name matches exactly. Use `glob:` prefix to select branches by wildcard pattern. For details, see https://github.com/martinvonz/jj/blob/main/docs/revsets.md#string-patterns.
###### **Options:**
* `--from <REVISIONS>` — Move branches from the given revisions
* `--to <REVISION>` — Move branches to this revision
Default value: `@`
* `-B`, `--allow-backwards` — Allow moving branches backwards or sideways
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
## `jj branch rename`
cli: branch: remove trailing period from command/arg summary lines That's the convention of clap.
2024-06-20 04:01:55 +00:00
Rename `old` branch name to `new` branch name
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
The new branch name points at the same commit as the old branch name.
**Usage:** `jj branch rename <OLD> <NEW>`
###### **Arguments:**
* `<OLD>` — The old name of the branch
* `<NEW>` — The new name of the branch
## `jj branch set`
cli: branch: make "set" do upsert as before Since "set <thing>" often adds a <thing> if not exists, it make some sense that "branch set" does upsert. The current "branch set" use case is now covered by "branch move", so it's okay to change the "set" behavior. If new branch is created by "branch set", status message and hint will be printed to help migration. The user should be able to undo creation if it was a mistake. Closes #3584
2024-06-21 09:00:04 +00:00
Create or update a branch to point to a certain commit
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
**Usage:** `jj branch set [OPTIONS] <NAMES>...`
###### **Arguments:**
* `<NAMES>` — The branches to update
###### **Options:**
* `-r`, `--revision <REVISION>` — The branch's target revision
* `-B`, `--allow-backwards` — Allow moving the branch backwards or sideways
## `jj branch track`
Start tracking given remote branches
A tracking remote branch will be imported as a local branch of the same name. Changes to it will propagate to the existing local branch on future pulls.
**Usage:** `jj branch track <BRANCH@REMOTE>...`
###### **Arguments:**
* `<BRANCH@REMOTE>` — Remote branches to track
docs CLI Reference: upgrade `clap-markdown` to 0.1.4 Fixes important bugs. 🎉
2024-06-15 21:52:17 +00:00
By default, the specified name matches exactly. Use `glob:` prefix to select branches by wildcard pattern. For details, see https://github.com/martinvonz/jj/blob/main/docs/revsets.md#string-patterns.
Examples: branch@remote, glob:main@*, glob:jjfan-*@upstream
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
## `jj branch untrack`
Stop tracking given remote branches
A non-tracking remote branch is just a pointer to the last-fetched remote branch. It won't be imported as a local branch on future pulls.
**Usage:** `jj branch untrack <BRANCH@REMOTE>...`
###### **Arguments:**
* `<BRANCH@REMOTE>` — Remote branches to untrack
docs CLI Reference: upgrade `clap-markdown` to 0.1.4 Fixes important bugs. 🎉
2024-06-15 21:52:17 +00:00
By default, the specified name matches exactly. Use `glob:` prefix to select branches by wildcard pattern. For details, see https://github.com/martinvonz/jj/blob/main/docs/revsets.md#string-patterns.
Examples: branch@remote, glob:main@*, glob:jjfan-*@upstream
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
## `jj commit`
Update the description and create a new change on top
**Usage:** `jj commit [OPTIONS] [PATHS]...`
###### **Arguments:**
* `<PATHS>` — Put these paths in the first commit
###### **Options:**
* `-i`, `--interactive` — Interactively choose which changes to include in the first commit
cli: add --tool=<name> option to diff/merge editing commands I didn't add e2e tests to all commands, but the added tests should cover diff_editor/diff_selector/merge_editor() calls. Closes #2575
2024-03-01 14:49:22 +00:00
* `--tool <NAME>` — Specify diff editor to be used (implies --interactive)
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
* `-m`, `--message <MESSAGE>` — The change description to use (don't open editor)
## `jj config`
Manage config options
Operates on jj configuration, which comes from the config file and environment variables.
For file locations, supported config options, and other details about jj config, see https://github.com/martinvonz/jj/blob/main/docs/config.md.
**Usage:** `jj config <COMMAND>`
###### **Subcommands:**
* `edit` — Start an editor on a jj config file
cli: sort config/sparse subcommands in lexicographical order
2024-06-20 07:54:28 +00:00
* `get` — Get the value of a given config option.
* `list` — List variables set in config file, along with their values
cli `jj config`: add `jj config path` command
2024-02-01 04:53:23 +00:00
* `path` — Print the path to the config file
cli: sort config/sparse subcommands in lexicographical order
2024-06-20 07:54:28 +00:00
* `set` — Update config file to set the given option to a given value
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
cli: sort config/sparse subcommands in lexicographical order
2024-06-20 07:54:28 +00:00
## `jj config edit`
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
cli: sort config/sparse subcommands in lexicographical order
2024-06-20 07:54:28 +00:00
Start an editor on a jj config file.
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
cli: sort config/sparse subcommands in lexicographical order
2024-06-20 07:54:28 +00:00
Creates the file if it doesn't already exist regardless of what the editor does.
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
cli: sort config/sparse subcommands in lexicographical order
2024-06-20 07:54:28 +00:00
**Usage:** `jj config edit <--user|--repo>`
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
###### **Options:**
* `--user` — Target the user-level config
* `--repo` — Target the repo-level config
## `jj config get`
Get the value of a given config option.
Unlike `jj config list`, the result of `jj config get` is printed without
extra formatting and therefore is usable in scripting. For example:
$ jj config list user.name
user.name="Martin von Zweigbergk"
$ jj config get user.name
Martin von Zweigbergk
**Usage:** `jj config get <NAME>`
###### **Arguments:**
* `<NAME>`
cli: sort config/sparse subcommands in lexicographical order
2024-06-20 07:54:28 +00:00
## `jj config list`
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
cli: sort config/sparse subcommands in lexicographical order
2024-06-20 07:54:28 +00:00
List variables set in config file, along with their values
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
cli: sort config/sparse subcommands in lexicographical order
2024-06-20 07:54:28 +00:00
**Usage:** `jj config list [OPTIONS] [NAME]`
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
###### **Arguments:**
cli: sort config/sparse subcommands in lexicographical order
2024-06-20 07:54:28 +00:00
* `<NAME>` — An optional name of a specific config option to look up
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
###### **Options:**
cli: sort config/sparse subcommands in lexicographical order
2024-06-20 07:54:28 +00:00
* `--include-defaults` — Whether to explicitly include built-in default values in the list
* `--include-overridden` — Allow printing overridden values
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
* `--user` — Target the user-level config
* `--repo` — Target the repo-level config
cli: sort config/sparse subcommands in lexicographical order
2024-06-20 07:54:28 +00:00
* `-T`, `--template <TEMPLATE>` — Render each variable using the given template
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
cli: sort config/sparse subcommands in lexicographical order
2024-06-20 07:54:28 +00:00
The following keywords are defined:
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
cli: sort config/sparse subcommands in lexicographical order
2024-06-20 07:54:28 +00:00
* `name: String`: Config name.
* `value: String`: Serialized value in TOML syntax.
* `overridden: Boolean`: True if the value is shadowed by other.
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
cli: sort config/sparse subcommands in lexicographical order
2024-06-20 07:54:28 +00:00
For the syntax, see https://github.com/martinvonz/jj/blob/main/docs/templates.md
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
docs: mention in `jj help config edit` that the command can create a file
2024-02-01 04:53:23 +00:00
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
cli: sort config/sparse subcommands in lexicographical order
2024-06-20 07:54:28 +00:00
## `jj config path`
Print the path to the config file
A config file at that path may or may not exist.
See `jj config edit` if you'd like to immediately edit the file.
**Usage:** `jj config path <--user|--repo>`
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
###### **Options:**
cli `jj config`: add `jj config path` command
2024-02-01 04:53:23 +00:00
* `--user` — Target the user-level config
* `--repo` — Target the repo-level config
cli: sort config/sparse subcommands in lexicographical order
2024-06-20 07:54:28 +00:00
## `jj config set`
cli `jj config`: add `jj config path` command
2024-02-01 04:53:23 +00:00
cli: sort config/sparse subcommands in lexicographical order
2024-06-20 07:54:28 +00:00
Update config file to set the given option to a given value
cli `jj config`: add `jj config path` command
2024-02-01 04:53:23 +00:00
cli: sort config/sparse subcommands in lexicographical order
2024-06-20 07:54:28 +00:00
**Usage:** `jj config set <--user|--repo> <NAME> <VALUE>`
cli `jj config`: add `jj config path` command
2024-02-01 04:53:23 +00:00
cli: sort config/sparse subcommands in lexicographical order
2024-06-20 07:54:28 +00:00
###### **Arguments:**
cli `jj config`: add `jj config path` command
2024-02-01 04:53:23 +00:00
cli: sort config/sparse subcommands in lexicographical order
2024-06-20 07:54:28 +00:00
* `<NAME>`
* `<VALUE>`
cli `jj config`: add `jj config path` command
2024-02-01 04:53:23 +00:00
###### **Options:**
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
* `--user` — Target the user-level config
* `--repo` — Target the repo-level config
## `jj describe`
Update the change description or other metadata
Starts an editor to let you edit the description of a change. The editor will be $EDITOR, or `pico` if that's not defined (`Notepad` on Windows).
**Usage:** `jj describe [OPTIONS] [REVISION]`
###### **Arguments:**
* `<REVISION>` — The revision whose description to edit
Default value: `@`
###### **Options:**
* `-m`, `--message <MESSAGE>` — The change description to use (don't open editor)
* `--stdin` — Read the change description from stdin
* `--no-edit` — Don't open an editor
docs CLI Reference: upgrade `clap-markdown` to 0.1.4 Fixes important bugs. 🎉
2024-06-15 21:52:17 +00:00
This is mainly useful in combination with e.g. `--reset-author`.
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
* `--reset-author` — Reset the author to the configured user
docs CLI Reference: upgrade `clap-markdown` to 0.1.4 Fixes important bugs. 🎉
2024-06-15 21:52:17 +00:00
This resets the author name, email, and timestamp.
You can use it in combination with the JJ_USER and JJ_EMAIL environment variables to set a different author:
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
docs CLI Reference: upgrade `clap-markdown` to 0.1.4 Fixes important bugs. 🎉
2024-06-15 21:52:17 +00:00
$ JJ_USER='Foo Bar' JJ_EMAIL=foo@bar.com jj describe --reset-author
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
## `jj diff`
cli: restore documentation of `jj diff` lost in split of commands module The description of `jj diff` was lost in commit b5e4e670. We later got a short description for it in b5e4e670. This patch restores the original description.
2024-02-23 16:32:46 +00:00
Compare file contents between two revisions
With the `-r` option, which is the default, shows the changes compared to the parent revision. If there are several parent revisions (i.e., the given revision is a merge), then they will be merged and the changes from the result to the given revision will be shown.
With the `--from` and/or `--to` options, shows the difference from/to the given revisions. If either is left out, it defaults to the working-copy commit. For example, `jj diff --from main` shows the changes from "main" (perhaps a branch name) to the working-copy commit.
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
**Usage:** `jj diff [OPTIONS] [PATHS]...`
###### **Arguments:**
* `<PATHS>` — Restrict the diff to these paths
###### **Options:**
* `-r`, `--revision <REVISION>` — Show changes in this revision, compared to its parent(s)
docs CLI Reference: upgrade `clap-markdown` to 0.1.4 Fixes important bugs. 🎉
2024-06-15 21:52:17 +00:00
If the revision is a merge commit, this shows changes *from* the automatic merge of the contents of all of its parents *to* the contents of the revision itself.
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
* `--from <FROM>` — Show changes from this revision
* `--to <TO>` — Show changes to this revision
* `-s`, `--summary` — For each path, show only whether it was modified, added, or deleted
* `--stat` — Show a histogram of the changes
* `--types` — For each path, show only its type before and after
docs CLI Reference: upgrade `clap-markdown` to 0.1.4 Fixes important bugs. 🎉
2024-06-15 21:52:17 +00:00
The diff is shown as two letters. The first letter indicates the type before and the second letter indicates the type after. '-' indicates that the path was not present, 'F' represents a regular file, `L' represents a symlink, 'C' represents a conflict, and 'G' represents a Git submodule.
cli: Add an option to diff to output only paths.
2024-06-19 17:19:51 +00:00
* `--name-only` — For each path, show only its path
Typically useful for shell commands like: `jj diff -r @- --name_only | xargs perl -pi -e's/OLD/NEW/g`
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
* `--git` — Show a Git-format diff
* `--color-words` — Show a word-level diff with changes indicated only by color
* `--tool <TOOL>` — Generate diff by external command
Add --context flag for diffs. Allows specifying the number of lines of context to show around diffs. The logic was already in place, just some plumbing was needed.
2024-03-02 00:57:43 +00:00
* `--context <CONTEXT>` — Number of lines of context to show
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
## `jj diffedit`
Touch up the content changes in a revision with a diff editor
docs: stop mentioning `meld` as the default diff editor The default is now `:builtin`.
2024-04-12 23:42:07 +00:00
With the `-r` option, which is the default, starts a [diff editor] on the changes in the revision.
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
docs: stop mentioning `meld` as the default diff editor The default is now `:builtin`.
2024-04-12 23:42:07 +00:00
With the `--from` and/or `--to` options, starts a [diff editor] comparing the "from" revision to the "to" revision.
[diff editor]: https://martinvonz.github.io/jj/latest/config/#editing-diffs
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
Edit the right side of the diff until it looks the way you want. Once you close the editor, the revision specified with `-r` or `--to` will be updated. Descendants will be rebased on top as usual, which may result in conflicts.
See `jj restore` if you want to move entire files from one revision to another. See `jj squash -i` or `jj unsquash -i` if you instead want to move changes into or out of the parent revision.
**Usage:** `jj diffedit [OPTIONS]`
###### **Options:**
* `-r`, `--revision <REVISION>` — The revision to touch up. Defaults to @ if neither --to nor --from are specified
* `--from <FROM>` — Show changes from this revision. Defaults to @ if --to is specified
* `--to <TO>` — Edit changes in this revision. Defaults to @ if --from is specified
cli: add --tool=<name> option to diff/merge editing commands I didn't add e2e tests to all commands, but the added tests should cover diff_editor/diff_selector/merge_editor() calls. Closes #2575
2024-03-01 14:49:22 +00:00
* `--tool <NAME>` — Specify diff editor to be used
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
## `jj duplicate`
Create a new change with the same content as an existing one
**Usage:** `jj duplicate [REVISIONS]...`
###### **Arguments:**
* `<REVISIONS>` — The revision(s) to duplicate
Default value: `@`
## `jj edit`
cli: update help message for `jj edit` This change updates the language of `jj edit`'s help message to be more clear as to the nature of the command. It also adds a recommendation for a more idiomatic/safer workflow.
2024-03-07 20:01:17 +00:00
Sets the specified revision as the working-copy revision
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
cli: update help message for `jj edit` This change updates the language of `jj edit`'s help message to be more clear as to the nature of the command. It also adds a recommendation for a more idiomatic/safer workflow.
2024-03-07 20:01:17 +00:00
Note: it is generally recommended to instead use `jj new` and `jj squash`.
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
docs: add FAQ for why to use new-then-amend over edit
2024-03-07 21:16:16 +00:00
For more information, see https://martinvonz.github.io/jj/latest/FAQ#how-do-i-resume-working-on-an-existing-change
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
**Usage:** `jj edit <REVISION>`
###### **Arguments:**
* `<REVISION>` — The commit to edit
feat: Create a `file` command containing `print` and `chmod` - rearrange the files involved to be more clear about structure - deprecate existing `jj cat` and `jj chmod`
2024-06-14 14:34:17 +00:00
## `jj file`
File operations
**Usage:** `jj file <COMMAND>`
###### **Subcommands:**
* `chmod` — Sets or removes the executable bit for paths in the repo
cli: create `jj file list` and deprecate `jj files`
2024-06-15 17:27:01 +00:00
* `list` — List files in a revision
cli: file: sort subcommands chronologically Otherwise they wouldn't be sorted in help. I also reordered the match statement. Since subcommands are split to per-file modules, there's no point to keep some logical ordering.
2024-06-18 01:28:20 +00:00
* `print` — Print contents of files in a revision
feat: Create a `file` command containing `print` and `chmod` - rearrange the files involved to be more clear about structure - deprecate existing `jj cat` and `jj chmod`
2024-06-14 14:34:17 +00:00
## `jj file chmod`
Sets or removes the executable bit for paths in the repo
Unlike the POSIX `chmod`, `jj chmod` also works on Windows, on conflicted files, and on arbitrary revisions.
**Usage:** `jj file chmod [OPTIONS] <MODE> <PATHS>...`
###### **Arguments:**
* `<MODE>`
Possible values:
- `n`:
Make a path non-executable (alias: normal)
- `x`:
Make a path executable (alias: executable)
* `<PATHS>` — Paths to change the executable bit for
###### **Options:**
* `-r`, `--revision <REVISION>` — The revision to update
Default value: `@`
cli: create `jj file list` and deprecate `jj files`
2024-06-15 17:27:01 +00:00
## `jj file list`
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
List files in a revision
cli: create `jj file list` and deprecate `jj files`
2024-06-15 17:27:01 +00:00
**Usage:** `jj file list [OPTIONS] [PATHS]...`
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
###### **Arguments:**
* `<PATHS>` — Only list files matching these prefixes (instead of all files)
###### **Options:**
* `-r`, `--revision <REVISION>` — The revision to list files in
Default value: `@`
cli: file: sort subcommands chronologically Otherwise they wouldn't be sorted in help. I also reordered the match statement. Since subcommands are split to per-file modules, there's no point to keep some logical ordering.
2024-06-18 01:28:20 +00:00
## `jj file print`
Print contents of files in a revision
If the given path is a directory, files in the directory will be visited recursively.
**Usage:** `jj file print [OPTIONS] <PATHS>...`
###### **Arguments:**
* `<PATHS>` — Paths to print
###### **Options:**
* `-r`, `--revision <REVISION>` — The revision to get the file contents from
Default value: `@`
cli: implement enough of `jj fix` to run a single tool on all files
2024-05-15 22:19:55 +00:00
## `jj fix`
Update files with formatting fixes or other changes
The primary use case for this command is to apply the results of automatic
code formatting tools to revisions that may not be properly formatted yet.
It can also be used to modify files with other tools like `sed` or `sort`.
The changed files in the given revisions will be updated with any fixes
determined by passing their file content through the external tool.
Descendants will also be updated by passing their versions of the same files
through the same external tool, which will never result in new conflicts.
Files with existing conflicts will be updated on all sides of the conflict,
which can potentially increase or decrease the number of conflict markers.
The external tool must accept the current file content on standard input,
and return the updated file content on standard output. The output will not
be used unless the tool exits with a successful exit code. Output on
standard error will be passed through to the terminal.
The configuration schema is expected to change in the future. For now, it
defines a single command that will affect all changed files in the specified
revisions. For example, to format some Rust code changed in the working copy
revision, you could write this configuration:
[fix]
tool-command = ["rustfmt", "--emit", "stdout"]
And then run the command `jj fix -s @`.
fix: add support for fixing only some paths
2024-06-10 08:48:19 +00:00
**Usage:** `jj fix [OPTIONS] [PATHS]...`
###### **Arguments:**
* `<PATHS>` — Fix only these paths
cli: implement enough of `jj fix` to run a single tool on all files
2024-05-15 22:19:55 +00:00
###### **Options:**
cli `fix`: change default from `-s @` to `-s 'reachable(@, mutable())'` Most of the value of `jj fix` over a shell script is in formatting commits other than `@`. `@::` often doesn't contain those other commits, so `-s @` is a bad default. We could get the same effect from `-s 'mutable() & ::@'`, but `reachable()` is a bit more explicit and simple to read. We could also base this on excluding `trunk()`, but that just seems like an indirection for `mutable()` that might ignore the user's intent if they have configured part of trunk to be mutable.
2024-06-07 03:10:21 +00:00
* `-s`, `--source <SOURCE>` — Fix files in the specified revision(s) and their descendants. If no revisions are specified, this defaults to the `revsets.fix` setting, or `reachable(@, mutable())` if it is not set
cli: implement enough of `jj fix` to run a single tool on all files
2024-05-15 22:19:55 +00:00
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
## `jj git`
`jj help git`: Include "Git remotes" in the title Previously, it sounded like `jj git` might only include highly-technical commands, while IMO the most important commands in here are `jj git fetch` and `jj git push`.
2024-06-03 04:54:31 +00:00
Commands for working with Git remotes and the underlying Git repo
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
For a comparison with Git, including a table of commands, see https://github.com/martinvonz/jj/blob/main/docs/git-comparison.md.
**Usage:** `jj git <COMMAND>`
###### **Subcommands:**
* `clone` — Create a new repo backed by a clone of a Git repo
* `export` — Update the underlying Git repo with changes made in the repo
cli: sort debug/git subcommands lexicographically
2024-06-19 11:07:30 +00:00
* `fetch` — Fetch from a Git remote
* `import` — Update repo with changes made in the underlying Git repo
* `init` — Create a new Git backed repo
* `push` — Push to a Git remote
* `remote` — Manage Git remotes
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
cli: sort debug/git subcommands lexicographically
2024-06-19 11:07:30 +00:00
## `jj git clone`
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
cli: sort debug/git subcommands lexicographically
2024-06-19 11:07:30 +00:00
Create a new repo backed by a clone of a Git repo
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
The Git repo will be a bare git repo stored inside the `.jj/` directory.
cli: sort debug/git subcommands lexicographically
2024-06-19 11:07:30 +00:00
**Usage:** `jj git clone [OPTIONS] <SOURCE> [DESTINATION]`
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
cli: sort debug/git subcommands lexicographically
2024-06-19 11:07:30 +00:00
###### **Arguments:**
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
cli: sort debug/git subcommands lexicographically
2024-06-19 11:07:30 +00:00
* `<SOURCE>` — URL or path of the Git repo to clone
* `<DESTINATION>` — The directory to write the Jujutsu repo to
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
cli: sort debug/git subcommands lexicographically
2024-06-19 11:07:30 +00:00
###### **Options:**
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
cli: sort debug/git subcommands lexicographically
2024-06-19 11:07:30 +00:00
* `--colocate` — Whether or not to colocate the Jujutsu repo with the git repo
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
cli: sort debug/git subcommands lexicographically
2024-06-19 11:07:30 +00:00
## `jj git export`
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
cli: sort debug/git subcommands lexicographically
2024-06-19 11:07:30 +00:00
Update the underlying Git repo with changes made in the repo
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
cli: sort debug/git subcommands lexicographically
2024-06-19 11:07:30 +00:00
**Usage:** `jj git export`
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
cli: sort debug/git subcommands lexicographically
2024-06-19 11:07:30 +00:00
## `jj git fetch`
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
cli: sort debug/git subcommands lexicographically
2024-06-19 11:07:30 +00:00
Fetch from a Git remote
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
cli: sort debug/git subcommands lexicographically
2024-06-19 11:07:30 +00:00
If a working-copy commit gets abandoned, it will be given a new, empty commit. This is true in general; it is not specific to this command.
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
cli: sort debug/git subcommands lexicographically
2024-06-19 11:07:30 +00:00
**Usage:** `jj git fetch [OPTIONS]`
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
cli: sort debug/git subcommands lexicographically
2024-06-19 11:07:30 +00:00
###### **Options:**
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
cli: sort debug/git subcommands lexicographically
2024-06-19 11:07:30 +00:00
* `-b`, `--branch <BRANCH>` — Fetch only some of the branches
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
cli: sort debug/git subcommands lexicographically
2024-06-19 11:07:30 +00:00
By default, the specified name matches exactly. Use `glob:` prefix to expand `*` as a glob. The other wildcard characters aren't supported.
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
cli: sort debug/git subcommands lexicographically
2024-06-19 11:07:30 +00:00
Default value: `glob:*`
* `--remote <remote>` — The remote to fetch from (only named remotes are supported, can be repeated)
* `--all-remotes` — Fetch from all remotes
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
cli: sort debug/git subcommands lexicographically
2024-06-19 11:07:30 +00:00
## `jj git import`
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
cli: sort debug/git subcommands lexicographically
2024-06-19 11:07:30 +00:00
Update repo with changes made in the underlying Git repo
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
cli: sort debug/git subcommands lexicographically
2024-06-19 11:07:30 +00:00
If a working-copy commit gets abandoned, it will be given a new, empty commit. This is true in general; it is not specific to this command.
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
cli: sort debug/git subcommands lexicographically
2024-06-19 11:07:30 +00:00
**Usage:** `jj git import`
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
cli: add a `jj git init` command. This initializes a git backed repo. * It does the same thing as `jj init --git` except that it has a --colocated flag to explicitly specify that we want the .git repo to be side-by-side the .jj repo in the working directory. * `jj init --git` will keep the current behaviour and will not be able to create colocated git backed repos. * Update test snapshots.
2024-01-08 10:41:07 +00:00
## `jj git init`
Create a new Git backed repo
**Usage:** `jj git init [OPTIONS] [DESTINATION]`
###### **Arguments:**
docs CLI Reference: upgrade `clap-markdown` to 0.1.4 Fixes important bugs. 🎉
2024-06-15 21:52:17 +00:00
* `<DESTINATION>` — The destination directory where the `jj` repo will be created. If the directory does not exist, it will be created. If no directory is given, the current directory is used.
By default the `git` repo is under `$destination/.jj`
cli: add a `jj git init` command. This initializes a git backed repo. * It does the same thing as `jj init --git` except that it has a --colocated flag to explicitly specify that we want the .git repo to be side-by-side the .jj repo in the working directory. * `jj init --git` will keep the current behaviour and will not be able to create colocated git backed repos. * Update test snapshots.
2024-01-08 10:41:07 +00:00
Default value: `.`
###### **Options:**
docs CLI Reference: upgrade `clap-markdown` to 0.1.4 Fixes important bugs. 🎉
2024-06-15 21:52:17 +00:00
* `--colocate` — Specifies that the `jj` repo should also be a valid `git` repo, allowing the use of both `jj` and `git` commands in the same directory.
This is done by placing the backing git repo into a `.git` directory in the root of the `jj` repo along with the `.jj` directory. If the `.git` directory already exists, all the existing commits will be imported.
cli: add a `jj git init` command. This initializes a git backed repo. * It does the same thing as `jj init --git` except that it has a --colocated flag to explicitly specify that we want the .git repo to be side-by-side the .jj repo in the working directory. * `jj init --git` will keep the current behaviour and will not be able to create colocated git backed repos. * Update test snapshots.
2024-01-08 10:41:07 +00:00
docs CLI Reference: upgrade `clap-markdown` to 0.1.4 Fixes important bugs. 🎉
2024-06-15 21:52:17 +00:00
This option is mutually exclusive with `--git-repo`.
* `--git-repo <GIT_REPO>` — Specifies a path to an **existing** git repository to be used as the backing git repo for the newly created `jj` repo.
cli: add a `jj git init` command. This initializes a git backed repo. * It does the same thing as `jj init --git` except that it has a --colocated flag to explicitly specify that we want the .git repo to be side-by-side the .jj repo in the working directory. * `jj init --git` will keep the current behaviour and will not be able to create colocated git backed repos. * Update test snapshots.
2024-01-08 10:41:07 +00:00
docs CLI Reference: upgrade `clap-markdown` to 0.1.4 Fixes important bugs. 🎉
2024-06-15 21:52:17 +00:00
If the specified `--git-repo` path happens to be the same as the `jj` repo path (both .jj and .git directories are in the same working directory), then both `jj` and `git` commands will work on the same repo. This is called a co-located repo.
This option is mutually exclusive with `--colocate`.
cli: add a `jj git init` command. This initializes a git backed repo. * It does the same thing as `jj init --git` except that it has a --colocated flag to explicitly specify that we want the .git repo to be side-by-side the .jj repo in the working directory. * `jj init --git` will keep the current behaviour and will not be able to create colocated git backed repos. * Update test snapshots.
2024-01-08 10:41:07 +00:00
cli: sort debug/git subcommands lexicographically
2024-06-19 11:07:30 +00:00
## `jj git push`
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
cli: sort debug/git subcommands lexicographically
2024-06-19 11:07:30 +00:00
Push to a Git remote
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
cli: sort debug/git subcommands lexicographically
2024-06-19 11:07:30 +00:00
By default, pushes any branches pointing to `remote_branches(remote=<remote>)..@`. Use `--branch` to push specific branches. Use `--all` to push all branches. Use `--change` to generate branch names based on the change IDs of specific commits.
cli: document that we create a new working-copy commit for abandoned one When we abandon a working-copy commit, we create a new working-copy commit on top. This behave is very useful, but it's not obvious. Let's document it. Thankfully, 2bbefcc3383f (rewrite: default to not simplifying ancestor merges) means that there are much fewer commands where we need to document this behavior.
2024-02-26 00:39:35 +00:00
cli: sort debug/git subcommands lexicographically
2024-06-19 11:07:30 +00:00
Before the command actually moves, creates, or deletes a remote branch, it makes several [safety checks]. If there is a problem, you may need to run `jj git fetch --remote <remote name>` and/or resolve some [branch conflicts].
[safety checks]: https://martinvonz.github.io/jj/latest/branches/#pushing-branches-safety-checks
[branch conflicts]: https://martinvonz.github.io/jj/latest/branches/#conflicts
**Usage:** `jj git push [OPTIONS]`
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
###### **Options:**
cli: sort debug/git subcommands lexicographically
2024-06-19 11:07:30 +00:00
* `--remote <REMOTE>` — The remote to push to (only named remotes are supported)
* `-b`, `--branch <BRANCH>` — Push only this branch, or branches matching a pattern (can be repeated)
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
cli: sort debug/git subcommands lexicographically
2024-06-19 11:07:30 +00:00
By default, the specified name matches exactly. Use `glob:` prefix to select branches by wildcard pattern. For details, see https://martinvonz.github.io/jj/latest/revsets#string-patterns.
* `--all` — Push all branches (including deleted branches)
* `--tracked` — Push all tracked branches (including deleted branches)
docs CLI Reference: upgrade `clap-markdown` to 0.1.4 Fixes important bugs. 🎉
2024-06-15 21:52:17 +00:00
cli: sort debug/git subcommands lexicographically
2024-06-19 11:07:30 +00:00
This usually means that the branch was already pushed to or fetched from the relevant remote. For details, see https://martinvonz.github.io/jj/latest/branches#remotes-and-tracked-branches
* `--deleted` — Push all deleted branches
Only tracked branches can be successfully deleted on the remote. A warning will be printed if any untracked branches on the remote correspond to missing local branches.
* `--allow-empty-description` — Allow pushing commits with empty descriptions
* `-r`, `--revisions <REVISIONS>` — Push branches pointing to these commits (can be repeated)
* `-c`, `--change <CHANGE>` — Push this commit by creating a branch based on its change ID (can be repeated)
* `--dry-run` — Only display what will change on the remote
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
cli: sort debug/git subcommands lexicographically
2024-06-19 11:07:30 +00:00
## `jj git remote`
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
cli: sort debug/git subcommands lexicographically
2024-06-19 11:07:30 +00:00
Manage Git remotes
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
The Git repo will be a bare git repo stored inside the `.jj/` directory.
cli: sort debug/git subcommands lexicographically
2024-06-19 11:07:30 +00:00
**Usage:** `jj git remote <COMMAND>`
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
cli: sort debug/git subcommands lexicographically
2024-06-19 11:07:30 +00:00
###### **Subcommands:**
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
cli: sort debug/git subcommands lexicographically
2024-06-19 11:07:30 +00:00
* `add` — Add a Git remote
* `list` — List Git remotes
* `remove` — Remove a Git remote and forget its branches
* `rename` — Rename a Git remote
cli: git: add `jj git remote set-url` command
2024-06-21 11:11:22 +00:00
* `set-url` — Set the URL of a Git remote
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
cli: sort debug/git subcommands lexicographically
2024-06-19 11:07:30 +00:00
## `jj git remote add`
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
cli: sort debug/git subcommands lexicographically
2024-06-19 11:07:30 +00:00
Add a Git remote
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
cli: sort debug/git subcommands lexicographically
2024-06-19 11:07:30 +00:00
**Usage:** `jj git remote add <REMOTE> <URL>`
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
cli: sort debug/git subcommands lexicographically
2024-06-19 11:07:30 +00:00
###### **Arguments:**
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
cli: sort debug/git subcommands lexicographically
2024-06-19 11:07:30 +00:00
* `<REMOTE>` — The remote's name
* `<URL>` — The remote's URL
`jj git push` docs: document safety checks As discussed in https://discord.com/channels/968932220549103686/1226363798483636265/1226415448615288864
2024-04-08 21:18:58 +00:00
cli: sort debug/git subcommands lexicographically
2024-06-19 11:07:30 +00:00
## `jj git remote list`
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
cli: sort debug/git subcommands lexicographically
2024-06-19 11:07:30 +00:00
List Git remotes
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
cli: sort debug/git subcommands lexicographically
2024-06-19 11:07:30 +00:00
**Usage:** `jj git remote list`
cli `git push`: new --tracked option
2024-02-03 03:38:54 +00:00
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
cli: sort debug/git subcommands lexicographically
2024-06-19 11:07:30 +00:00
## `jj git remote remove`
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
cli: sort debug/git subcommands lexicographically
2024-06-19 11:07:30 +00:00
Remove a Git remote and forget its branches
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
cli: sort debug/git subcommands lexicographically
2024-06-19 11:07:30 +00:00
**Usage:** `jj git remote remove <REMOTE>`
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
cli: sort debug/git subcommands lexicographically
2024-06-19 11:07:30 +00:00
###### **Arguments:**
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
cli: sort debug/git subcommands lexicographically
2024-06-19 11:07:30 +00:00
* `<REMOTE>` — The remote's name
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
cli: document that we create a new working-copy commit for abandoned one When we abandon a working-copy commit, we create a new working-copy commit on top. This behave is very useful, but it's not obvious. Let's document it. Thankfully, 2bbefcc3383f (rewrite: default to not simplifying ancestor merges) means that there are much fewer commands where we need to document this behavior.
2024-02-26 00:39:35 +00:00
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
cli: sort debug/git subcommands lexicographically
2024-06-19 11:07:30 +00:00
## `jj git remote rename`
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
cli: sort debug/git subcommands lexicographically
2024-06-19 11:07:30 +00:00
Rename a Git remote
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
cli: sort debug/git subcommands lexicographically
2024-06-19 11:07:30 +00:00
**Usage:** `jj git remote rename <OLD> <NEW>`
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
cli: sort debug/git subcommands lexicographically
2024-06-19 11:07:30 +00:00
###### **Arguments:**
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
cli: sort debug/git subcommands lexicographically
2024-06-19 11:07:30 +00:00
* `<OLD>` — The name of an existing remote
* `<NEW>` — The desired name for `old`
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
cli: git: add `jj git remote set-url` command
2024-06-21 11:11:22 +00:00
## `jj git remote set-url`
Set the URL of a Git remote
**Usage:** `jj git remote set-url <REMOTE> <URL>`
###### **Arguments:**
* `<REMOTE>` — The remote's name
* `<URL>` — The desired url for `remote`
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
## `jj init`
Create a new repo in the given directory
If the given directory does not exist, it will be created. If no directory is given, the current directory is used.
cli: add a `jj git init` command. This initializes a git backed repo. * It does the same thing as `jj init --git` except that it has a --colocated flag to explicitly specify that we want the .git repo to be side-by-side the .jj repo in the working directory. * `jj init --git` will keep the current behaviour and will not be able to create colocated git backed repos. * Update test snapshots.
2024-01-08 10:41:07 +00:00
**Usage:** `jj init [DESTINATION]`
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
###### **Arguments:**
* `<DESTINATION>` — The destination directory
Default value: `.`
## `jj interdiff`
Compare the changes of two commits
This excludes changes from other commits by temporarily rebasing `--from` onto `--to`'s parents. If you wish to compare the same change across versions, consider `jj obslog -p` instead.
**Usage:** `jj interdiff [OPTIONS] <--from <FROM>|--to <TO>> [PATHS]...`
###### **Arguments:**
* `<PATHS>` — Restrict the diff to these paths
###### **Options:**
* `--from <FROM>` — Show changes from this revision
* `--to <TO>` — Show changes to this revision
* `-s`, `--summary` — For each path, show only whether it was modified, added, or deleted
* `--stat` — Show a histogram of the changes
* `--types` — For each path, show only its type before and after
docs CLI Reference: upgrade `clap-markdown` to 0.1.4 Fixes important bugs. 🎉
2024-06-15 21:52:17 +00:00
The diff is shown as two letters. The first letter indicates the type before and the second letter indicates the type after. '-' indicates that the path was not present, 'F' represents a regular file, `L' represents a symlink, 'C' represents a conflict, and 'G' represents a Git submodule.
cli: Add an option to diff to output only paths.
2024-06-19 17:19:51 +00:00
* `--name-only` — For each path, show only its path
Typically useful for shell commands like: `jj diff -r @- --name_only | xargs perl -pi -e's/OLD/NEW/g`
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
* `--git` — Show a Git-format diff
* `--color-words` — Show a word-level diff with changes indicated only by color
* `--tool <TOOL>` — Generate diff by external command
Add --context flag for diffs. Allows specifying the number of lines of context to show around diffs. The logic was already in place, just some plumbing was needed.
2024-03-02 00:57:43 +00:00
* `--context <CONTEXT>` — Number of lines of context to show
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
## `jj log`
log: add some documentation The `jj log` command had basically no documentation. Let's at least start adding some.
2024-03-08 17:06:06 +00:00
Show revision history
Renders a graphical view of the project's history, ordered with children before parents. By default, the output only includes mutable revisions, along with some additional revisions for context.
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
log: enable synthetic elided nodes by default We're early in the release cycle, so let's enable this feature and test it for a while before the next release.
2024-03-08 17:43:24 +00:00
Spans of revisions that are not included in the graph per `--revisions` are rendered as a synthetic node labeled "(elided revisions)".
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
**Usage:** `jj log [OPTIONS] [PATHS]...`
###### **Arguments:**
log: add some documentation The `jj log` command had basically no documentation. Let's at least start adding some.
2024-03-08 17:06:06 +00:00
* `<PATHS>` — Show revisions modifying the given paths
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
###### **Options:**
cli: only use default log revset when neither path nor revset is provided
2024-03-31 09:47:31 +00:00
* `-r`, `--revisions <REVISIONS>` — Which revisions to show. If no paths nor revisions are specified, this defaults to the `revsets.log` setting, or `@ | ancestors(immutable_heads().., 2) | trunk()` if it is not set
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
* `--reversed` — Show revisions in the opposite order (older revisions first)
cli: deprecate `-l` short alias for `--limit` in favour of `-n` This better matches `git log` and affects `jj log`, `jj op log` and `jj obslog`
2024-06-14 23:24:09 +00:00
* `-n`, `--limit <LIMIT>` — Limit number of revisions to show
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
docs CLI Reference: upgrade `clap-markdown` to 0.1.4 Fixes important bugs. 🎉
2024-06-15 21:52:17 +00:00
Applied after revisions are filtered and reordered.
* `--no-graph` — Don't show the graph, show a flat list of revisions
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
* `-T`, `--template <TEMPLATE>` — Render each revision using the given template
docs CLI Reference: upgrade `clap-markdown` to 0.1.4 Fixes important bugs. 🎉
2024-06-15 21:52:17 +00:00
For the syntax, see https://github.com/martinvonz/jj/blob/main/docs/templates.md
* `-p`, `--patch` — Show patch
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
* `-s`, `--summary` — For each path, show only whether it was modified, added, or deleted
* `--stat` — Show a histogram of the changes
* `--types` — For each path, show only its type before and after
docs CLI Reference: upgrade `clap-markdown` to 0.1.4 Fixes important bugs. 🎉
2024-06-15 21:52:17 +00:00
The diff is shown as two letters. The first letter indicates the type before and the second letter indicates the type after. '-' indicates that the path was not present, 'F' represents a regular file, `L' represents a symlink, 'C' represents a conflict, and 'G' represents a Git submodule.
cli: Add an option to diff to output only paths.
2024-06-19 17:19:51 +00:00
* `--name-only` — For each path, show only its path
Typically useful for shell commands like: `jj diff -r @- --name_only | xargs perl -pi -e's/OLD/NEW/g`
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
* `--git` — Show a Git-format diff
* `--color-words` — Show a word-level diff with changes indicated only by color
* `--tool <TOOL>` — Generate diff by external command
Add --context flag for diffs. Allows specifying the number of lines of context to show around diffs. The logic was already in place, just some plumbing was needed.
2024-03-02 00:57:43 +00:00
* `--context <CONTEXT>` — Number of lines of context to show
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
## `jj new`
Create a new, empty change and (by default) edit it in the working copy
By default, `jj` will edit the new change, making the working copy represent the new commit. This can be avoided with `--no-edit`.
Note that you can create a merge commit by specifying multiple revisions as argument. For example, `jj new main @` will create a new commit with the `main` branch and the working copy as parents.
For more information, see https://github.com/martinvonz/jj/blob/main/docs/working-copy.md.
**Usage:** `jj new [OPTIONS] [REVISIONS]...`
###### **Arguments:**
* `<REVISIONS>` — Parent(s) of the new change
Default value: `@`
###### **Options:**
* `-m`, `--message <MESSAGE>` — The change description to use
* `--no-edit` — Do not edit the newly created change
new: allow `--insert-before` and `--insert-after` simultaneously
2024-06-01 14:26:27 +00:00
* `-A`, `--insert-after <INSERT_AFTER>` — Insert the new change after the given commit(s)
* `-B`, `--insert-before <INSERT_BEFORE>` — Insert the new change before the given commit(s)
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
## `jj next`
next/prev: make first line of help text consistent This drops the trailing period for consistency with other commands, and rephrases them a bit for consistency between each other.
2024-03-13 05:15:59 +00:00
Move the working-copy commit to the child revision
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
Update the documentation for `jj next` This is to match the recent changes made to the docs for `jj prev`.
2024-04-05 19:05:45 +00:00
The command creates a new empty working copy revision that is the child of a
descendant `offset` revisions ahead of the parent of the current working
copy.
For example, when the offset is 1:
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
docs: fixup to b318b200, mark code blocks in help as text This prevents rust doctests from trying to compile the code blocks. I don't think we use doctests much or at all, but I'd like `cargo insta test --test-runner nextest --accept --workspace` to pass. Unfortunately, this affects the output of `jj help` as well, but I can't think of a workaround for that.
2024-01-30 22:59:31 +00:00
```text
Update the documentation for `jj next` This is to match the recent changes made to the docs for `jj prev`.
2024-04-05 19:05:45 +00:00
D D @
| |/
C @ => C
|/ |
B B
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
```
Update the documentation for `jj next` This is to match the recent changes made to the docs for `jj prev`.
2024-04-05 19:05:45 +00:00
If `--edit` is passed, the working copy revision is changed to the child of
the current working copy revision.
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
docs: fixup to b318b200, mark code blocks in help as text This prevents rust doctests from trying to compile the code blocks. I don't think we use doctests much or at all, but I'd like `cargo insta test --test-runner nextest --accept --workspace` to pass. Unfortunately, this affects the output of `jj help` as well, but I can't think of a workaround for that.
2024-01-30 22:59:31 +00:00
```text
Update the documentation for `jj next` This is to match the recent changes made to the docs for `jj prev`.
2024-04-05 19:05:45 +00:00
D D
| |
C C
| |
B => @
| |
@ A
```
next/prev: make --edit implied when already on non-head commit Users who edit non-head commits usually expect `jj next/prev` to continue to edit the next/previous commit, so let's make that the default behavior. This should not confuse users who don't edit non-head commits since they will simply not be in this state. My main concern is that doing `jj next; jj prev` will now usually take you back to the previous commit, but not if you started on the parent of a head commit.
2024-02-12 05:56:52 +00:00
If your working-copy commit already has visible children, then `--edit` is
implied.
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
Rename the "AMOUNT" argument for `jj prev` and `jj next` to OFFSET Offset is a more descriptive noun for this argument. This commit also tweaks the help message for the argument. This isn't an option/flag, so this change should be transparent to users.
2024-04-03 22:08:59 +00:00
**Usage:** `jj next [OPTIONS] [OFFSET]`
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
###### **Arguments:**
Rename the "AMOUNT" argument for `jj prev` and `jj next` to OFFSET Offset is a more descriptive noun for this argument. This commit also tweaks the help message for the argument. This isn't an option/flag, so this change should be transparent to users.
2024-04-03 22:08:59 +00:00
* `<OFFSET>` — How many revisions to move forward. Advances to the next child by default
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
Default value: `1`
###### **Options:**
Add short a `-e` alias for `--edit` to prev and next I'm not sure if this was an intentional omission, but I think it would be useful to have `-e` as a short flag for `--edit`. I don't usually edit commits, but I do use `prev` and `next` with edit to navigate to a commit that I want to squash. Often this is easier than typing `--from` and `--into` plus the change IDs. If people want to edit commits we shouldn't stand in their way.
2024-04-20 12:14:04 +00:00
* `-e`, `--edit` — Instead of creating a new working-copy commit on top of the target commit (like `jj new`), edit the target commit directly (like `jj edit`)
next/prev: Implement `next/prev --conflict` This allows users to jump to the next conflict in the ancestors or children of the start commit. Continues work on #2126 Co-Authored-By: Noah Mayr <dev@noahmayr.com>
2024-02-18 17:57:55 +00:00
* `--conflict` — Jump to the next conflicted descendant
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
## `jj obslog`
docs: update obslog description
2024-04-29 13:41:49 +00:00
Show how a change has evolved over time
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
docs: update obslog description
2024-04-29 13:41:49 +00:00
Lists the previous commits which a change has pointed to. The current commit of a change evolves when the change is updated, rebased, etc.
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
docs: mention origin of obslog name
2024-04-29 06:01:18 +00:00
Name is derived from Merciual's obsolescence markers.
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
**Usage:** `jj obslog [OPTIONS]`
###### **Options:**
* `-r`, `--revision <REVISION>`
Default value: `@`
cli: deprecate `-l` short alias for `--limit` in favour of `-n` This better matches `git log` and affects `jj log`, `jj op log` and `jj obslog`
2024-06-14 23:24:09 +00:00
* `-n`, `--limit <LIMIT>` — Limit number of revisions to show
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
* `--no-graph` — Don't show the graph, show a flat list of revisions
* `-T`, `--template <TEMPLATE>` — Render each revision using the given template
docs CLI Reference: upgrade `clap-markdown` to 0.1.4 Fixes important bugs. 🎉
2024-06-15 21:52:17 +00:00
For the syntax, see https://github.com/martinvonz/jj/blob/main/docs/templates.md
* `-p`, `--patch` — Show patch compared to the previous version of this change
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
docs CLI Reference: upgrade `clap-markdown` to 0.1.4 Fixes important bugs. 🎉
2024-06-15 21:52:17 +00:00
If the previous version has different parents, it will be temporarily rebased to the parents of the new version, so the diff is not contaminated by unrelated changes.
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
* `-s`, `--summary` — For each path, show only whether it was modified, added, or deleted
* `--stat` — Show a histogram of the changes
* `--types` — For each path, show only its type before and after
docs CLI Reference: upgrade `clap-markdown` to 0.1.4 Fixes important bugs. 🎉
2024-06-15 21:52:17 +00:00
The diff is shown as two letters. The first letter indicates the type before and the second letter indicates the type after. '-' indicates that the path was not present, 'F' represents a regular file, `L' represents a symlink, 'C' represents a conflict, and 'G' represents a Git submodule.
cli: Add an option to diff to output only paths.
2024-06-19 17:19:51 +00:00
* `--name-only` — For each path, show only its path
Typically useful for shell commands like: `jj diff -r @- --name_only | xargs perl -pi -e's/OLD/NEW/g`
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
* `--git` — Show a Git-format diff
* `--color-words` — Show a word-level diff with changes indicated only by color
* `--tool <TOOL>` — Generate diff by external command
Add --context flag for diffs. Allows specifying the number of lines of context to show around diffs. The logic was already in place, just some plumbing was needed.
2024-03-02 00:57:43 +00:00
* `--context <CONTEXT>` — Number of lines of context to show
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
## `jj operation`
Commands for working with the operation log
For information about the operation log, see https://github.com/martinvonz/jj/blob/main/docs/operation-log.md.
**Usage:** `jj operation <COMMAND>`
###### **Subcommands:**
* `abandon` — Abandon operation history
* `log` — Show the operation log
* `restore` — Create a new operation that restores the repo to an earlier state
cli: sort operation subcommands
2024-06-22 01:19:38 +00:00
* `undo` — Create a new operation that undoes an earlier operation
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
## `jj operation abandon`
Abandon operation history
To discard old operation history, use `jj op abandon ..<operation ID>`. It will abandon the specified operation and all its ancestors. The descendants will be reparented onto the root operation.
To discard recent operations, use `jj op restore <operation ID>` followed by `jj op abandon <operation ID>..@-`.
The abandoned operations, commits, and other unreachable objects can later be garbage collected by using `jj util gc` command.
**Usage:** `jj operation abandon <OPERATION>`
###### **Arguments:**
* `<OPERATION>` — The operation or operation range to abandon
## `jj operation log`
Show the operation log
**Usage:** `jj operation log [OPTIONS]`
###### **Options:**
cli: deprecate `-l` short alias for `--limit` in favour of `-n` This better matches `git log` and affects `jj log`, `jj op log` and `jj obslog`
2024-06-14 23:24:09 +00:00
* `-n`, `--limit <LIMIT>` — Limit number of operations to show
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
* `--no-graph` — Don't show the graph, show a flat list of operations
* `-T`, `--template <TEMPLATE>` — Render each operation using the given template
docs CLI Reference: upgrade `clap-markdown` to 0.1.4 Fixes important bugs. 🎉
2024-06-15 21:52:17 +00:00
For the syntax, see https://github.com/martinvonz/jj/blob/main/docs/templates.md
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
cli: sort operation subcommands
2024-06-22 01:19:38 +00:00
## `jj operation restore`
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
cli: sort operation subcommands
2024-06-22 01:19:38 +00:00
Create a new operation that restores the repo to an earlier state
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
cli: sort operation subcommands
2024-06-22 01:19:38 +00:00
This restores the repo to the state at the specified operation, effectively undoing all later operations. It does so by creating a new operation.
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
cli: sort operation subcommands
2024-06-22 01:19:38 +00:00
**Usage:** `jj operation restore [OPTIONS] <OPERATION>`
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
###### **Arguments:**
cli: sort operation subcommands
2024-06-22 01:19:38 +00:00
* `<OPERATION>` — The operation to restore to
docs CLI Reference: upgrade `clap-markdown` to 0.1.4 Fixes important bugs. 🎉
2024-06-15 21:52:17 +00:00
cli: sort operation subcommands
2024-06-22 01:19:38 +00:00
Use `jj op log` to find an operation to restore to. Use e.g. `jj --at-op=<operation ID> log` before restoring to an operation to see the state of the repo at that operation.
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
###### **Options:**
* `--what <WHAT>` — What portions of the local state to restore (can be repeated)
docs CLI Reference: upgrade `clap-markdown` to 0.1.4 Fixes important bugs. 🎉
2024-06-15 21:52:17 +00:00
This option is EXPERIMENTAL.
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
Default values: `repo`, `remote-tracking`
Possible values:
- `repo`:
The jj repo state and local branches
- `remote-tracking`:
The remote-tracking branches. Do not restore these if you'd like to push after the undo
cli: sort operation subcommands
2024-06-22 01:19:38 +00:00
## `jj operation undo`
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
cli: sort operation subcommands
2024-06-22 01:19:38 +00:00
Create a new operation that undoes an earlier operation
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
cli: sort operation subcommands
2024-06-22 01:19:38 +00:00
This undoes an individual operation by applying the inverse of the operation.
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
cli: sort operation subcommands
2024-06-22 01:19:38 +00:00
**Usage:** `jj operation undo [OPTIONS] [OPERATION]`
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
###### **Arguments:**
cli: sort operation subcommands
2024-06-22 01:19:38 +00:00
* `<OPERATION>` — The operation to undo
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
cli: sort operation subcommands
2024-06-22 01:19:38 +00:00
Use `jj op log` to find an operation to undo.
Default value: `@`
docs CLI Reference: upgrade `clap-markdown` to 0.1.4 Fixes important bugs. 🎉
2024-06-15 21:52:17 +00:00
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
###### **Options:**
* `--what <WHAT>` — What portions of the local state to restore (can be repeated)
docs CLI Reference: upgrade `clap-markdown` to 0.1.4 Fixes important bugs. 🎉
2024-06-15 21:52:17 +00:00
This option is EXPERIMENTAL.
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
Default values: `repo`, `remote-tracking`
Possible values:
- `repo`:
The jj repo state and local branches
- `remote-tracking`:
The remote-tracking branches. Do not restore these if you'd like to push after the undo
Implement jj parallelize Parallelize revisions by making them siblings Running `jj parallelize 1::2` will transform the history like this: ```text 3 | 3 2 / \ | -> 1 2 1 \ / | 0 0 ``` Each of the target revisions is rebased onto the parents of the root(s) of the target revset (not to be confused with the repo root). The children of the head(s) of the target revset are rebased onto the target revisions. The target revset is the union of the REVISIONS arguments. The target revset being parallelized must satisfy several conditions, otherwise the command will fail. 1. The heads of the target revset must not have different children. 2. The roots of the target revset must not have different parents. 3. The parents of all target revisions except the roots must also be parallelized. This means that the target revisions must be connected.
2024-03-31 12:46:55 +00:00
## `jj parallelize`
Parallelize revisions by making them siblings
Running `jj parallelize 1::2` will transform the history like this:
```text
3
| 3
2 / \
| -> 1 2
1 \ /
| 0
0
```
parallelize: make the command pass in more cases The checks are not needed by the new implementation, so just drop them.
2024-04-17 04:32:56 +00:00
The command effectively says "these revisions are actually independent",
meaning that they should no longer be ancestors/descendants of each other.
However, revisions outside the set that were previously ancestors of a
revision in the set will remain ancestors of it. For example, revision 0
above remains an ancestor of both 1 and 2. Similarly,
revisions outside the set that were previously descendants of a revision
in the set will remain descendants of it. For example, revision 3 above
remains a descendant of both 1 and 2.
Therefore, `jj parallelize '1 | 3'` is a no-op. That's because 2, which is
not in the target set, was a descendant of 1 before, so it remains a
descendant, and it was an ancestor of 3 before, so it remains an ancestor.
Implement jj parallelize Parallelize revisions by making them siblings Running `jj parallelize 1::2` will transform the history like this: ```text 3 | 3 2 / \ | -> 1 2 1 \ / | 0 0 ``` Each of the target revisions is rebased onto the parents of the root(s) of the target revset (not to be confused with the repo root). The children of the head(s) of the target revset are rebased onto the target revisions. The target revset is the union of the REVISIONS arguments. The target revset being parallelized must satisfy several conditions, otherwise the command will fail. 1. The heads of the target revset must not have different children. 2. The roots of the target revset must not have different parents. 3. The parents of all target revisions except the roots must also be parallelized. This means that the target revisions must be connected.
2024-03-31 12:46:55 +00:00
**Usage:** `jj parallelize [REVISIONS]...`
###### **Arguments:**
* `<REVISIONS>` — Revisions to parallelize
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
## `jj prev`
Improve the documentation of `jj prev` This will hopefully make it clear that `jj prev` does not move by [OFFSET] relative to `@`, which is a misconception that I had and I think others may also have. I am suggesting this change as a result of the vigorous discussion in these two issues: - https://github.com/martinvonz/jj/issues/3426 - https://github.com/martinvonz/jj/pull/3445 We should make similar changes to `jj next` as well since it follows similar rules.
2024-04-04 17:04:49 +00:00
Change the working copy revision relative to the parent revision
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
Improve the documentation of `jj prev` This will hopefully make it clear that `jj prev` does not move by [OFFSET] relative to `@`, which is a misconception that I had and I think others may also have. I am suggesting this change as a result of the vigorous discussion in these two issues: - https://github.com/martinvonz/jj/issues/3426 - https://github.com/martinvonz/jj/pull/3445 We should make similar changes to `jj next` as well since it follows similar rules.
2024-04-04 17:04:49 +00:00
The command creates a new empty working copy revision that is the child of
an ancestor `offset` revisions behind the parent of the current working
copy.
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
Improve the documentation of `jj prev` This will hopefully make it clear that `jj prev` does not move by [OFFSET] relative to `@`, which is a misconception that I had and I think others may also have. I am suggesting this change as a result of the vigorous discussion in these two issues: - https://github.com/martinvonz/jj/issues/3426 - https://github.com/martinvonz/jj/pull/3445 We should make similar changes to `jj next` as well since it follows similar rules.
2024-04-04 17:04:49 +00:00
For example, when the offset is 1:
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
docs: fixup to b318b200, mark code blocks in help as text This prevents rust doctests from trying to compile the code blocks. I don't think we use doctests much or at all, but I'd like `cargo insta test --test-runner nextest --accept --workspace` to pass. Unfortunately, this affects the output of `jj help` as well, but I can't think of a workaround for that.
2024-01-30 22:59:31 +00:00
```text
Improve the documentation of `jj prev` This will hopefully make it clear that `jj prev` does not move by [OFFSET] relative to `@`, which is a misconception that I had and I think others may also have. I am suggesting this change as a result of the vigorous discussion in these two issues: - https://github.com/martinvonz/jj/issues/3426 - https://github.com/martinvonz/jj/pull/3445 We should make similar changes to `jj next` as well since it follows similar rules.
2024-04-04 17:04:49 +00:00
D @ D
|/ |
A => A @
| |/
B B
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
```
Improve the documentation of `jj prev` This will hopefully make it clear that `jj prev` does not move by [OFFSET] relative to `@`, which is a misconception that I had and I think others may also have. I am suggesting this change as a result of the vigorous discussion in these two issues: - https://github.com/martinvonz/jj/issues/3426 - https://github.com/martinvonz/jj/pull/3445 We should make similar changes to `jj next` as well since it follows similar rules.
2024-04-04 17:04:49 +00:00
If `--edit` is passed, the working copy revision is changed to the parent of
the current working copy revision.
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
docs: fixup to b318b200, mark code blocks in help as text This prevents rust doctests from trying to compile the code blocks. I don't think we use doctests much or at all, but I'd like `cargo insta test --test-runner nextest --accept --workspace` to pass. Unfortunately, this affects the output of `jj help` as well, but I can't think of a workaround for that.
2024-01-30 22:59:31 +00:00
```text
Improve the documentation of `jj prev` This will hopefully make it clear that `jj prev` does not move by [OFFSET] relative to `@`, which is a misconception that I had and I think others may also have. I am suggesting this change as a result of the vigorous discussion in these two issues: - https://github.com/martinvonz/jj/issues/3426 - https://github.com/martinvonz/jj/pull/3445 We should make similar changes to `jj next` as well since it follows similar rules.
2024-04-04 17:04:49 +00:00
D @ D
|/ |
C => @
| |
B B
| |
A A
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
```
Improve the documentation of `jj prev` This will hopefully make it clear that `jj prev` does not move by [OFFSET] relative to `@`, which is a misconception that I had and I think others may also have. I am suggesting this change as a result of the vigorous discussion in these two issues: - https://github.com/martinvonz/jj/issues/3426 - https://github.com/martinvonz/jj/pull/3445 We should make similar changes to `jj next` as well since it follows similar rules.
2024-04-04 17:04:49 +00:00
If the working copy revision already has visible children, then `--edit` is
implied.
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
Rename the "AMOUNT" argument for `jj prev` and `jj next` to OFFSET Offset is a more descriptive noun for this argument. This commit also tweaks the help message for the argument. This isn't an option/flag, so this change should be transparent to users.
2024-04-03 22:08:59 +00:00
**Usage:** `jj prev [OPTIONS] [OFFSET]`
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
###### **Arguments:**
Rename the "AMOUNT" argument for `jj prev` and `jj next` to OFFSET Offset is a more descriptive noun for this argument. This commit also tweaks the help message for the argument. This isn't an option/flag, so this change should be transparent to users.
2024-04-03 22:08:59 +00:00
* `<OFFSET>` — How many revisions to move backward. Moves to the parent by default
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
Default value: `1`
###### **Options:**
Add short a `-e` alias for `--edit` to prev and next I'm not sure if this was an intentional omission, but I think it would be useful to have `-e` as a short flag for `--edit`. I don't usually edit commits, but I do use `prev` and `next` with edit to navigate to a commit that I want to squash. Often this is easier than typing `--from` and `--into` plus the change IDs. If people want to edit commits we shouldn't stand in their way.
2024-04-20 12:14:04 +00:00
* `-e`, `--edit` — Edit the parent directly, instead of moving the working-copy commit
next/prev: Implement `next/prev --conflict` This allows users to jump to the next conflict in the ancestors or children of the start commit. Continues work on #2126 Co-Authored-By: Noah Mayr <dev@noahmayr.com>
2024-02-18 17:57:55 +00:00
* `--conflict` — Jump to the previous conflicted ancestor
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
## `jj rebase`
Move revisions to different parent(s)
There are three different ways of specifying which revisions to rebase:
`-b` to rebase a whole branch, `-s` to rebase a revision and its
descendants, and `-r` to rebase a single commit. If none of them is
specified, it defaults to `-b @`.
With `-s`, the command rebases the specified revision and its descendants
onto the destination. For example, `jj rebase -s M -d O` would transform
your history like this (letters followed by an apostrophe are post-rebase
versions):
docs: fixup to b318b200, mark code blocks in help as text This prevents rust doctests from trying to compile the code blocks. I don't think we use doctests much or at all, but I'd like `cargo insta test --test-runner nextest --accept --workspace` to pass. Unfortunately, this affects the output of `jj help` as well, but I can't think of a workaround for that.
2024-01-30 22:59:31 +00:00
```text
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
O N'
| |
| N M'
| | |
| M O
| | => |
| | L | L
| |/ | |
| K | K
|/ |/
J J
```
With `-b`, the command rebases the whole "branch" containing the specified
revision. A "branch" is the set of commits that includes:
* the specified revision and ancestors that are not also ancestors of the
destination
* all descendants of those commits
In other words, `jj rebase -b X -d Y` rebases commits in the revset
`(Y..X)::` (which is equivalent to `jj rebase -s 'roots(Y..X)' -d Y` for a
single root). For example, either `jj rebase -b L -d O` or `jj rebase -b M
-d O` would transform your history like this (because `L` and `M` are on the
same "branch", relative to the destination):
docs: fixup to b318b200, mark code blocks in help as text This prevents rust doctests from trying to compile the code blocks. I don't think we use doctests much or at all, but I'd like `cargo insta test --test-runner nextest --accept --workspace` to pass. Unfortunately, this affects the output of `jj help` as well, but I can't think of a workaround for that.
2024-01-30 22:59:31 +00:00
```text
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
O N'
| |
| N M'
| | |
| M | L'
| | => |/
| | L K'
| |/ |
| K O
|/ |
J J
```
rebase: allow `-r` to accept multiple revisions
2024-04-23 14:47:55 +00:00
With `-r`, the command rebases only the specified revisions onto the
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
destination. Any "hole" left behind will be filled by rebasing descendants
onto the specified revision's parent(s). For example, `jj rebase -r K -d M`
would transform your history like this:
docs: fixup to b318b200, mark code blocks in help as text This prevents rust doctests from trying to compile the code blocks. I don't think we use doctests much or at all, but I'd like `cargo insta test --test-runner nextest --accept --workspace` to pass. Unfortunately, this affects the output of `jj help` as well, but I can't think of a workaround for that.
2024-01-30 22:59:31 +00:00
```text
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
M K'
| |
| L M
| | => |
| K | L'
|/ |/
J J
```
Note that you can create a merge commit by repeating the `-d` argument.
For example, if you realize that commit L actually depends on commit M in
order to work (in addition to its current parent K), you can run `jj rebase
-s L -d K -d M`:
docs: fixup to b318b200, mark code blocks in help as text This prevents rust doctests from trying to compile the code blocks. I don't think we use doctests much or at all, but I'd like `cargo insta test --test-runner nextest --accept --workspace` to pass. Unfortunately, this affects the output of `jj help` as well, but I can't think of a workaround for that.
2024-01-30 22:59:31 +00:00
```text
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
M L'
| |\
| L M |
| | => | |
| K | K
|/ |/
J J
```
cli: document that we create a new working-copy commit for abandoned one When we abandon a working-copy commit, we create a new working-copy commit on top. This behave is very useful, but it's not obvious. Let's document it. Thankfully, 2bbefcc3383f (rewrite: default to not simplifying ancestor merges) means that there are much fewer commands where we need to document this behavior.
2024-02-26 00:39:35 +00:00
If a working-copy commit gets abandoned, it will be given a new, empty
commit. This is true in general; it is not specific to this command.
rebase: add `--insert-after` and `--insert-before` options for `--revisions`
2024-03-29 13:32:55 +00:00
**Usage:** `jj rebase [OPTIONS] <--destination <DESTINATION>|--insert-after <INSERT_AFTER>|--insert-before <INSERT_BEFORE>>`
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
###### **Options:**
* `-b`, `--branch <BRANCH>` — Rebase the whole branch relative to destination's ancestors (can be repeated)
docs CLI Reference: upgrade `clap-markdown` to 0.1.4 Fixes important bugs. 🎉
2024-06-15 21:52:17 +00:00
`jj rebase -b=br -d=dst` is equivalent to `jj rebase '-s=roots(dst..br)' -d=dst`.
If none of `-b`, `-s`, or `-r` is provided, then the default is `-b @`.
Fix the description of the --source arg in the jj rebase --help docs
2024-03-30 23:00:28 +00:00
* `-s`, `--source <SOURCE>` — Rebase specified revision(s) together with their trees of descendants (can be repeated)
docs CLI Reference: upgrade `clap-markdown` to 0.1.4 Fixes important bugs. 🎉
2024-06-15 21:52:17 +00:00
Each specified revision will become a direct child of the destination revision(s), even if some of the source revisions are descendants of others.
If none of `-b`, `-s`, or `-r` is provided, then the default is `-b @`.
rebase: allow `-r` to accept multiple revisions
2024-04-23 14:47:55 +00:00
* `-r`, `--revisions <REVISIONS>` — Rebase the given revisions, rebasing descendants onto this revision's parent(s)
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
docs CLI Reference: upgrade `clap-markdown` to 0.1.4 Fixes important bugs. 🎉
2024-06-15 21:52:17 +00:00
Unlike `-s` or `-b`, you may `jj rebase -r` a revision `A` onto a descendant of `A`.
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
docs CLI Reference: upgrade `clap-markdown` to 0.1.4 Fixes important bugs. 🎉
2024-06-15 21:52:17 +00:00
If none of `-b`, `-s`, or `-r` is provided, then the default is `-b @`.
* `-d`, `--destination <DESTINATION>` — The revision(s) to rebase onto (can be repeated to create a merge commit)
* `-A`, `--insert-after <INSERT_AFTER>` — The revision(s) to insert after (can be repeated to create a merge commit)
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
docs CLI Reference: upgrade `clap-markdown` to 0.1.4 Fixes important bugs. 🎉
2024-06-15 21:52:17 +00:00
Only works with `-r`.
* `-B`, `--insert-before <INSERT_BEFORE>` — The revision(s) to insert before (can be repeated to create a merge commit)
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
docs CLI Reference: upgrade `clap-markdown` to 0.1.4 Fixes important bugs. 🎉
2024-06-15 21:52:17 +00:00
Only works with `-r`.
* `--skip-empty` — If true, when rebasing would produce an empty commit, the commit is abandoned. It will not be abandoned if it was already empty before the rebase. Will never skip merge commits with multiple non-empty parents
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
## `jj resolve`
Resolve a conflicted file with an external merge tool
Only conflicts that can be resolved with a 3-way merge are supported. See docs for merge tool configuration instructions.
Note that conflicts can also be resolved without using this command. You may edit the conflict markers in the conflicted file directly with a text editor.
**Usage:** `jj resolve [OPTIONS] [PATHS]...`
###### **Arguments:**
* `<PATHS>` — Restrict to these paths when searching for a conflict to resolve. We will attempt to resolve the first conflict we can find. You can use the `--list` argument to find paths to use here
###### **Options:**
* `-r`, `--revision <REVISION>`
Default value: `@`
* `-l`, `--list` — Instead of resolving one conflict, list all the conflicts
cli: add --tool=<name> option to diff/merge editing commands I didn't add e2e tests to all commands, but the added tests should cover diff_editor/diff_selector/merge_editor() calls. Closes #2575
2024-03-01 14:49:22 +00:00
* `--tool <NAME>` — Specify 3-way merge tool to be used
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
## `jj restore`
Restore paths from another revision
That means that the paths get the same content in the destination (`--to`) as they had in the source (`--from`). This is typically used for undoing changes to some paths in the working copy (`jj restore <paths>`).
If only one of `--from` or `--to` is specified, the other one defaults to the working copy.
When neither `--from` nor `--to` is specified, the command restores into the working copy from its parent(s). `jj restore` without arguments is similar to `jj abandon`, except that it leaves an empty revision with its description and other metadata preserved.
See `jj diffedit` if you'd like to restore portions of files rather than entire files.
**Usage:** `jj restore [OPTIONS] [PATHS]...`
###### **Arguments:**
* `<PATHS>` — Restore only these paths (instead of all paths)
###### **Options:**
* `--from <FROM>` — Revision to restore from (source)
* `--to <TO>` — Revision to restore into (destination)
docs CLI Reference: upgrade `clap-markdown` to 0.1.4 Fixes important bugs. 🎉
2024-06-15 21:52:17 +00:00
* `-c`, `--changes-in <REVISION>` — Undo the changes in a revision as compared to the merge of its parents.
This undoes the changes that can be seen with `jj diff -r REVISION`. If `REVISION` only has a single parent, this option is equivalent to `jj restore --to REVISION --from REVISION-`.
The default behavior of `jj restore` is equivalent to `jj restore --changes-in @`.
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
## `jj root`
Show the current workspace root directory
**Usage:** `jj root`
## `jj show`
Show commit description and changes in a revision
**Usage:** `jj show [OPTIONS] [REVISION]`
###### **Arguments:**
* `<REVISION>` — Show changes in this revision, compared to its parent(s)
Default value: `@`
###### **Options:**
cli: make `jj show` accept a template to render its output
2024-02-10 06:01:47 +00:00
* `-T`, `--template <TEMPLATE>` — Render a revision using the given template
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
docs CLI Reference: upgrade `clap-markdown` to 0.1.4 Fixes important bugs. 🎉
2024-06-15 21:52:17 +00:00
For the syntax, see https://github.com/martinvonz/jj/blob/main/docs/templates.md
* `-s`, `--summary` — For each path, show only whether it was modified, added, or deleted
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
* `--stat` — Show a histogram of the changes
* `--types` — For each path, show only its type before and after
docs CLI Reference: upgrade `clap-markdown` to 0.1.4 Fixes important bugs. 🎉
2024-06-15 21:52:17 +00:00
The diff is shown as two letters. The first letter indicates the type before and the second letter indicates the type after. '-' indicates that the path was not present, 'F' represents a regular file, `L' represents a symlink, 'C' represents a conflict, and 'G' represents a Git submodule.
cli: Add an option to diff to output only paths.
2024-06-19 17:19:51 +00:00
* `--name-only` — For each path, show only its path
Typically useful for shell commands like: `jj diff -r @- --name_only | xargs perl -pi -e's/OLD/NEW/g`
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
* `--git` — Show a Git-format diff
* `--color-words` — Show a word-level diff with changes indicated only by color
* `--tool <TOOL>` — Generate diff by external command
Add --context flag for diffs. Allows specifying the number of lines of context to show around diffs. The logic was already in place, just some plumbing was needed.
2024-03-02 00:57:43 +00:00
* `--context <CONTEXT>` — Number of lines of context to show
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
## `jj sparse`
Manage which paths from the working-copy commit are present in the working copy
**Usage:** `jj sparse <COMMAND>`
###### **Subcommands:**
cli: sort config/sparse subcommands in lexicographical order
2024-06-20 07:54:28 +00:00
* `edit` — Start an editor to update the patterns that are present in the working copy
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
* `list` — List the patterns that are currently present in the working copy
sparse: extract "set --reset" to subcommand Since --reset conflicts with the other flags, "set --reset" seems odd.
2024-03-28 12:19:24 +00:00
* `reset` — Reset the patterns to include all files in the working copy
cli: sort config/sparse subcommands in lexicographical order
2024-06-20 07:54:28 +00:00
* `set` — Update the patterns that are present in the working copy
## `jj sparse edit`
Start an editor to update the patterns that are present in the working copy
**Usage:** `jj sparse edit`
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
## `jj sparse list`
List the patterns that are currently present in the working copy
By default, a newly cloned or initialized repo will have have a pattern matching all files from the repo root. That pattern is rendered as `.` (a single period).
**Usage:** `jj sparse list`
cli: sort config/sparse subcommands in lexicographical order
2024-06-20 07:54:28 +00:00
## `jj sparse reset`
Reset the patterns to include all files in the working copy
**Usage:** `jj sparse reset`
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
## `jj sparse set`
Update the patterns that are present in the working copy
For example, if all you need is the `README.md` and the `lib/` directory, use `jj sparse set --clear --add README.md --add lib`. If you no longer need the `lib` directory, use `jj sparse set --remove lib`.
**Usage:** `jj sparse set [OPTIONS]`
###### **Options:**
* `--add <ADD>` — Patterns to add to the working copy
* `--remove <REMOVE>` — Patterns to remove from the working copy
* `--clear` — Include no files in the working copy (combine with --add)
## `jj split`
Split a revision in two
docs: stop mentioning `meld` as the default diff editor The default is now `:builtin`.
2024-04-12 23:42:07 +00:00
Starts a [diff editor] on the changes in the revision. Edit the right side of the diff until it has the content you want in the first revision. Once you close the editor, your edited content will replace the previous revision. The remaining changes will be put in a new revision on top.
[diff editor]: https://martinvonz.github.io/jj/latest/config/#editing-diffs
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
If the change you split had a description, you will be asked to enter a change description for each commit. If the change did not have a description, the second part will not get a description, and you will be asked for a description only for the first part.
Refuse to split an empty commit with `jj split`. Rationale: The user may be confused by the empty diff in the diff editor tool if they accidentally run `jj split` on a wrong (empty) commit.
2024-05-10 14:44:49 +00:00
Splitting an empty commit is not supported because the same effect can be achieved with `jj new`.
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
**Usage:** `jj split [OPTIONS] [PATHS]...`
###### **Arguments:**
* `<PATHS>` — Put these paths in the first commit
###### **Options:**
* `-i`, `--interactive` — Interactively choose which parts to split. This is the default if no paths are provided
cli: add --tool=<name> option to diff/merge editing commands I didn't add e2e tests to all commands, but the added tests should cover diff_editor/diff_selector/merge_editor() calls. Closes #2575
2024-03-01 14:49:22 +00:00
* `--tool <NAME>` — Specify diff editor to be used (implies --interactive)
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
* `-r`, `--revision <REVISION>` — The revision to split
Default value: `@`
cli: deprecate `jj split --siblings` in favor of `jj split --parallel` This better matches `jj parallelize`.
2024-06-12 00:07:08 +00:00
* `-p`, `--parallel` — Split the revision into two parallel revisions instead of a parent and child
Add a --siblings option to the jj split command If the --siblings option is used, the target commit is split into two sibling commits instead of parent and child commits. Any children of the original commit will have both siblings as their new parents. #2274
2024-02-08 01:37:07 +00:00
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
## `jj squash`
squash: learn `--from/--into` flags This was proposed by @Brixy in https://github.com/martinvonz/jj/discussions/2882 a while ago. There seems to be pretty strong consensus that it's a good idea. I've copied the added test cases from `test_move_command.rs`, just replacing `move` by `squash`, `--to` by `--into`, and deleting the test of a no-arg invocation (`jj move` fails, `jj squash` does not - it defaults to squashing into the parent).
2024-03-10 18:50:14 +00:00
Move changes from a revision into another revision
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
squash: learn `--from/--into` flags This was proposed by @Brixy in https://github.com/martinvonz/jj/discussions/2882 a while ago. There seems to be pretty strong consensus that it's a good idea. I've copied the added test cases from `test_move_command.rs`, just replacing `move` by `squash`, `--to` by `--into`, and deleting the test of a no-arg invocation (`jj move` fails, `jj squash` does not - it defaults to squashing into the parent).
2024-03-10 18:50:14 +00:00
With the `-r` option, moves the changes from the specified revision to the parent revision. Fails if there are several parent revisions (i.e., the given revision is a merge).
With the `--from` and/or `--into` options, moves changes from/to the given revisions. If either is left out, it defaults to the working-copy commit. For example, `jj squash --into @--` moves changes from the working-copy commit to the grandparent.
If, after moving changes out, the source revision is empty compared to its parent(s), it will be abandoned. Without `--interactive`, the source revision will always be empty.
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
If the source became empty and both the source and destination had a non-empty description, you will be asked for the combined description. If either was empty, then the other one will be used.
cli: document that we create a new working-copy commit for abandoned one When we abandon a working-copy commit, we create a new working-copy commit on top. This behave is very useful, but it's not obvious. Let's document it. Thankfully, 2bbefcc3383f (rewrite: default to not simplifying ancestor merges) means that there are much fewer commands where we need to document this behavior.
2024-02-26 00:39:35 +00:00
If a working-copy commit gets abandoned, it will be given a new, empty commit. This is true in general; it is not specific to this command.
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
**Usage:** `jj squash [OPTIONS] [PATHS]...`
###### **Arguments:**
* `<PATHS>` — Move only changes to these paths (instead of all paths)
###### **Options:**
squash: make `-r` argument optional in clap I'm soon going to make `jj squash` accept either `-r` or `--from/--to`, which means `-r` will then be optional. This patch prepares for that already, since it also simplifies the code a little (and improves it so we warn if the user does `jj squash -r @ nonexistent`).
2024-03-10 21:29:08 +00:00
* `-r`, `--revision <REVISION>` — Revision to squash into its parent (default: @)
squash: accept multiple --from arguments Since multiple revisions can be specified, there's no reason to reject multiple --from arguments.
2024-04-03 03:25:06 +00:00
* `--from <FROM>` — Revision(s) to squash from (default: @)
squash: learn `--from/--into` flags This was proposed by @Brixy in https://github.com/martinvonz/jj/discussions/2882 a while ago. There seems to be pretty strong consensus that it's a good idea. I've copied the added test cases from `test_move_command.rs`, just replacing `move` by `squash`, `--to` by `--into`, and deleting the test of a no-arg invocation (`jj move` fails, `jj squash` does not - it defaults to squashing into the parent).
2024-03-10 18:50:14 +00:00
* `--into <INTO>` — Revision to squash into (default: @)
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
* `-m`, `--message <MESSAGE>` — The description to use for squashed revision (don't open editor)
Add a --use-destination-message option to `jj squash` if `--use-destination-message/-u` is passed to `jj squash`, the resulting revision will use the description of the destination revision and the description(s) of the source revision(s) will be discarded.
2024-04-02 15:19:12 +00:00
* `-u`, `--use-destination-message` — Use the description of the destination revision and discard the description(s) of the source revision(s)
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
* `-i`, `--interactive` — Interactively choose which parts to squash
cli: add --tool=<name> option to diff/merge editing commands I didn't add e2e tests to all commands, but the added tests should cover diff_editor/diff_selector/merge_editor() calls. Closes #2575
2024-03-01 14:49:22 +00:00
* `--tool <NAME>` — Specify diff editor to be used (implies --interactive)
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
## `jj status`
Show high-level repo status
This includes:
* The working copy commit and its (first) parent, and a summary of the changes between them
* Conflicted branches (see https://github.com/martinvonz/jj/blob/main/docs/branches.md)
cli: support filtering by paths in `status`
2024-04-02 20:17:03 +00:00
**Usage:** `jj status [PATHS]...`
###### **Arguments:**
* `<PATHS>` — Restrict the status display to these paths
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
## `jj tag`
Manage tags
**Usage:** `jj tag <COMMAND>`
###### **Subcommands:**
* `list` — List tags
## `jj tag list`
List tags
cli: migrate "tag list" to template I'm going to add more detailed output there. This is a step towards "branch list" template. "tag list -T" wouldn't be that useful, but it shares primitives with "branch list -T".
2024-04-25 09:23:12 +00:00
**Usage:** `jj tag list [OPTIONS] [NAMES]...`
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
###### **Arguments:**
* `<NAMES>` — Show tags whose local name matches
docs CLI Reference: upgrade `clap-markdown` to 0.1.4 Fixes important bugs. 🎉
2024-06-15 21:52:17 +00:00
By default, the specified name matches exactly. Use `glob:` prefix to select tags by wildcard pattern. For details, see https://github.com/martinvonz/jj/blob/main/docs/revsets.md#string-patterns.
cli: migrate "tag list" to template I'm going to add more detailed output there. This is a step towards "branch list" template. "tag list -T" wouldn't be that useful, but it shares primitives with "branch list -T".
2024-04-25 09:23:12 +00:00
###### **Options:**
* `-T`, `--template <TEMPLATE>` — Render each tag using the given template
docs CLI Reference: upgrade `clap-markdown` to 0.1.4 Fixes important bugs. 🎉
2024-06-15 21:52:17 +00:00
All 0-argument methods of the `RefName` type are available as keywords.
For the syntax, see https://github.com/martinvonz/jj/blob/main/docs/templates.md
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
## `jj util`
Infrequently used commands such as for generating shell completions
**Usage:** `jj util <COMMAND>`
###### **Subcommands:**
* `completion` — Print a command-line-completion script
* `gc` — Run backend-dependent garbage collection
* `mangen` — Print a ROFF (manpage)
* `markdown-help` — Print the CLI help for all subcommands in Markdown
* `config-schema` — Print the JSON schema for the jj TOML config format
## `jj util completion`
Print a command-line-completion script
cli: minor updates to `jj util completion` A few minor updates after 0f27152 AKA #2945 Specifically, I tried to change the help text so that it looks better as Markdown. I also reworded the deprecation warning and added a hint.
2024-02-04 21:39:30 +00:00
Apply it by running one of these:
cli `jj util completion --help`: Make the terminal output a bit prettier Cc: https://github.com/martinvonz/jj/pull/2949#issuecomment-2098710774
2024-05-07 21:35:31 +00:00
- Bash: `source <(jj util completion bash)`
- Fish: `jj util completion fish | source`
- Nushell:
completion: Add support for Nushell completions
2024-02-16 20:23:41 +00:00
```nu
jj util completion nushell | save "completions-jj.nu"
use "completions-jj.nu" * # Or `source "completions-jj.nu"`
```
cli `jj util completion --help`: Make the terminal output a bit prettier Cc: https://github.com/martinvonz/jj/pull/2949#issuecomment-2098710774
2024-05-07 21:35:31 +00:00
- Zsh:
cli: minor updates to `jj util completion` A few minor updates after 0f27152 AKA #2945 Specifically, I tried to change the help text so that it looks better as Markdown. I also reworded the deprecation warning and added a hint.
2024-02-04 21:39:30 +00:00
```shell
autoload -U compinit
compinit
completion: Update docs for new style with positional argument
2024-02-16 22:13:08 +00:00
source <(jj util completion zsh)
cli: minor updates to `jj util completion` A few minor updates after 0f27152 AKA #2945 Specifically, I tried to change the help text so that it looks better as Markdown. I also reworded the deprecation warning and added a hint.
2024-02-04 21:39:30 +00:00
```
cli: use a positional argument for `jj util completion` this has two main advantages: - it makes it clear that the shells are mutually exclusive - it allows us to extend the command with shell-specific options in the future if necessary as a happy accident, it also adds support for `elvish` and `powershell`. for backwards compatibility, this also keeps the existing options as hidden flags. i am not super happy with how the new help looks; the instructions for setting up the shell are squished together and IMO a little harder to read. i'm open to suggestions.
2024-02-04 19:49:20 +00:00
**Usage:** `jj util completion [SHELL]`
###### **Arguments:**
* `<SHELL>`
completion: Add support for Nushell completions
2024-02-16 20:23:41 +00:00
Possible values: `bash`, `elvish`, `fish`, `nushell`, `power-shell`, `zsh`
cli: use a positional argument for `jj util completion` this has two main advantages: - it makes it clear that the shells are mutually exclusive - it allows us to extend the command with shell-specific options in the future if necessary as a happy accident, it also adds support for `elvish` and `powershell`. for backwards compatibility, this also keeps the existing options as hidden flags. i am not super happy with how the new help looks; the instructions for setting up the shell are squished together and IMO a little harder to read. i'm open to suggestions.
2024-02-04 19:49:20 +00:00
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
## `jj util gc`
Run backend-dependent garbage collection
**Usage:** `jj util gc [OPTIONS]`
###### **Options:**
* `--expire <EXPIRE>` — Time threshold
docs CLI Reference: upgrade `clap-markdown` to 0.1.4 Fixes important bugs. 🎉
2024-06-15 21:52:17 +00:00
By default, only obsolete objects and operations older than 2 weeks are pruned.
Only the string "now" can be passed to this parameter. Support for arbitrary absolute and relative timestamps will come in a subsequent release.
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
## `jj util mangen`
Print a ROFF (manpage)
**Usage:** `jj util mangen`
## `jj util markdown-help`
Print the CLI help for all subcommands in Markdown
**Usage:** `jj util markdown-help`
## `jj util config-schema`
Print the JSON schema for the jj TOML config format
**Usage:** `jj util config-schema`
## `jj undo`
Undo an operation (shortcut for `jj op undo`)
**Usage:** `jj undo [OPTIONS] [OPERATION]`
###### **Arguments:**
* `<OPERATION>` — The operation to undo
docs CLI Reference: upgrade `clap-markdown` to 0.1.4 Fixes important bugs. 🎉
2024-06-15 21:52:17 +00:00
Use `jj op log` to find an operation to undo.
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
Default value: `@`
###### **Options:**
* `--what <WHAT>` — What portions of the local state to restore (can be repeated)
docs CLI Reference: upgrade `clap-markdown` to 0.1.4 Fixes important bugs. 🎉
2024-06-15 21:52:17 +00:00
This option is EXPERIMENTAL.
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
Default values: `repo`, `remote-tracking`
Possible values:
- `repo`:
The jj repo state and local branches
- `remote-tracking`:
The remote-tracking branches. Do not restore these if you'd like to push after the undo
## `jj unsquash`
Move changes from a revision's parent into the revision
After moving the changes out of the parent, the child revision will have the same content state as before. If moving the change out of the parent change made it empty compared to its parent, it will be abandoned. Without `--interactive`, the parent change will always become empty.
If the source became empty and both the source and destination had a non-empty description, you will be asked for the combined description. If either was empty, then the other one will be used.
cli: document that we create a new working-copy commit for abandoned one When we abandon a working-copy commit, we create a new working-copy commit on top. This behave is very useful, but it's not obvious. Let's document it. Thankfully, 2bbefcc3383f (rewrite: default to not simplifying ancestor merges) means that there are much fewer commands where we need to document this behavior.
2024-02-26 00:39:35 +00:00
If a working-copy commit gets abandoned, it will be given a new, empty commit. This is true in general; it is not specific to this command.
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
**Usage:** `jj unsquash [OPTIONS]`
###### **Options:**
* `-r`, `--revision <REVISION>`
Default value: `@`
* `-i`, `--interactive` — Interactively choose which parts to unsquash
cli: add --tool=<name> option to diff/merge editing commands I didn't add e2e tests to all commands, but the added tests should cover diff_editor/diff_selector/merge_editor() calls. Closes #2575
2024-03-01 14:49:22 +00:00
* `--tool <NAME>` — Specify diff editor to be used (implies --interactive)
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
## `jj untrack`
Stop tracking specified paths in the working copy
**Usage:** `jj untrack <PATHS>...`
###### **Arguments:**
docs CLI Reference: upgrade `clap-markdown` to 0.1.4 Fixes important bugs. 🎉
2024-06-15 21:52:17 +00:00
* `<PATHS>` — Paths to untrack. They must already be ignored.
The paths could be ignored via a .gitignore or .git/info/exclude (in colocated repos).
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
## `jj version`
Display version information
**Usage:** `jj version`
## `jj workspace`
Commands for working with workspaces
Workspaces let you add additional working copies attached to the same repo. A common use case is so you can run a slow build or test in one workspace while you're continuing to write code in another workspace.
Each workspace has its own working-copy commit. When you have more than one workspace attached to a repo, they are indicated by `@<workspace name>` in `jj log`.
cli: make new workspace inherit sparse pattern from old workspace
2024-02-17 17:04:21 +00:00
Each workspace also has own sparse patterns.
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
**Usage:** `jj workspace <COMMAND>`
###### **Subcommands:**
* `add` — Add a workspace
* `forget` — Stop tracking a workspace's working-copy commit in the repo
* `list` — List workspaces
* `root` — Show the current workspace root directory
* `update-stale` — Update a workspace that has become stale
## `jj workspace add`
Add a workspace
cli: make new workspace inherit sparse pattern from old workspace
2024-02-17 17:04:21 +00:00
Sparse patterns will be copied over from the current workspace.
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
**Usage:** `jj workspace add [OPTIONS] <DESTINATION>`
###### **Arguments:**
* `<DESTINATION>` — Where to create the new workspace
###### **Options:**
* `--name <NAME>` — A name for the workspace
docs CLI Reference: upgrade `clap-markdown` to 0.1.4 Fixes important bugs. 🎉
2024-06-15 21:52:17 +00:00
To override the default, which is the basename of the destination directory.
* `-r`, `--revision <REVISION>` — A list of parent revisions for the working-copy commit of the newly created workspace. You may specify nothing, or any number of parents.
If no revisions are specified, the new workspace will be created, and its working-copy commit will exist on top of the parent(s) of the working-copy commit in the current workspace, i.e. they will share the same parent(s).
If any revisions are specified, the new workspace will be created, and the new working-copy commit will be created with all these revisions as parents, i.e. the working-copy commit will exist as if you had run `jj new r1 r2 r3 ...`.
docs: store output of `jj util markdown-help`, render it on the website I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
2024-01-28 03:31:27 +00:00
## `jj workspace forget`
Stop tracking a workspace's working-copy commit in the repo
The workspace will not be touched on disk. It can be deleted from disk before or after running this command.
**Usage:** `jj workspace forget [WORKSPACES]...`
###### **Arguments:**
* `<WORKSPACES>` — Names of the workspaces to forget. By default, forgets only the current workspace
## `jj workspace list`
List workspaces
**Usage:** `jj workspace list`
## `jj workspace root`
Show the current workspace root directory
**Usage:** `jj workspace root`
## `jj workspace update-stale`
Update a workspace that has become stale
For information about stale working copies, see https://github.com/martinvonz/jj/blob/main/docs/working-copy.md.
**Usage:** `jj workspace update-stale`
<hr/>
<small><i>
This document was generated automatically by
<a href="https://crates.io/crates/clap-markdown"><code>clap-markdown</code></a>.
</i></small>
Copy permalink