From 1410f2bee79803672975a53578269c4997d102fa Mon Sep 17 00:00:00 2001 From: Lukas Wirth Date: Fri, 13 Sep 2024 07:25:47 +0200 Subject: [PATCH] docs: Remove trailing whitespace in markdown files --- CHANGELOG.md | 10 +- README.md | 16 +-- cli/src/config/README.md | 2 +- docs/FAQ.md | 18 ++-- docs/cli-reference.md | 1 - docs/community_tools.md | 20 ++-- docs/config.md | 6 +- docs/contributing.md | 24 ++--- docs/design/copy-tracking.md | 4 +- docs/design/run.md | 182 +++++++++++++++++------------------ docs/design_doc_blueprint.md | 12 +-- docs/design_docs.md | 21 ++-- docs/git-compatibility.md | 4 +- docs/glossary.md | 2 +- docs/revsets.md | 4 +- docs/templates.md | 4 +- docs/testimonials.md | 20 ++-- docs/tutorial.md | 2 +- docs/windows.md | 4 +- docs/working-copy.md | 2 +- 20 files changed, 178 insertions(+), 180 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 12acfe08ba..243cd589ac 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -23,11 +23,11 @@ to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). * `jj branch` has been deprecated in favor of `jj bookmark`. - **Rationale:** Jujutsu's branches don't behave like Git branches, which a + **Rationale:** Jujutsu's branches don't behave like Git branches, which a confused many newcomers, as they expected a similar behavior given the name. We've renamed them to "bookmarks" to match the actual behavior, as we think - that describes them better, and they also behave similar to Mercurial's - bookmarks. + that describes them better, and they also behave similar to Mercurial's + bookmarks. * The `git.push-branch-prefix` config has been deprecated in favor of `git.push-bookmark-prefix`. @@ -87,7 +87,7 @@ to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). * A tilde (`~`) at the start of the path will now be expanded to the user's home directory when configuring a `signing.key` for SSH commit signing. - + * When reconfiguring the author, warn that the working copy won't be updated ### Fixed bugs @@ -187,7 +187,7 @@ Thanks to the people who made this release happen! * `jj backout` can now back out multiple commits at once. -* `jj git clone some/nested/path` now creates the full directory tree for +* `jj git clone some/nested/path` now creates the full directory tree for nested destination paths if they don't exist. * String patterns now support caseā€insensitive matching by suffixing any diff --git a/README.md b/README.md index 367b96b1fa..c6e7687716 100644 --- a/README.md +++ b/README.md @@ -132,22 +132,22 @@ developers monitor both channels. ### News and Updates šŸ“£ - **Feb 2024**: Version 0.14 is released, which deprecates ["jj checkout" and "jj merge"](CHANGELOG.md#0140---2024-02-07), - as well as `jj init --git`, which is now just called `jj git init`. + as well as `jj init --git`, which is now just called `jj git init`. - **Oct 2023**: Version 0.10.0 is released! Now includes a bundled merge and diff editor for all platforms, "immutable revsets" to avoid accidentally `edit`-ing the wrong revisions, and lots of polish. - **Jan 2023**: Martin gave a presentation about Google's plans for Jujutsu at - Git Merge 2022! + Git Merge 2022! See the [slides][merge-slides] or the [recording][merge-talk]. ### Related Media - **Mar 2024**: Chris Krycho started [a YouTube series about Jujutsu][krycho-yt]. - **Feb 2024**: Chris Krycho published an article about Jujutsu called [jj init][krycho] - and Steve Klabnik followed up with the [Jujutsu Tutorial][klabnik]. -- **Jan 2024**: Jujutsu was featured in an LWN.net article called + and Steve Klabnik followed up with the [Jujutsu Tutorial][klabnik]. +- **Jan 2024**: Jujutsu was featured in an LWN.net article called [Jujutsu: a new, Git-compatible version control system][lwn]. -- **Jan 2023**: Martin's Talk about Jujutsu at Git Merge 2022, [video][merge-talk] +- **Jan 2023**: Martin's Talk about Jujutsu at Git Merge 2022, [video][merge-talk] and the associated [slides][merge-slides]. The wiki also contains a more extensive list of [media references][wiki-media]. @@ -155,9 +155,9 @@ The wiki also contains a more extensive list of [media references][wiki-media]. [krycho-yt]: https://www.youtube.com/playlist?list=PLelyiwKWHHAq01Pvmpf6x7J0y-yQpmtxp [krycho]: https://v5.chriskrycho.com/essays/jj-init/ [klabnik]: https://steveklabnik.github.io/jujutsu-tutorial/ -[lwn]: https://lwn.net/Articles/958468/ +[lwn]: https://lwn.net/Articles/958468/ [merge-talk]: https://www.youtube.com/watch?v=bx_LGilOuE4 -[merge-slides]: https://docs.google.com/presentation/d/1F8j9_UOOSGUN9MvHxPZX_L4bQ9NMcYOp1isn17kTC_M/view +[merge-slides]: https://docs.google.com/presentation/d/1F8j9_UOOSGUN9MvHxPZX_L4bQ9NMcYOp1isn17kTC_M/view [wiki-media]: https://github.com/martinvonz/jj/wiki/Media ## Getting started @@ -209,7 +209,7 @@ The Git backend is fully featured and maintained, and allows you to use Jujutsu with any Git remote. The commits you create will look like regular Git commits. You can fetch branches from a regular Git remote and push branches to the remote. You can always switch back to Git. - + Here is how you can explore a GitHub repository with `jj`. diff --git a/cli/src/config/README.md b/cli/src/config/README.md index d51750e0a3..f9d1bd20f5 100644 --- a/cli/src/config/README.md +++ b/cli/src/config/README.md @@ -1,2 +1,2 @@ These files are compiled into the binary; they are not installed to the user's -system. \ No newline at end of file +system. diff --git a/docs/FAQ.md b/docs/FAQ.md index f8d0dc8cb2..4d290a3e5f 100644 --- a/docs/FAQ.md +++ b/docs/FAQ.md @@ -66,18 +66,18 @@ important ones are: - Jujutsu commands may be a little slower in very large repositories due to importing and exporting changes to Git. Most repositories are not noticeably - affected by this. + affected by this. If you primarily use Jujutsu to modify the repository, the drawbacks are unlikely to affect you. Try co-locating while you learn Jujutsu, then switch if you find a specific reason not to co-locate. -### `jj` is said to record the working copy after `jj log` and every other command. Where can I see these automatic "saves"? +### `jj` is said to record the working copy after `jj log` and every other command. Where can I see these automatic "saves"? -Indeed, every `jj` command updates the current "working-copy" revision, marked +Indeed, every `jj` command updates the current "working-copy" revision, marked with `@` in `jj log`. You can notice this by how the [commit ID] of the working copy revision changes when it's updated. Note that, unless you move to -another revision (with `jj new` or `jj edit`, for example), the [change ID] will +another revision (with `jj new` or `jj edit`, for example), the [change ID] will not change. If you expected to see a historical view of your working copy changes in the @@ -151,9 +151,9 @@ ignore everything in the directory including the `.gitignore` file itself. If `$EDITOR` integration is important, something like `scratchpad.*` may be more helpful, as you can keep the filename extension intact (it -matches `scratchpad.md`, `scratchpad.rs` and more). Another option is to add a +matches `scratchpad.md`, `scratchpad.rs` and more). Another option is to add a directory to the global `.gitignore` which then stores all your temporary files -and notes. For example, you could add `scratch/` to `~/.git/ignore` and then +and notes. For example, you could add `scratch/` to `~/.git/ignore` and then store arbitrary files in `/scratch/`. You can find more details on `gitignore` files [here][gitignore]. @@ -163,7 +163,7 @@ You can find more details on `gitignore` files [here][gitignore]. Suppose your repository tracks a file like `secret_config.json`, and you make some changes to that file to work locally. Since Jujutsu automatically commits the working copy, there's no way to prevent Jujutsu from committing changes to -the file. But, you never want to push those changes to the remote repository. +the file. But, you never want to push those changes to the remote repository. One solution is to keep these changes in a separate commit branched from the trunk. To use those changes in your working copy, _merge_ the private commit @@ -251,7 +251,7 @@ commit to the new state. ### How do I resume working on an existing change? There are two ways to resume working on an earlier change: `jj new` then `jj squash`, -and `jj edit`. The first is generally recommended, but `jj edit` can be useful. When +and `jj edit`. The first is generally recommended, but `jj edit` can be useful. When you use `jj edit`, the revision is directly amended with your new changes, making it difficult to tell what exactly you change. You should avoid using `jj edit` when the revision has a conflict, as you may accidentally break the plain-text annotations on @@ -259,7 +259,7 @@ your state without realising. To start, use `jj new ` to create a change based on that earlier revision. Make your edits, then use `jj squash` to update the earlier revision with those edits. -For when you would use git stashing, use `jj edit ` for expected behaviour. +For when you would use git stashing, use `jj edit ` for expected behaviour. Other workflows may prefer `jj edit` as well. ### How do I deal with divergent changes ('??' after the [change ID])? diff --git a/docs/cli-reference.md b/docs/cli-reference.md index 2db6105323..5a1b0a1d74 100644 --- a/docs/cli-reference.md +++ b/docs/cli-reference.md @@ -18,4 +18,3 @@ rewrite-relative-urls=false start="" %} - diff --git a/docs/community_tools.md b/docs/community_tools.md index 262aa23706..686a36c702 100644 --- a/docs/community_tools.md +++ b/docs/community_tools.md @@ -4,16 +4,16 @@ But they already simplify many workflows and can improve your experience. -## Diffedit3 +## Diffedit3 -Diffedit3 is a web-based alternate to Meld, as it no longer is packaged and +Diffedit3 is a web-based alternate to Meld, as it no longer is packaged and available for all Distros. Its creator is also a frequent contributor. Find it [here][diffedit3] ## GG - GUI for JJ -GG is a cross platform GUI for Jujutsu which makes all graph manipulating +GG is a cross platform GUI for Jujutsu which makes all graph manipulating workflows quite easy. Take a look at its README.md as it quite descriptive. Find it [here][gg]. @@ -33,7 +33,7 @@ Find it [here][lazyjj]. ## JJ TUI -This is TUI for Jujutsu built in Ocaml, it is unopiniated and its creator is +This is TUI for Jujutsu built in Ocaml, it is unopiniated and its creator is open to feedback. Find it [here][jj_tui]. @@ -41,22 +41,22 @@ Find it [here][jj_tui]. ## Visual Jujutsu -VJJ is a fzf (fuzzy finder) wrapper for Jujutsu, which is meant to be used -interactively in the terminal. +VJJ is a fzf (fuzzy finder) wrapper for Jujutsu, which is meant to be used +interactively in the terminal. Find it [here][vjj]. -## Finding other integrations +## Finding other integrations -You can find other community contributed tools and integrations in our +You can find other community contributed tools and integrations in our [Wiki]. [cultivate]: https://github.com/benbrittain/cultivate [diffedit3]: https://github.com/ilyagr/diffedit3 -[gg]: https://github.com/gulbanana/gg +[gg]: https://github.com/gulbanana/gg [hunk.nvim]: https://github.com/julienvincent/hunk.nvim [jj_tui]: https://github.com/faldor20/jj_tui [lazyjj]: https://github.com/Cretezy/lazyjj [vjj]: https://github.com/noahmayr/vjj -[Wiki]: https://github.com/martinvonz/jj/wiki +[Wiki]: https://github.com/martinvonz/jj/wiki diff --git a/docs/config.md b/docs/config.md index 8bb4b71c5d..1c1ae2aef6 100644 --- a/docs/config.md +++ b/docs/config.md @@ -771,7 +771,7 @@ patterns = ["numbers.txt"] ## Commit Signing -`jj` can be configured to sign and verify the commits it creates using either +`jj` can be configured to sign and verify the commits it creates using either GnuPG or SSH signing keys. To do this you need to configure a signing backend. @@ -824,8 +824,8 @@ signing.backends.ssh.program = "/path/to/ssh-keygen" When verifying commit signatures the ssh backend needs to be provided with an allowed-signers file containing the public keys of authors whose signatures you want to be able to verify. -You can find the format for this file in the -[ssh-keygen man page](https://man.openbsd.org/ssh-keygen#ALLOWED_SIGNERS). This can be provided +You can find the format for this file in the +[ssh-keygen man page](https://man.openbsd.org/ssh-keygen#ALLOWED_SIGNERS). This can be provided as follows: ```toml diff --git a/docs/contributing.md b/docs/contributing.md index cc6b5e00dd..d885720283 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -36,22 +36,22 @@ commit and the new feature in a different commit. If the refactoring itself consists of many parts, try to separate out those into separate commits. You can use `jj split` to do it if you didn't realize ahead of time how it should be split up. Include tests and documentation in the same commit as the code they -test and document. +test and document. The commit message should describe the changes in the commit; the PR description can even be empty, but feel free to include a personal -message. We write commit messages in an affected component style and don't use -[conventional commits](www.conventionalcommits.org/en/v1.0.0/). This means if -you modified a command in the CLI, use its name as the topic, e.g +message. We write commit messages in an affected component style and don't use +[conventional commits](www.conventionalcommits.org/en/v1.0.0/). This means if +you modified a command in the CLI, use its name as the topic, e.g `next/prev: ` or `conflicts: `. We don't -currently have a specific guidelines on what to write in the topic field, but -the reviewers will help you provide a topic if you have difficulties choosing +currently have a specific guidelines on what to write in the topic field, but +the reviewers will help you provide a topic if you have difficulties choosing it. When you address comments on a PR, don't make the changes in a commit on top (as is typical on GitHub). Instead, please make the changes in the appropriate -commit. You can do that by creating a new commit on top of the initial commit - (`jj new `) and then squash in the changes when you're done (`jj squash`). +commit. You can do that by creating a new commit on top of the initial commit + (`jj new `) and then squash in the changes when you're done (`jj squash`). `jj git push` will automatically force-push the bookmark. @@ -74,9 +74,9 @@ Guidelines](https://opensource.google/conduct/). ## Contributing large patches -Before sending a PR for a large change which designs/redesigns or reworks an -existing component, we require an architecture review from multiple -stakeholders, which we do with [Design Docs](design_docs.md), see the +Before sending a PR for a large change which designs/redesigns or reworks an +existing component, we require an architecture review from multiple +stakeholders, which we do with [Design Docs](design_docs.md), see the [process here](design_docs.md#process). ## Contributing to the documentation @@ -233,7 +233,7 @@ necessary. Any version of `pipx` will do. If you are installing `pipx` manually, you may first need to follow the [Python installation instructions]. [Python installation instructions]: https://docs.python.org/3/using/index.html -[Poetry installation instructions]: https://python-poetry.org/docs/#installation +[Poetry installation instructions]: https://python-poetry.org/docs/#installation Once you have `poetry` installed, you should ask it to install the rest of the required tools into a virtual environment as follows: diff --git a/docs/design/copy-tracking.md b/docs/design/copy-tracking.md index 24e0d27e79..e2949c037f 100644 --- a/docs/design/copy-tracking.md +++ b/docs/design/copy-tracking.md @@ -75,12 +75,12 @@ pub type CopyRecordStream = BoxStream>; pub trait Backend { /// Get all copy records for `paths` in the dag range `roots..heads`. - /// + /// /// The exact order these are returned is unspecified, but it is guaranteed /// to be reverse-topological. That is, for any two copy records with /// different commit ids A and B, if A is an ancestor of B, A is streamed /// after B. - /// + /// /// Streaming by design to better support large backends which may have very /// large single-file histories. This also allows more iterative algorithms /// like blame/annotate to short-circuit after a point without wasting diff --git a/docs/design/run.md b/docs/design/run.md index b313ad25ba..5bb6606b27 100644 --- a/docs/design/run.md +++ b/docs/design/run.md @@ -5,25 +5,25 @@ Authors: [Philip Metzger](mailto:philipmetzger@bluewin.ch), [Martin von Zweigber Initial Version, 10.12.2022 (view full history [here](https://docs.google.com/document/d/14BiAoEEy_e-BRPHYpXRFjvHMfgYVKh-pKWzzTDi-v-g/edit)) -**Summary:** This Document documents the design of a new `run` command for +**Summary:** This Document documents the design of a new `run` command for Jujutsu which will be used to seamlessly integrate with build systems, linters -and formatters. This is achieved by running a user-provided command or script -across multiple revisions. For more details, read the +and formatters. This is achieved by running a user-provided command or script +across multiple revisions. For more details, read the [Use-Cases of jj run](#use-cases-of-jj-run). ## Preface The goal of this Design Document is to specify the correct behavior of `jj run`. -The points we decide on here I (Philip Metzger) will try to implement. There +The points we decide on here I (Philip Metzger) will try to implement. There exists some prior work in other DVCS: -* `git test`: part of [git-branchless]. Similar to this proposal for `jj run`. +* `git test`: part of [git-branchless]. Similar to this proposal for `jj run`. * `hg run`: Google's internal Mercurial extension. Similar to this proposal for `jj run`. -Details not available. +Details not available. * `hg fix`: Google's open source Mercurial extension: [source code][fix-src]. A more specialized approach to rewriting file content without full context of the -working directory. -* `git rebase -x`: runs commands opportunistically as part of rebase. +working directory. +* `git rebase -x`: runs commands opportunistically as part of rebase. * `git bisect run`: run a command to determine which commit introduced a bug. ## Context and Scope @@ -32,15 +32,15 @@ The initial need for some kind of command runner integrated in the VCS, surfaced in a [github discussion][pre-commit]. In a [discussion on discord][hooks] about the git-hook model, there was consensus about not repeating their mistakes. -For `jj run` there is prior art in Mercurial, git branchless and Google's +For `jj run` there is prior art in Mercurial, git branchless and Google's internal Mercurial. Currently git-branchless `git test` and `hg fix` implement -some kind of command runner. The Google internal `hg run` works in +some kind of command runner. The Google internal `hg run` works in conjunction with CitC (Clients in the Cloud) which allows it to lazily apply the current command to any affected file. Currently no Jujutsu backend -(Git, Native) has a fancy virtual filesystem supporting it, so we -can't apply this optimization. We could do the same once we have an -implementation of the working copy based on a virtual file system. Until then, -we have to run the commands in regular local-disk working copies. +(Git, Native) has a fancy virtual filesystem supporting it, so we +can't apply this optimization. We could do the same once we have an +implementation of the working copy based on a virtual file system. Until then, +we have to run the commands in regular local-disk working copies. ## Goals and Non-Goals @@ -50,22 +50,22 @@ we have to run the commands in regular local-disk working copies. * We should be able to parallelize running the actual command, while preserving a good console output. * The run command should be able to work in any commit, the working-copy commit -itself or any other commit. -* There should exist some way to signal hard failure. -* The command should build enough infrastructure for `jj test`, `jj fix` and +itself or any other commit. +* There should exist some way to signal hard failure. +* The command should build enough infrastructure for `jj test`, `jj fix` and `jj format`. -* The main goal is to be good enough, as we can always expand the functionality +* The main goal is to be good enough, as we can always expand the functionality in the future. ### Non-Goals -* While we should build a base for `jj test`, `jj format` and `jj fix`, we +* While we should build a base for `jj test`, `jj format` and `jj fix`, we shouldn't mash their use-cases into `jj run`. -* The command shouldn't be too smart, as too many assumptions about workflows -makes the command confusing for users. +* The command shouldn't be too smart, as too many assumptions about workflows +makes the command confusing for users. * The smart caching of outputs, as user input commands can be unpredictable. -makes the command confusing for users. -* Avoid the smart caching of outputs, as user input commands can be +makes the command confusing for users. +* Avoid the smart caching of outputs, as user input commands can be unpredictable. * Fine grained user facing configuration, as it's unwarranted complexity. * A `fix` subcommand as it cuts too much design space. @@ -88,89 +88,89 @@ unpredictable. - `jj run 'bazel build //some/target:somewhere'` - `jj run 'ninja check-lld'` -Some of these use-cases should get a specialized command, as this allows -further optimization. A command could be `jj format`, which runs a list of -formatters over a subset of a file in a revision. Another command could be +Some of these use-cases should get a specialized command, as this allows +further optimization. A command could be `jj format`, which runs a list of +formatters over a subset of a file in a revision. Another command could be `jj fix`, which runs a command like `rustfmt --fix` or `cargo clippy --fix` over a subset of a file in a revision. ## Design -### Base Design +### Base Design -All the work will be done in the `.jj/` directory. This allows us to hide all +All the work will be done in the `.jj/` directory. This allows us to hide all complexity from the users, while preserving the user's current workspace. -We will copy the approach from git-branchless's `git test` of creating a -temporary working copy for each parallel command. The working copies will be -reused between `jj run` invocations. They will also be reused within `jj run` +We will copy the approach from git-branchless's `git test` of creating a +temporary working copy for each parallel command. The working copies will be +reused between `jj run` invocations. They will also be reused within `jj run` invocation if there are more commits to run on than there are parallel jobs. -We will leave ignored files in the temporary directory between runs. That +We will leave ignored files in the temporary directory between runs. That enables incremental builds (e.g by letting cargo reuse its `target/` directory). -However, it also means that runs potentially become less reproducible. We will +However, it also means that runs potentially become less reproducible. We will provide a flag for removing ignored files from the temporary working copies to -address that. +address that. Another problem with leaving ignored files in the temporary directories is that -they take up space. That is especially problematic in the case of cargo (the +they take up space. That is especially problematic in the case of cargo (the `target/` directory often takes up tens of GBs). The same flag for cleaning up -ignored files can be used to address that. We may want to also have a flag for -cleaning up temporary working copies *after* running the command. +ignored files can be used to address that. We may want to also have a flag for +cleaning up temporary working copies *after* running the command. -An early version of the command will directly use [Treestate] to -to manage the temporary working copies. That means that running `jj` inside the +An early version of the command will directly use [Treestate] to +to manage the temporary working copies. That means that running `jj` inside the temporary working copies will not work . We can later extend that to use a full -[Workspace]. To prevent operations in the working copies from +[Workspace]. To prevent operations in the working copies from impacting the repo, we can use a separate [OpHeadsStore] for it. ### Modifying the Working Copy -Since the subprocesses will run in temporary working copies, they +Since the subprocesses will run in temporary working copies, they won't interfere with the user's working copy. The user can therefore continue -to work in it while `jj run` is running. +to work in it while `jj run` is running. We want subprocesses to be able to make changes to the repo by updating their -assigned working copy. Let's say the user runs `jj run` on just commits A and -B, where B's parent is A. Any changes made on top of A would be squashed into +assigned working copy. Let's say the user runs `jj run` on just commits A and +B, where B's parent is A. Any changes made on top of A would be squashed into A, forming A'. Similarly B' would be formed by squasing it into B. We can then either do a normal rebase of B' onto A', or we can simply update its parent to A'. The former is useful, e.g when the subprocess only makes a partial update -of the tree based on the parent commit. In addition to these two modes, we may -want to have an option to ignore any changes made in the subprocess's working +of the tree based on the parent commit. In addition to these two modes, we may +want to have an option to ignore any changes made in the subprocess's working copy. ### Modifying the Repo -Once we give the subprocess access to a fork of the repo via separate +Once we give the subprocess access to a fork of the repo via separate [OpHeadsStore], it will be able to create new operations in its fork. If the user runs `jj run -r foo` and the subprocess checks out another commit, -it's not clear what that should do. We should probably just verify that the +it's not clear what that should do. We should probably just verify that the working-copy commit's parents are unchanged after the subprocess returns. Any -operations created by the subprocess will be ignored. +operations created by the subprocess will be ignored. -### Rewriting the revisions +### Rewriting the revisions Like all commands, `jj run` will refuse to rewrite public/immutable commits. -For private/unpublished revisions, we either amend or reparent the changes, +For private/unpublished revisions, we either amend or reparent the changes, which are available as command options. ## Execution order/parallelism -It may be useful to execute commands in topological order. For example, -commands with costs proportional to incremental changes, like build systems. +It may be useful to execute commands in topological order. For example, +commands with costs proportional to incremental changes, like build systems. There may also be other relevant heuristics, but topological order is an easy -and effective way to start. +and effective way to start. -Parallel execution of commands on different commits may choose to schedule +Parallel execution of commands on different commits may choose to schedule commits to still reduce incremental changes in the working copy used by each -execution slot/"thread". However, running the command on all commits -concurrently should be possible if desired. +execution slot/"thread". However, running the command on all commits +concurrently should be possible if desired. -Executing commands in topological order allows for more meaningful use of any -potential features that stop execution "at the first failure". For example, -when running tests on a chain of commits, it might be useful to proceed in -topological/chronological order, and stop on the first failure, because it +Executing commands in topological order allows for more meaningful use of any +potential features that stop execution "at the first failure". For example, +when running tests on a chain of commits, it might be useful to proceed in +topological/chronological order, and stop on the first failure, because it might imply that the remaining executions will be undesirable because they will also fail. @@ -178,54 +178,54 @@ also fail. It will be useful to have multiple strategies to deal with failures on a single or multiple revisions. The reason for these strategies is to allow customized -conflict handling. These strategies then can be exposed in the ui with a +conflict handling. These strategies then can be exposed in the ui with a matching option. -**Continue:** If any subprocess fails, we will continue the work on child -revisions. Notify the user on exit about the failed revisions. +**Continue:** If any subprocess fails, we will continue the work on child +revisions. Notify the user on exit about the failed revisions. **Stop:** Signal a fatal failure and cancel any scheduled work that has not yet started running, but let any already started subprocess finish. Notify the -user about the failed command and display the generated error from the -subprocess. +user about the failed command and display the generated error from the +subprocess. -**Fatal:** Signal a fatal failure and immediately stop processing and kill any -running processes. Notify the user that we failed to apply the command to the -specific revision. +**Fatal:** Signal a fatal failure and immediately stop processing and kill any +running processes. Notify the user that we failed to apply the command to the +specific revision. We will leave any affected commit in its current state, if any subprocess fails. -This allows us to provide a better user experience, as leaving revisions in an +This allows us to provide a better user experience, as leaving revisions in an undesirable state, e.g partially formatted, may confuse users. ## Resource constraints -It will be useful to constrain the execution to prevent resource exhaustion. +It will be useful to constrain the execution to prevent resource exhaustion. Relevant resources could include: - CPU and memory available on the machine running the commands. `jj run` can -provide some simple mitigations like limiting parallelism to "number of CPUs" -by default, and limiting parallelism by dividing "available memory" by some +provide some simple mitigations like limiting parallelism to "number of CPUs" +by default, and limiting parallelism by dividing "available memory" by some estimate or measurement of per-invocation memory use of the commands. -- External resources that are not immediately known to jj. For example, +- External resources that are not immediately known to jj. For example, commands run in parallel may wish to limit the total number of connections -to a server. We might choose to defer any handling of this to the -implementation of the command being invoked, instead of trying to +to a server. We might choose to defer any handling of this to the +implementation of the command being invoked, instead of trying to communicate that information to jj. ## Command Options -The base command of any jj command should be usable. By default `jj run` works +The base command of any jj command should be usable. By default `jj run` works on the `@` the current working copy. * --command, explicit name of the first argument * -x, for git compatibility (may alias another command) * -j, --jobs, the amount of parallelism to use * -k, --keep-going, continue on failure (may alias another command) * --show, display the diff for an affected revision -* --dry-run, do the command execution without doing any work, logging all +* --dry-run, do the command execution without doing any work, logging all intended files and arguments -* --rebase, rebase all parents on the consulitng diff (may alias another +* --rebase, rebase all parents on the consulitng diff (may alias another command) -* --reparent, change the parent of an effected revision to the new change +* --reparent, change the parent of an effected revision to the new change (may alias another command) * --clean, remove existing workspaces and remove the ignored files * --readonly, ignore changes across multiple run invocations @@ -236,34 +236,34 @@ command) `jj log`: No special handling needed `jj diff`: No special handling needed `jj st`: For now reprint the final output of `jj run` -`jj op log`: No special handling needed, but awaits further discussion in +`jj op log`: No special handling needed, but awaits further discussion in [#963][issue] `jj undo/jj op undo`: No special handling needed ## Open Points -Should the command be working copy backend specific? -How do we manage the Processes which the command will spawn? +Should the command be working copy backend specific? +How do we manage the Processes which the command will spawn? Configuration options, User and Repository Wide? ## Future possibilities -- We could rewrite the file in memory, which is a neat optimization -- Exposing some internal state, to allow preciser resource constraints -- Integration options for virtual filesystems, which allow them to cache the -needed working copies. +- We could rewrite the file in memory, which is a neat optimization +- Exposing some internal state, to allow preciser resource constraints +- Integration options for virtual filesystems, which allow them to cache the +needed working copies. - A Jujutsu wide concept for a cached working copy, as they could be expensive -to materialize. -- Customized failure messages, this maybe useful for bots, it could be similar +to materialize. +- Customized failure messages, this maybe useful for bots, it could be similar to Bazel's `select(..., message = "arch not supported for $project")`. - Make `jj run` asynchronous by spawning a `main` process, directly return to the -user and incrementally updating the output of `jj st`. +user and incrementally updating the output of `jj st`. [git-branchless]: https://github.com/arxanas/git-branchless -[issue]: https://github.com/martinvonz/jj/issues/963 +[issue]: https://github.com/martinvonz/jj/issues/963 [fix-src]: https://repo.mercurial-scm.org/hg/file/tip/hgext/fix.py [hooks]: https://discord.com/channels/968932220549103686/969829516539228222/1047958933161119795 [OpHeadsStore]: https://github.com/martinvonz/jj/blob/main/lib/src/op_heads_store.rs diff --git a/docs/design_doc_blueprint.md b/docs/design_doc_blueprint.md index 70f5563673..ba55a2a398 100644 --- a/docs/design_doc_blueprint.md +++ b/docs/design_doc_blueprint.md @@ -8,17 +8,17 @@ Author: [Your-Name](mailto:your-name@reachable.com) ## Summary -A short summary of your project/re-design/component and what problems it +A short summary of your project/re-design/component and what problems it addresses in about 3-10 sentences. ## State of the Feature as of `$VERSION` (optional) -The state of the feature you want to improve and where it currently falls +The state of the feature you want to improve and where it currently falls short. If there's nothing to compare to, leave it out. ## Prior work (optional) -Does this feature exist somewhere else and which tradeoffs it made. +Does this feature exist somewhere else and which tradeoffs it made. > If there's no prior work, then use the related work section below. @@ -33,7 +33,7 @@ A detailed overview of the project and the improvements it brings. ### Detailed Design The place to describe all new interfaces and interactions and how it plays into -the existing code and behavior. This is the place for all nitty-gritty details +the existing code and behavior. This is the place for all nitty-gritty details which interact with the system. ## Alternatives considered (optional) @@ -46,8 +46,8 @@ A list of issues which are addressed by this design. ## Related Work (optional) -If there's a feature in another VCS which shares some similarities to your -proposed work, it belongs here. An example would be Jujutsu sparse workspaces +If there's a feature in another VCS which shares some similarities to your +proposed work, it belongs here. An example would be Jujutsu sparse workspaces and Perforce client workspaces. ## Future Possibilities diff --git a/docs/design_docs.md b/docs/design_docs.md index e40f323eea..ba5a425e45 100644 --- a/docs/design_docs.md +++ b/docs/design_docs.md @@ -1,28 +1,27 @@ # Jujutsu Design Docs Jujutsu uses Design Docs to drive technical decisions on large projects and it -is the place to discuss your proposed design or new component. It is a very +is the place to discuss your proposed design or new component. It is a very thorough process, in which the design doc must be approved before PRs for the -feature will be accepted. It shares some similarities with [Rust RFCs] but -mostly addresses _technical_ problems and gauges the technical and social +feature will be accepted. It shares some similarities with [Rust RFCs] but +mostly addresses _technical_ problems and gauges the technical and social concerns of all stakeholders. So if you want to start building the native backend or the server component for -Jujutsu, you'll need to go through this process. +Jujutsu, you'll need to go through this process. ## Process -1. Add a new markdown document to `docs/design`, named after your improvement - or project. +1. Add a new markdown document to `docs/design`, named after your improvement + or project. 1. Describe the current state of the world and the things you want to improve. -1. Wait for the Maintainers and Stakeholders to show up. +1. Wait for the Maintainers and Stakeholders to show up. 1. Iterate until everyone accepts the change in normal codereview fashion. - -[Rust RFCs]: https://github.com/rust-lang/rfcs + +[Rust RFCs]: https://github.com/rust-lang/rfcs ## Blueprint (Template) -You can find the base template of a new Design Doc +You can find the base template of a new Design Doc [here](design_doc_blueprint.md). - diff --git a/docs/git-compatibility.md b/docs/git-compatibility.md index 60954b801c..9afa34a430 100644 --- a/docs/git-compatibility.md +++ b/docs/git-compatibility.md @@ -31,7 +31,7 @@ a comparison with Git, including how workflows are different, see the * **.gitignore: Yes.** Ignores in `.gitignore` files are supported. So are ignores in `.git/info/exclude` or configured via Git's `core.excludesfile` config. The `.gitignore` support uses a native implementation, so please - report a bug if you notice any difference compared to `git`. + report a bug if you notice any difference compared to `git`. * **.gitattributes: No.** There's [#53](https://github.com/martinvonz/jj/issues/53) about adding support for at least the `eol` attribute. * **Hooks: No.** There's [#405](https://github.com/martinvonz/jj/issues/405) @@ -45,7 +45,7 @@ a comparison with Git, including how workflows are different, see the * **Staging area: Kind of.** The staging area will be ignored. For example, `jj diff` will show a diff from the Git HEAD to the working copy. There are [ways of fulfilling your use cases without a staging - area](https://github.com/martinvonz/jj/blob/main/docs/git-comparison.md#the-index). + area](https://github.com/martinvonz/jj/blob/main/docs/git-comparison.md#the-index). * **Garbage collection: Yes.** It should be safe to run `git gc` in the Git repo, but it's not tested, so it's probably a good idea to make a backup of the whole workspace first. There's [no garbage collection and repacking of diff --git a/docs/glossary.md b/docs/glossary.md index 3f201b107e..5b868e8290 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -25,7 +25,7 @@ such as the "operation store backend" for storing A bookmark is a named pointer to a [commit](#commit). They automatically follow the commit if it gets [rewritten](#rewrite). Bookmarks are sometimes called "named branches" to distinguish them from [anonymous branches](#anonymous-branch). -They are similar to Git's branches and even more similar to +They are similar to Git's branches and even more similar to [Mercurial's bookmarks](https://wiki.mercurial-scm.org/Bookmarks). See [here](bookmarks.md) for details. diff --git a/docs/revsets.md b/docs/revsets.md index 136f796bd0..ada396429e 100644 --- a/docs/revsets.md +++ b/docs/revsets.md @@ -405,7 +405,7 @@ For example: ### Built-in Aliases The following aliases are built-in and used for certain operations. These functions -are defined as aliases in order to allow you to overwrite them as needed. +are defined as aliases in order to allow you to overwrite them as needed. See [revsets.toml](https://github.com/martinvonz/jj/blob/main/cli/src/config/revsets.toml) for a comprehensive list. @@ -439,7 +439,7 @@ for a comprehensive list. * `immutable()`: The set of commits that `jj` treats as immutable. This is equivalent to `::(immutable_heads() | root())`. It is not recommended to redefine this alias. Note that modifying this will *not* change whether a commit is immutable. - To do that, edit `immutable_heads()`. + To do that, edit `immutable_heads()`. * `mutable()`: The set of commits that `jj` treats as mutable. This is equivalent to `~immutable()`. It is not recommended to redefined this alias. diff --git a/docs/templates.md b/docs/templates.md index 23edbeb303..68f553e895 100644 --- a/docs/templates.md +++ b/docs/templates.md @@ -80,8 +80,8 @@ This type cannot be printed. The following methods are defined. working-copy commit as `@`. * `current_working_copy() -> Boolean`: True for the working-copy commit of the current workspace. -* `bookmarks() -> List`: Local and remote bookmarks pointing to the - commit. A tracking remote bookmark will be included only if its target is +* `bookmarks() -> List`: Local and remote bookmarks pointing to the + commit. A tracking remote bookmark will be included only if its target is different from the local one. * `local_bookmarks() -> List`: All local bookmarks pointing to the commit. * `remote_bookmarks() -> List`: All remote bookmarks pointing to the commit. diff --git a/docs/testimonials.md b/docs/testimonials.md index 5ab6860086..449a34c753 100644 --- a/docs/testimonials.md +++ b/docs/testimonials.md @@ -6,7 +6,7 @@ practice. In order to provide some motivation, we've collected a number of real, 100% authentic testimonials — from our loving users, our silly developers — all to tip the scales and get you on our side! -## What the users have to say +## What the users have to say > I've spent many years of my career working on version control. What I like > most about Jujutsu is how it has non-obvious solutions to UX problems that @@ -37,18 +37,18 @@ practice. In order to provide some motivation, we've collected a number of real, > It's so rare that a solution attacks the innermost core of a problem so > thoroughly, I genuinely feel blessed to be in its presence. And also a bit > vindicated in not even trying to learn to use any of the tools that felt like -> more crutches stacked upon a sand castle +> more crutches stacked upon a sand castle — Anonymous user, speaking from the shadows -> It's the easiest time I've ever had learning a tool this deeply this quickly, -> because of the ability to experiment and undo, instead of triple-checking +> It's the easiest time I've ever had learning a tool this deeply this quickly, +> because of the ability to experiment and undo, instead of triple-checking > before trying a new scary command. — Scott Olson, advanced Git user and now a Jujutsu user -> I initially started to use Jujutsu for personal repos, and it has quickly -> gone from "neat, let's try this more" to "very neat, added to my permanent +> I initially started to use Jujutsu for personal repos, and it has quickly +> gone from "neat, let's try this more" to "very neat, added to my permanent > config and automatically installed for new machines". — Poliorcetics, on GitHub @@ -59,7 +59,7 @@ practice. In order to provide some motivation, we've collected a number of real, — jyn514, Rust contributor -> Jujutsu is pretty cool, you can even keep most of your existing workflows +> Jujutsu is pretty cool, you can even keep most of your existing workflows — Ben, who doesn't want you keeping your existing workflow @@ -69,9 +69,9 @@ practice. In order to provide some motivation, we've collected a number of real, Jujutsu exists) > When I heard about Jujutsu I decided to try it out before forming an opinion. -> Technically it never formed, because I haven't considered going back. +> Technically it never formed, because I haven't considered going back. -— gul banana, computer programmer +— gul banana, computer programmer ## What the developers have to say @@ -94,7 +94,7 @@ Jujutsu exists) — Anton Bulakh, contributor and dopamine enthusiast -> I'm sometimes still surprised that navigating with `jj next` and `jj prev` +> I'm sometimes still surprised that navigating with `jj next` and `jj prev` > works. — Philip Metzger, author of `jj next` and `jj prev` diff --git a/docs/tutorial.md b/docs/tutorial.md index 46089f3f15..76f8fc2a77 100644 --- a/docs/tutorial.md +++ b/docs/tutorial.md @@ -2,7 +2,7 @@ > **Hint:** This tutorial has become somewhat out of date. Many people find > the alternative (not quite finished) [tutorial by Steve -> Klabnik](https://steveklabnik.github.io/jujutsu-tutorial/) helpful. +> Klabnik](https://steveklabnik.github.io/jujutsu-tutorial/) helpful. This text assumes that the reader is familiar with Git. diff --git a/docs/windows.md b/docs/windows.md index b13b65e94b..6ac795d677 100644 --- a/docs/windows.md +++ b/docs/windows.md @@ -88,10 +88,10 @@ Then only use the `~/my-repo` workspace from Linux. ## Symbolic link support -`jj` supports symlinks on Windows only when they are enabled by the operating +`jj` supports symlinks on Windows only when they are enabled by the operating system. This requires Windows 10 version 14972 or higher, as well as Developer Mode. If those conditions are not satisfied, `jj` will materialize symlinks as ordinary files. For colocated repositories, Git support must also be enabled using the -`git config` option `core.symlinks=true`. \ No newline at end of file +`git config` option `core.symlinks=true`. diff --git a/docs/working-copy.md b/docs/working-copy.md index 96acd48e83..7190b47232 100644 --- a/docs/working-copy.md +++ b/docs/working-copy.md @@ -77,7 +77,7 @@ You can untrack such files with the jj file untrack command. ## Workspaces -You can have multiple working copies backed by a single repo. Use +You can have multiple working copies backed by a single repo. Use `jj workspace add` to create a new working copy. The working copy will have a `.jj/` directory linked to the main repo. The working copy and the `.jj/` directory together is called a "workspace". Each workspace can have a different