jj/docs
Remo Senekowitsch ec5c135387 git: colocate repos by default
Closes https://github.com/jj-vcs/jj/issues/7189

Colocated repos have some advantages and some disadvantages. On the
whole, I think making Git repos colocated by default is a better
trade-off, especially for new users. With the `git.colocate` setting,
(experienced) users can easily change this according to preference.

A non-exhaustive list of pros and cons of colocated repos:

pros:
* Many code editors show the changes one is currently working on based
  on Git's "dirty worktree".
* There are a lot of tools that integrate with Git which don't work at
  all in non-colocated repositories.
* There are a lot of Git features that Jujutsu doesn't have yet. When
  users ask for them, the answer is usually: "Just colocate your repo
  and run git directly for now." It's a strength that Jujutsu can focus
  on what makes it special and not have to rush the reimplementation of
  every niche feature of Git. Examples: `git rebase` tracking file
  renames, `git bisect`, `git tag`, `git range-diff`, submodules.

cons:
* Jujutsu performs worse in colocated repositories with lots of refs,
  because of the automatic `jj git import`.
* Colocated repos make branch@git references show up in Jujutsu output,
  which is usually just aesthetically displeasing or possibly even
  confusing to inexperienced users.
* Interleaving jj and (mutating) git commands can lead to confusing
  situations. Examples:
  * Creating a commit with git instead of jj will often leave a
    duplicate "work in progress" commit in Jujutsu's log.
  * Some IDEs periodically run `git fetch` in the background. This can
    lead to conflicted branches and divergent change IDs, something many
    people struggle with.
2025-09-04 11:26:28 +00:00
..
design op: undo: rename to revert 2025-08-15 21:31:15 +00:00
governance meta: add initial GOVERNANCE.md 2025-02-10 17:39:34 +00:00
guides docs: use commit ids in divergence example commands 2025-08-21 15:23:40 +00:00
images Replace the PNG logo with a vector SVG version. 2025-03-11 22:44:13 +00:00
technical conflicts: document the "same-change rule" 2025-05-14 15:08:29 +00:00
bookmarks.md bookmarks: First step to make target revision a required argument to bookmark create/move/set. 2025-02-11 22:21:19 +00:00
changelog.md website: Add the CHANGELOG 2025-07-17 22:59:58 +00:00
cli-reference.md mkdocs: update mkdocs-material and mkdocs-include-markdown-plugin 2025-02-13 17:30:21 +00:00
code-of-conduct.md code-of-conduct: replace @avamsi by @icorbrey as Community Leader 2025-07-11 17:14:07 +00:00
community_tools.md docs: Add a section for Selvejj 2025-08-22 14:31:08 +00:00
config-schema.json docs: Expose config-schema.json in the docs site 2025-01-14 13:45:36 +00:00
config.md git: colocate repos by default 2025-09-04 11:26:28 +00:00
config.toml docs: document git.fetch and git.push config options 2024-02-09 12:03:42 -06:00
conflicts.md docs: fix syntax highlighting for conflicts.md 2025-03-03 22:42:14 +00:00
contributing.md git: colocate repos by default 2025-09-04 11:26:28 +00:00
core_tenets.md docs/core_tenets: fix typo 2025-05-10 15:36:46 +00:00
design_doc_blueprint.md docs: Remove trailing whitespace in markdown files 2024-09-13 13:06:28 +02:00
design_docs.md doc: update some references to "the native backend" 2025-03-21 16:27:51 +00:00
FAQ.md docs: Recommend unhiding revisions in the accidental changes FAQ 2025-08-29 05:30:42 +00:00
filesets.md docs: remove trailing whitespace 2025-08-25 00:05:21 +00:00
git-command-table.md docs: convert Git command table from HTML to YAML 2025-04-21 00:45:01 +00:00
git-command-table.yml git: colocate repos by default 2025-09-04 11:26:28 +00:00
git-comparison.md docs: move Git command table to a separate page 2025-02-10 15:29:32 +00:00
git-compatibility.md git: colocate repos by default 2025-09-04 11:26:28 +00:00
github.md git: colocate repos by default 2025-09-04 11:26:28 +00:00
glossary.md docs: add definition for remotes to glossary 2025-08-15 21:51:48 +00:00
index.md website: Add the CHANGELOG 2025-07-17 22:59:58 +00:00
install-and-setup.md docs: improve description of different completion scripts 2025-09-03 17:35:05 +00:00
operation-log.md undo: revert progressively older operations with repeated calls 2025-08-24 06:56:40 +00:00
paid_contributors.md paid contributors: add myself as a newly minted ERSC employee 2025-09-03 02:10:36 +00:00
related-work.md docs: Add GitButler to related-work 2025-07-06 12:51:44 +00:00
releasing.md docs: put bare URLs in angle brackets 2025-06-07 20:20:47 +00:00
revsets.md docs: update description of trunk() revset 2025-08-18 13:28:32 +00:00
revsets.toml website: Add the CHANGELOG 2025-07-17 22:59:58 +00:00
roadmap.md docs/cli: update URLs to from martinvonz user to jj-vcs org 2024-12-17 12:44:44 -08:00
sapling-comparison.md docs: update Sapling comparison logs 2025-02-01 16:50:53 +00:00
style_guide.md style-guide: say that we prefer lower-level tests over e2e test 2025-08-19 06:30:00 +00:00
templates.md templates: add string.match function 2025-09-02 02:19:54 +00:00
testimonials.md docs: add some more testimonials 2025-04-08 20:55:09 +00:00
tutorial.md undo: revert progressively older operations with repeated calls 2025-08-24 06:56:40 +00:00
windows.md local working copy: add support for EOL conversion 2025-07-17 15:36:28 +00:00
working-copy.md docs: mention jj file track where snapshot.auto-track is described 2025-07-22 13:17:14 +00:00