mirror of
https://github.com/martinvonz/jj.git
synced 2024-10-22 22:46:44 +00:00
docs: Remove trailing whitespace in markdown files
This commit is contained in:
Lukas Wirth
parent
bccd8214df
commit
1410f2bee7
20 changed files with 178 additions and 180 deletions
10
CHANGELOG.md
10
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
|
||||
|
|
|
|||
16
README.md
16
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`.
|
||||
|
||||
<img src="demos/git_compat.png" />
|
||||
|
|
|
|||
|
|
@ -1,2 +1,2 @@
|
|||
These files are compiled into the binary; they are not installed to the user's
|
||||
system.
|
||||
system.
|
||||
|
|
|
|||
18
docs/FAQ.md
18
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 `<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])?
|
||||
|
|
|
|||
|
|
@ -18,4 +18,3 @@
|
|||
rewrite-relative-urls=false
|
||||
start="<!-- BEGIN MARKDOWN-->"
|
||||
%}
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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:
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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).
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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`
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
|
|
|
|||
|
|
@ -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`.
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Reference in a new issue