ok/jj
1
0
Fork 0
forked from mirrors/jj

docs: Remove trailing whitespace in markdown files

This commit is contained in:
Lukas Wirth 2024-09-13 07:25:47 +02:00
parent bccd8214df
commit 1410f2bee7
20 changed files with 178 additions and 180 deletions

View file

@ -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 caseinsensitive matching by suffixing any

View file

@ -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`.
<img src="demos/git_compat.png" />

View file

@ -1,2 +1,2 @@
These files are compiled into the binary; they are not installed to the user's
system.
system.

View file

@ -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 `<your-git-repo>/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 <rev>` 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 <rev>` for expected behaviour.
For when you would use git stashing, use `jj edit <rev>` for expected behaviour.
Other workflows may prefer `jj edit` as well.
### How do I deal with divergent changes ('??' after the [change ID])?

View file

@ -18,4 +18,3 @@
rewrite-relative-urls=false
start="<!-- BEGIN MARKDOWN-->"
%}

View file

@ -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].
<!-- TODO: Add benbrittains/cultivate when its ready -->
## 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

View file

@ -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

View file

@ -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: <your-modification>` or `conflicts: <your-modification>`. 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 <commit>`) 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 <commit>`) 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:

View file

@ -75,12 +75,12 @@ pub type CopyRecordStream = BoxStream<BackendResult<CopyRecord>>;
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

View file

@ -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

View file

@ -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

View file

@ -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).

View file

@ -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

View file

@ -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.

View file

@ -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.

View file

@ -80,8 +80,8 @@ This type cannot be printed. The following methods are defined.
working-copy commit as `<workspace name>@`.
* `current_working_copy() -> Boolean`: True for the working-copy commit of the
current workspace.
* `bookmarks() -> List<RefName>`: Local and remote bookmarks pointing to the
commit. A tracking remote bookmark will be included only if its target is
* `bookmarks() -> List<RefName>`: 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<RefName>`: All local bookmarks pointing to the commit.
* `remote_bookmarks() -> List<RefName>`: All remote bookmarks pointing to the commit.

View file

@ -6,7 +6,7 @@ practice. In order to provide some motivation, we've collected a number of real,
100% authentic testimonials &mdash; from our loving users, our silly developers
&mdash; 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
&mdash; 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.
&mdash; 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".
&mdash; Poliorcetics, on GitHub
@ -59,7 +59,7 @@ practice. In order to provide some motivation, we've collected a number of real,
&mdash; 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
&mdash; 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.
&mdash; gul banana, computer programmer
&mdash; gul banana, computer programmer
## What the developers have to say
@ -94,7 +94,7 @@ Jujutsu exists)
&mdash; 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.
&mdash; Philip Metzger, author of `jj next` and `jj prev`

View file

@ -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.

View file

@ -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`.
`git config` option `core.symlinks=true`.

View file

@ -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