branch: externals/vc-jj
commit 3b404bf6f4af97f713d286a6b99f7bd1f3237ce0
Author: Kristoffer Balintona <[email protected]>
Commit: Kristoffer Balintona <[email protected]>
Expand README and tweak package commentary
---
README.org | 80 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++---
vc-jj.el | 60 +++++++++++++++++++++++++---------------------
2 files changed, 110 insertions(+), 30 deletions(-)
diff --git a/README.org b/README.org
index 8fa876fe1f..631b1d2faa 100644
--- a/README.org
+++ b/README.org
@@ -57,7 +57,81 @@ Jujutsu offers many configuration options. Vc-jj has not
thoroughly
tested its compatibility with these options, but it is expected that
vc-jj work well even if the user configures many of them.
-** Contributing
+* Jujutsu and Git
+
+Jujutsu is a distributed version control system that is separated from
+the format in which files are stored on-disk. Currently, the only
+storage backend jujutsu supports is Git, although other storage
+backends may be supported in the future.
+
+Since version 0.34.0, jujutsu repositories are "colocated" by default.
+Earlier versions of jujutsu may colocate a Git repository with ~jj git
+clone --colocate REPOSITORY-URL~. Colocated repositories are ones that
+contain both a ".jj" and a ".git" directory in the repository root,
+allowing users to use both Jujutsu and Git commands in the same
+repository, without one getting in the way of the other. (Although
+Git will complain about being in "detached HEAD" state.) Because of
+this colocation, vc-jj can reuse some vc-git functionality where
+appropriate, such as handling '.gitignore' files.
+
+** Jujutsu terminology and concepts
+
+To those used to other version control systems, like Git, jujutsu's
+version control model may be unfamiliar.
+
+Below is an attempt at a brief description of jujutsu-specific
+terminology and concepts.
+
+In Jujutsu, there are both "commits" and "changes." In Git, the
+primary unit of history is the commit, which is immutable and
+identified by a commit hash. In jujutsu, the primary unit is the
+change. A jujutsu "*commit*" is the same as in Git: a snapshot in time
+of the repository. In Jujutsu, "*revision*" can be used interchangeably
+with "commit." A *"change"*, on the other hand, is unique to jujutsu:
+it can be thought of as a /logical unit of work/. A change is like the
+entire evolution of a commit as it changes over time. Each change has
+an underlying commit.
+
+As the user modifies the repository, all changes are automatically
+recorded and all non-ignored files are automatically tracked.
+Consequently, unlike Git, there is no straging area or check-in
+operation. Instead, all modifications occur in the current change ---
+the "*working copy*." As files are edited, added, and deleted, jujutsu
+will take *snapshots* of the repository and automatically *rewrite* the
+underlying commit of the working copy, keeping the change intact but
+changing the corresponding underlying commit.
+
+Every change has a corresponding change ID and every commit has a
+corresponding commit ID. Most jj commands accept both change IDs and
+commit IDs.
+
+Because of the conceptual differences between Git and Jujutsu,
+commands that assume a stage/commit workflow behave differently or are
+no-ops when used via vc-jj.
+
+In Git, ~git log~ shows a log of commits. In Jujutsu, ~jj log~ shows a
+log of changes. History rewriting is a normal part of jj’s workflow.
+Changes may be edited, split, or reordered while preserving their
+identity via the change ID. Users will find that it is much more
+natural to make changes in a repository by rewriting, playing with,
+and modifying the change log.
+
+Finally, in Jujutsu, there are *bookmarks*. Although each git *branch*
+corresponds to a Jujutsu bookmark and vice versa, a bookmark is merely
+an alias or named pointer to a commit. (Bookmarks automatically
+follow a commit if it gets rewritten.) The working copy (current
+change) may be on a bookmark's commit, but it is not "attached" to it
+in the way a commit in Git corresponds to a certain branch: bookmarks
+do not move when new changes are made atop them. Users familiar with
+Mercurial will find that Jujutsu bookmarks are more similar to
+[[https://wiki.mercurial-scm.org/Bookmarks][Mercurial bookmarks]] than Git
branches.
+
+Users may read more about the concepts and terms used in jujutsu here:
+https://docs.jj-vcs.dev/latest/. In particular, a glossary of all
+jujutsu-specific terms can be found here:
+https://docs.jj-vcs.dev/latest/glossary/.
+
+* Contributing
We welcome bug reports and pull requests! =vc-jj.el= tries its best to
support Emacs 28.1 and above, but users may notice bugs related to
@@ -74,8 +148,8 @@ place; feel free to contact us for details. Note that
"trivial"
The code in file =vc-jj.el= is organized according to the structure set
out in the preamble of the file =vc.el= in the Emacs source tree.
-Test code coverage can be checked via the
[[https://emacs-eldev.github.io/eldev/][Eldev]] tool and
[[https://github.com/trezona-lecomte/coverage][coverage]]:
-run ~eldev test --undercover simplecov,dontsend~ in the project root
+Test code coverage can be checked via the
[[https://emacs-eldev.github.io/eldev/][Eldev]] tool and
[[https://github.com/trezona-lecomte/coverage][coverage]]: run
+~eldev test --undercover simplecov,dontsend~ in the project root
directory then activate =coverage-mode= inside =vc-jj.el=.
* Other Emacs packages for Jujutsu
diff --git a/vc-jj.el b/vc-jj.el
index bfae8df51a..4dad995230 100644
--- a/vc-jj.el
+++ b/vc-jj.el
@@ -25,39 +25,45 @@
;;; Commentary:
-;; A backend for vc.el to handle Jujutsu (jj) repositories.
+;; This package provides a backend for vc.el to handle Jujutsu (jj)
+;; repositories. Jujutsu uses a change-centric model that differs in
+;; important ways from Git’s commit-centric model. Vc-jj adapts
+;; vc.el’s abstractions to match jj terminology and behavior.
;;
-;; Jujutsu is a distributed version control system that uses the same
-;; on-disk storage format as git (although other storage backends are
-;; possible). Jj repositories are "co-located" by default, which
-;; means they contain both a '.jj' and a '.git' directory in the
-;; repository root. Therefore, vc-jj can re-use some functionality of
-;; vc-git, like handling of '.gitignore' files. It is possible to run
-;; git commands in a co-located repository, although git will complain
-;; about being in "detached HEAD" state.
+;; Users may see and customize all options by pressing
;;
-;; Note that 'JJ' should come before 'Git' in `vc-handled-backends' so
-;; that 'vc' chooses the jj backend.
+;; 'M-x customize-group vc-jj RET'
;;
-;; In jj terminology, vc "revisions" are called "changes" and are
-;; identified by a "change ID"; the code in vc-jj tries to adhere to
-;; this terminology.
-;;
-;; In contrast to git, there is no staging area or check-in operation:
-;; as the user modifies a file, the changes are automatically
-;; recorded. Note that the change ID stays constant when the current
-;; change is being modified, e.g., by editing a file. Underlying each
-;; change is a (git-type) commit with a commit ID; the commit ID
-;; changes when a change gets modified. Most jj commands accept both
-;; change IDs and commit IDs. We display both change ID and commit ID
-;; where appropriate, for example in the extra headers of vc-dir
-;; buffers.
+;; and using the Customize menu.
+
+;; STATUS AND LIMITATIONS
;;
+;; Vc-jj implements most commonly used vc.el commands (such as
+;; `vc-dir', `vc-diff', `vc-print-log', and file state queries), but
+;; some operations are not yet supported or behave differently from
+;; vc-git due to jj’s model.
+;; FILE STRUCTURE
+;;
;; After the "Customization" and "Internal Utilities" sections, the
;; organization of this file follows the "BACKEND PROPERTIES" section
-;; at the beginning of 'vc.el', implementing the functions listed
-;; there in the same order.
+;; of the preamble of the 'vc.el' file: each outline heading
+;; corresponding to a vc backend method and the contents of each
+;; heading relate to implementing that backend method.
+
+;; FEEDBACK AND CONTRIBUTIONS
+;;
+;; Bug reports and contributions are welcome, especially for
+;; unimplemented vc.el backend methods. The home of this project is
+;; found here: https://codeberg.org/emacs-jj-vc/vc-jj.el. Users may
+;; file bug reports in the "Issues" tab and create pull requests in
+;; the "Pull requests" tab.
+;;
+;; Vc-jj prefers jujutsu's terminology and attempts to adhere to it,
+;; so we ask contributors to try their best to use the terminology
+;; specific to jujutsu as opposed to other version control systems,
+;; such as Git. A brief description of these differences can be found
+;; above.
;;; Code:
@@ -538,7 +544,7 @@ parents.map(|c| concat(
"Return the current change id of the repository containing FILE."
(when-let* ((default-directory (vc-jj-root file)))
;; 'jj log' might print a warning at the start of its output,
- ;; e.g., "Warning: Refused to snapshot some files". The output we
+ ;; e.g., "Warning: Refused to snapshot some files." The output we
;; want will be printed afterwards.
(car (last (vc-jj--process-lines "log" "--no-graph"
"-r" "@"
