diff --git a/demos/README.md b/demos/README.md new file mode 100644 index 0000000000..eb36f7e983 --- /dev/null +++ b/demos/README.md @@ -0,0 +1,41 @@ +# Screenshots with demos and scripts to generate them + +The `demo_*.sh` scripts in this directory demo +various features of `jj`. + +The `run_scripts.sh` script can be used to: + +- Run them inside a standardized environment instead of the user's local + environment. +- Generate SVG and PNG images for the scripts. + +The PNG images in the repo may be slightly older, as they take up more space in +the repo. + +The SVG images have human-readable diffs, but may look different on different +computers with different fonts installed. + +## Running `run_scripts.sh` + +This requires ImageMagick and `term-transcript-cli` to be installed. See +`run_scripts.sh`'s error messages for some more details. + +One way to make all the images and check the output is: + +```shell +cd demos +./run_scripts.sh demo_*.sh |less +``` + +### A note on fonts + +The exact PNG output depends on the fonts you have installed on your system. + +The screenshots are usually generated on a Debian Linux system and use the "Fira +Code" font. It can be installed with `sudo apt install fonts-firacode`. It seems +to include all relevant Unicode symbols and be a little bolder and thus more +readable than the "Liberation Mono" font, which is used if Fira Code is not +installed (which also works OK). `Consolas` and `SFMono-Regular` are added for +web viewing. + +`convert -list Fonts` will list the fonts ImageMagick is aware of. diff --git a/demos/git_compat.svg b/demos/git_compat.svg new file mode 100644 index 0000000000..16f0c1dab8 --- /dev/null +++ b/demos/git_compat.svg @@ -0,0 +1,87 @@ + + + + + + + +# Clone a Git repo: + +$ jj git clone https://github.com/octocat/Hello-World +Fetching into new repo in "/tmp/tmp.FzCQ5K0fCd/Hello-World" +Working copy now at: rmsvpzst e4dbb280 (empty) (no description set) +Parent commit      : orrkosyo 7fd1a60b master | (empty) Merge pull request #6 fr↓ +om Spaceghost/patch-1 +Added 1 files, modified 0 files, removed 0 files +$ cd Hello-World + +# Inspect it: + +$ jj log -r 'all()' +@  rmsvpzst jjfan@example.com 2023-09-16 21:50:32.000 -07:00 e4dbb280 +│  (empty) (no description set) +│ ◉  tpstlust support+octocat@github.com 2018-05-10 12:55:19.000 -05:00 +├─╯  octocat-patch-1 b1b3f972 +│    sentence case +│ ◉  kowxouwz octocat@nowhere.com 2014-06-10 15:22:26.000 -07:00 test b3cbd5bb +├─╯  Create CONTRIBUTING.md +◉    orrkosyo octocat@nowhere.com 2012-03-06 15:06:50.000 -08:00 master 7fd1a60b +├─╮  (empty) Merge pull request #6 from Spaceghost/patch-1 +│ ◉  nznozkvv Johnneylee.rollins@gmail.com 2011-09-13 21:42:41.000 -07:00 +├─╯  76294131 +│    New line at end of file. --Signed off by Spaceghost +◉  syktoqts cameron@github.com 2011-01-26 11:06:08.000 -08:00 553c2077 +│  first commit +◉  zzzzzzzz root() 00000000 +$ jj diff -r b1 +Modified regular file README: +   1    1: Hello Worldworld! + +# The repo is backed by the actual Git repo: + +$ git --git-dir=.jj/repo/store/git log --graph --all --decorate --oneline +* db9d0cd  +* e4dbb28  +| * b1b3f97 (origin/octocat-patch-1) sentence case +|/   +| * b3cbd5b (origin/test) Create CONTRIBUTING.md +|/   +*   7fd1a60 (origin/master) Merge pull request #6 from Spaceghost/patch-1 +|\   +| * 7629413 New line at end of file. --Signed off by Spaceghost +|/   +* 553c207 first commit + + + diff --git a/demos/juggle_conflicts.svg b/demos/juggle_conflicts.svg new file mode 100644 index 0000000000..20a5933a26 --- /dev/null +++ b/demos/juggle_conflicts.svg @@ -0,0 +1,130 @@ + + + + + + + +# We are in a repo with three commits, all +# editing the same line: + +$ jj log +@  smrqtvtv jjfan@example.com 2023-09-16 21:50:33.426 -07:00 eb215836 +│  (empty) (no description set) +◉  oxqyoovk jjfan@example.com 2023-09-16 21:50:33.425 -07:00 third eeb2c6d9 +│  third +◉  zyxuklro jjfan@example.com 2023-09-16 21:50:33.383 -07:00 second a713551b +│  second +◉  uyvvvvkm jjfan@example.com 2023-09-16 21:50:33.343 -07:00 first 2b128607 +│  first +◉  zzzzzzzz root() 00000000 +$ jj diff -r first +Added regular file file: +        1: first +$ jj diff -r second +Modified regular file file: +   1    1: firstsecond +$ jj diff -r third +Modified regular file file: +   1    1: secondthird + +# Let's reorder the second and third commits: + +$ jj rebase -s third -d first +Rebased 2 commits +Working copy now at: smrqtvtv 8d33adb7 (conflict) (empty) (no description set) +Parent commit      : oxqyoovk 62fea634 third | (conflict) third +Added 0 files, modified 1 files, removed 0 files +$ jj rebase -s second -d third +Rebased 1 commits +$ jj log +◉  zyxuklro jjfan@example.com 2023-09-16 21:50:33.563 -07:00 second 48e9acfd +│  second +│ @  smrqtvtv jjfan@example.com 2023-09-16 21:50:33.537 -07:00 8d33adb7 conflict +├─╯  (empty) (no description set) +◉  oxqyoovk jjfan@example.com 2023-09-16 21:50:33.537 -07:00 third 62fea634 +│  conflict +│  third +◉  uyvvvvkm jjfan@example.com 2023-09-16 21:50:33.343 -07:00 first 2b128607 +│  first +◉  zzzzzzzz root() 00000000 + +# The commit labeled "third" has a conflict, +# as expected. What's more interesting is +# that the top commit has no conflict! That's +# because it has the changes from all three +# commits applied to it. + + +# Let's verify that by looking at its contents: + +$ jj co second +Working copy now at: unwqytsp 79bcefe9 (empty) (no description set) +Parent commit      : zyxuklro 48e9acfd second | second +Added 0 files, modified 1 files, removed 0 files +$ cat file +third + +# Let's now instead make "second" and "third" +# sibling and merge them: + +$ jj rebase -s second -d first +Rebased 2 commits +Working copy now at: unwqytsp a64d5bfa (empty) (no description set) +Parent commit      : zyxuklro f9813715 second | second +Added 0 files, modified 1 files, removed 0 files +$ jj merge second third -m merged +Working copy now at: rolvyyqw b2089d05 (empty) merged +Parent commit      : zyxuklro f9813715 second | second +Parent commit      : oxqyoovk 62fea634 third | (conflict) third +Added 0 files, modified 1 files, removed 0 files +$ jj log +@    rolvyyqw jjfan@example.com 2023-09-16 21:50:33.661 -07:00 b2089d05 +├─╮  (empty) merged +│ ◉  oxqyoovk jjfan@example.com 2023-09-16 21:50:33.537 -07:00 third 62fea634 +│ │  conflict +│ │  third +◉ │  zyxuklro jjfan@example.com 2023-09-16 21:50:33.640 -07:00 second f9813715 +├─╯  second +◉  uyvvvvkm jjfan@example.com 2023-09-16 21:50:33.343 -07:00 first 2b128607 +│  first +◉  zzzzzzzz root() 00000000 + +# Again, because the merge commit has the +# changes from all three commits, it has no +# conflict. + + + + diff --git a/demos/operation_log.svg b/demos/operation_log.svg new file mode 100644 index 0000000000..18d318188a --- /dev/null +++ b/demos/operation_log.svg @@ -0,0 +1,169 @@ + + + + + + + +# We are in the octocat/Hello-World repo. +# The "operation log" shows the operations +# so far: + +$ jj op log +@  944b06270a2c jjfan@jujube now, lasted 1 millisecond +│  check out git remote's default branch +│  args: jj git clone https://github.com/octocat/Hello-World +◉  63095284120d jjfan@jujube now, lasted 457 milliseconds +│  fetch from git remote into empty repo +│  args: jj git clone https://github.com/octocat/Hello-World +◉  e663308954fa jjfan@jujube now, lasted 1 millisecond +│  add workspace 'default' +◉  95c48e65122a jjfan@jujube now, lasted less than a microsecond +   initialize repo + +# We are going to make some changes to show +# how the operation log works. Let's add a file, set +# a description, and rebase onto the "test" branch: + +$ echo stuff > new-file +$ jj describe -m stuff +Working copy now at: lsywywpx 13ac5438 stuff +Parent commit      : orrkosyo 7fd1a60b master | (empty) Merge pull request #6 fr↓ +om Spaceghost/patch-1 +$ jj rebase -d test +Rebased 1 commits +Working copy now at: lsywywpx 377355e1 stuff +Parent commit      : kowxouwz b3cbd5bb test | Create CONTRIBUTING.md +Added 1 files, modified 0 files, removed 0 files + +# We are now going to make another change off of +# master: + +$ jj co master +Working copy now at: luvqloow cb520197 (empty) (no description set) +Parent commit      : orrkosyo 7fd1a60b master | (empty) Merge pull request #6 fr↓ +om Spaceghost/patch-1 +Added 0 files, modified 0 files, removed 2 files +$ jj describe -m "other stuff" +Working copy now at: luvqloow 8d738e0e (empty) other stuff +Parent commit      : orrkosyo 7fd1a60b master | (empty) Merge pull request #6 fr↓ +om Spaceghost/patch-1 + +# The repo now looks like this: + +$ jj log +@  luvqloow jjfan@example.com 2023-09-16 21:50:34.000 -07:00 8d738e0e +│  (empty) other stuff +│ ◉  lsywywpx jjfan@example.com 2023-09-16 21:50:34.000 -07:00 377355e1 +│ │  stuff +│ ◉  kowxouwz octocat@nowhere.com 2014-06-10 15:22:26.000 -07:00 test b3cbd5bb +├─╯  Create CONTRIBUTING.md +◉  orrkosyo octocat@nowhere.com 2012-03-06 15:06:50.000 -08:00 master 7fd1a60b +│  (empty) Merge pull request #6 from Spaceghost/patch-1 +~ + +# The most recent portion of the operation log +# is: + +$ jj op log | head +@  d62203e95faf jjfan@jujube now, lasted less than a microsecond +│  describe commit cb5201978464f88695bd4791598d45a21be0c271 +│  args: jj describe -m 'other stuff' +◉  b70193b4854c jjfan@jujube now, lasted 1 millisecond +│  check out commit 7fd1a60b01f91b314f59955a4e4d4e80d8edf11d +│  args: jj co master +◉  1134b48562b5 jjfan@jujube now, lasted 1 millisecond +│  rebase commit 13ac54383ddc28c356c3a2ce66f6d20216362f0d and descendants +│  args: jj rebase -d test +◉  f7adf9a1d5dc jjfan@jujube now, lasted 1 millisecond + +# Let's undo that rebase operation: + +$ jj undo d62203e9 +Working copy now at: luvqloow cb520197 (empty) (no description set) +Parent commit      : orrkosyo 7fd1a60b master | (empty) Merge pull request #6 fr↓ +om Spaceghost/patch-1 + +# Note that only the rebase was undone, and the +# subsequent "other stuff" change was not undone: + +$ jj log +@  luvqloow jjfan@example.com 2023-09-16 21:50:33.000 -07:00 cb520197 +│  (empty) (no description set) +│ ◉  lsywywpx jjfan@example.com 2023-09-16 21:50:34.000 -07:00 377355e1 +│ │  stuff +│ ◉  kowxouwz octocat@nowhere.com 2014-06-10 15:22:26.000 -07:00 test b3cbd5bb +├─╯  Create CONTRIBUTING.md +◉  orrkosyo octocat@nowhere.com 2012-03-06 15:06:50.000 -08:00 master 7fd1a60b +│  (empty) Merge pull request #6 from Spaceghost/patch-1 +~ + +# We can also see what the repo looked like +# after the rebase operation: + +$ jj --at-op d62203e9 log +@  luvqloow jjfan@example.com 2023-09-16 21:50:34.000 -07:00 8d738e0e +│  (empty) other stuff +│ ◉  lsywywpx jjfan@example.com 2023-09-16 21:50:34.000 -07:00 377355e1 +│ │  stuff +│ ◉  kowxouwz octocat@nowhere.com 2014-06-10 15:22:26.000 -07:00 test b3cbd5bb +├─╯  Create CONTRIBUTING.md +◉  orrkosyo octocat@nowhere.com 2012-03-06 15:06:50.000 -08:00 master 7fd1a60b +│  (empty) Merge pull request #6 from Spaceghost/patch-1 +~ + +# Let's say we instead want to go back to the +# state of the repo right after the rebase: + +$ jj op restore d62203e9 +Working copy now at: luvqloow 8d738e0e (empty) other stuff +Parent commit      : orrkosyo 7fd1a60b master | (empty) Merge pull request #6 fr↓ +om Spaceghost/patch-1 + +# We're now back to before the "other stuff" +# change existed: + +$ jj log +@  luvqloow jjfan@example.com 2023-09-16 21:50:34.000 -07:00 8d738e0e +│  (empty) other stuff +│ ◉  lsywywpx jjfan@example.com 2023-09-16 21:50:34.000 -07:00 377355e1 +│ │  stuff +│ ◉  kowxouwz octocat@nowhere.com 2014-06-10 15:22:26.000 -07:00 test b3cbd5bb +├─╯  Create CONTRIBUTING.md +◉  orrkosyo octocat@nowhere.com 2012-03-06 15:06:50.000 -08:00 master 7fd1a60b +│  (empty) Merge pull request #6 from Spaceghost/patch-1 +~ + + + diff --git a/demos/resolve_conflicts.svg b/demos/resolve_conflicts.svg new file mode 100644 index 0000000000..702b21a103 --- /dev/null +++ b/demos/resolve_conflicts.svg @@ -0,0 +1,139 @@ + + + + + + + +# We are on the master branch of the +# octocat/Hello-World repo: + +$ jj log -r 'all()' +@  vzlkrspz jjfan@example.com 2023-09-16 21:50:36.000 -07:00 fe0c497b +│  (empty) (no description set) +│ ◉  tpstlust support+octocat@github.com 2018-05-10 12:55:19.000 -05:00 +├─╯  octocat-patch-1 b1b3f972 +│    sentence case +│ ◉  kowxouwz octocat@nowhere.com 2014-06-10 15:22:26.000 -07:00 test b3cbd5bb +├─╯  Create CONTRIBUTING.md +◉    orrkosyo octocat@nowhere.com 2012-03-06 15:06:50.000 -08:00 master 7fd1a60b +├─╮  (empty) Merge pull request #6 from Spaceghost/patch-1 +│ ◉  nznozkvv Johnneylee.rollins@gmail.com 2011-09-13 21:42:41.000 -07:00 +├─╯  76294131 +│    New line at end of file. --Signed off by Spaceghost +◉  syktoqts cameron@github.com 2011-01-26 11:06:08.000 -08:00 553c2077 +│  first commit +◉  zzzzzzzz root() 00000000 + +# Let's make an edit that will conflict +# when we rebase it: + +$ jj describe -m "README: say which world" +Working copy now at: vzlkrspz a87fe7e1 (empty) README: say which world +Parent commit      : orrkosyo 7fd1a60b master | (empty) Merge pull request #6 fr↓ +om Spaceghost/patch-1 +$ echo "Hello Earth!" > README +$ jj diff +Modified regular file README: +   1    1: Hello WorldEarth! + +# We're going to rebase it onto commit b1. +# That commit looks like this: + +$ jj diff -r b1 +Modified regular file README: +   1    1: Hello Worldworld! + +# Now rebase: + +$ jj rebase -d b1 +Rebased 1 commits +Working copy now at: vzlkrspz 28bf7e6c (conflict) README: say which world +Parent commit      : tpstlust b1b3f972 octocat-patch-1 | sentence case +Added 0 files, modified 1 files, removed 0 files + +# Huh, that seemed to succeed. Let's take a +# look at the repo: + +$ jj log -r 'all()' +@  vzlkrspz jjfan@example.com 2023-09-16 21:50:36.000 -07:00 28bf7e6c conflict +│  README: say which world +◉  tpstlust support+octocat@github.com 2018-05-10 12:55:19.000 -05:00 +│  octocat-patch-1 b1b3f972 +│  sentence case +│ ◉  kowxouwz octocat@nowhere.com 2014-06-10 15:22:26.000 -07:00 test b3cbd5bb +├─╯  Create CONTRIBUTING.md +◉    orrkosyo octocat@nowhere.com 2012-03-06 15:06:50.000 -08:00 master 7fd1a60b +├─╮  (empty) Merge pull request #6 from Spaceghost/patch-1 +│ ◉  nznozkvv Johnneylee.rollins@gmail.com 2011-09-13 21:42:41.000 -07:00 +├─╯  76294131 +│    New line at end of file. --Signed off by Spaceghost +◉  syktoqts cameron@github.com 2011-01-26 11:06:08.000 -08:00 553c2077 +│  first commit +◉  zzzzzzzz root() 00000000 +$ jj status +Working copy changes: +M README +There are unresolved conflicts at these paths: +README    2-sided conflict +Working copy : vzlkrspz 28bf7e6c (conflict) README: say which world +Parent commit: tpstlust b1b3f972 octocat-patch-1 | sentence case + +# As you can see, the rebased commit has a +# conflict. The file in the working copy looks +# like this: + +$ cat README +<<<<<<< +%%%%%%% +-Hello World! ++Hello world! ++++++++ +Hello Earth! +>>>>>>> + +# Now we will resolve the conflict: + +$ echo "Hello earth!" > README + +# The status command no longer reports it: + +$ jj status +Working copy changes: +M README +Working copy : vzlkrspz a434efad README: say which world +Parent commit: tpstlust b1b3f972 octocat-patch-1 | sentence case + + + diff --git a/demos/run_scripts.sh b/demos/run_scripts.sh index 26e257c547..fa7b061fb3 100755 --- a/demos/run_scripts.sh +++ b/demos/run_scripts.sh @@ -51,7 +51,12 @@ run_script_through_term_transcript_and_pipe_result_to_stderr() { tee /dev/stderr | \ term-transcript capture \ --no-inputs --pure-svg --palette powershell \ + --font "Fira Code, Liberation Mono, SFMono-Regular, Consolas, Menlo" \ --out "$script_base".svg "$script_base" + # The default font choice term-transcript would make is: + # SFMono-Regular, Consolas, Liberation Mono, Menlo + # We add the fonts that were checked and seem to contain all the relevant + # unicode in front. } for script in "$@"; do diff --git a/demos/working_copy.svg b/demos/working_copy.svg new file mode 100644 index 0000000000..9c1ff98c18 --- /dev/null +++ b/demos/working_copy.svg @@ -0,0 +1,141 @@ + + + + + + + +# We are in the octocat/Hello-World repo. +# We have an empty working copy on top of master: + +$ jj status +The working copy is clean +Working copy : lpotmuxz 950f3f73 (empty) (no description set) +Parent commit: orrkosyo 7fd1a60b master | (empty) Merge pull request #6 from Spa↓ +ceghost/patch-1 +$ jj log +@  lpotmuxz jjfan@example.com 2023-09-16 21:50:37.000 -07:00 950f3f73 +│  (empty) (no description set) +◉  orrkosyo octocat@nowhere.com 2012-03-06 15:06:50.000 -08:00 master 7fd1a60b +│  (empty) Merge pull request #6 from Spaceghost/patch-1 +~ + +# Now make some changes in the working copy: + +$ echo "Goodbye World!" > README +$ echo stuff > new-file + +# Our working copy's commit ID changed +# because we made changes: + +$ jj status +Working copy changes: +M README +A new-file +Working copy : lpotmuxz fe6a4af3 (no description set) +Parent commit: orrkosyo 7fd1a60b master | (empty) Merge pull request #6 from Spa↓ +ceghost/patch-1 +$ jj log +@  lpotmuxz jjfan@example.com 2023-09-16 21:50:37.000 -07:00 fe6a4af3 +│  (no description set) +◉  orrkosyo octocat@nowhere.com 2012-03-06 15:06:50.000 -08:00 master 7fd1a60b +│  (empty) Merge pull request #6 from Spaceghost/patch-1 +~ + +# Add a branch so we can easily refer to this +# commit: + +$ jj branch create goodbye +$ jj log +@  lpotmuxz jjfan@example.com 2023-09-16 21:50:37.000 -07:00 goodbye fe6a4af3 +│  (no description set) +◉  orrkosyo octocat@nowhere.com 2012-03-06 15:06:50.000 -08:00 master 7fd1a60b +│  (empty) Merge pull request #6 from Spaceghost/patch-1 +~ + +# Start working on a new change off of master: + +$ jj co master +Working copy now at: ounkkvrs a54c61a2 (empty) (no description set) +Parent commit      : orrkosyo 7fd1a60b master | (empty) Merge pull request #6 fr↓ +om Spaceghost/patch-1 +Added 0 files, modified 1 files, removed 1 files +$ jj log +@  ounkkvrs jjfan@example.com 2023-09-16 21:50:36.000 -07:00 a54c61a2 +│  (empty) (no description set) +│ ◉  lpotmuxz jjfan@example.com 2023-09-16 21:50:37.000 -07:00 goodbye fe6a4af3 +├─╯  (no description set) +◉  orrkosyo octocat@nowhere.com 2012-03-06 15:06:50.000 -08:00 master 7fd1a60b +│  (empty) Merge pull request #6 from Spaceghost/patch-1 +~ + +# Note that the working copy is now clean; the +# "goodbye" change stayed in its own commit: + +$ jj status +The working copy is clean +Working copy : ounkkvrs a54c61a2 (empty) (no description set) +Parent commit: orrkosyo 7fd1a60b master | (empty) Merge pull request #6 from Spa↓ +ceghost/patch-1 + +# Modify a file in this new change: + +$ echo "Hello everyone!" > README + +# The working copy is not special; we can, for +# example, set the description of any commit. +# First, set it on the working copy: + +$ jj describe -m everyone +Working copy now at: ounkkvrs efab10c4 everyone +Parent commit      : orrkosyo 7fd1a60b master | (empty) Merge pull request #6 fr↓ +om Spaceghost/patch-1 + +# Now set it on the change we worked on before: + +$ jj describe goodbye -m goodbye + +# Inspect the result: + +$ jj log +◉  lpotmuxz jjfan@example.com 2023-09-16 21:50:38.000 -07:00 goodbye 5e859fe3 +│  goodbye +│ @  ounkkvrs jjfan@example.com 2023-09-16 21:50:38.000 -07:00 efab10c4 +├─╯  everyone +◉  orrkosyo octocat@nowhere.com 2012-03-06 15:06:50.000 -08:00 master 7fd1a60b +│  (empty) Merge pull request #6 from Spaceghost/patch-1 +~ + + +