feat(docs)!: update docs

Author: gaojunran

README.md

@@ -6,63 +6,19 @@ Fast, opinionated version control experience. Powered by [jj-vcs](https://github
 
 ## Goals
 
-- Most actions (commit, push, rebase, ...) can be done with a single command, with reasonable default arguments.
-- Try my best to make jj compatible with git remote actions (pull, push, create PRs...). Some bookmark actions are annoying, I make them implicit.
-- Integrate GitHub workflow into jj, (powered by gh cli).
-- Final goal: make a freshman user able to use jj **without any git knowledge**.
+- ⚡️ Minimal Commands
 
-MAKE **VERSION CONTROL** GREAT AGAIN!
+No more interactive rebases or hard-to-remember Git commands. Do everything with a single command!
 
-## Planned Features
-- [x] Clone a repo
-  - [x] shorthand for github
-  - [ ] shorthand for your own github repo (powered by gh cli)
-  - [ ] Fork and clone a repo (powered by gh cli)
-- [x] Download a repo (powered by [degit-rs](https://github.com/psnszsn/degit-rs))
-  - [x] Download specified file / folder (powered by [cloneit](https://github.com/alok8bb/cloneit))
-- [x] Initialize a repo
-  - [x] Create a new repo on GitHub
-  - [x] Add remote to local repo
-  - [x] Create a default branch
-  - [ ] Download a .gitignore
-- [x] Commit specified files
-  - [x] `--push` option
-  - [ ] Experimental config: allow array message input
-- [x] Amend changes
-  - [x] `--force`: `--ignore-immutable`
-- [x] Reset changes
-- [x] Push to remote
-  - [x] If no branch specified, push the closest bookmark
-  - [x] (for a multi-worker branch) Pull before Push `--pull`
-  - [x] (for a multi-branch repo) Update trunk `--upbase`
-  - [x] `--change` option
-- [x] Pull from Remote
-- [x] Update Trunk from a branch (`upbase`)
-- [ ] GitHub PR Create, TBD
-- [ ] Consider co-locate with git, to get highest IDE / git-tool compatibility
-  - [ ] `clone --colocate`
-  - [ ] `init --colocate`
-  - [ ] config: check git or not
-  - [ ] config: use colocate by default or not
-- [ ] Record repos that managed by hj, and launch selector if there's no `.jj` in cwd. (?)
-- [x] Make `hj keepup` independent
-  - [ ] closest pushable: [discussion](https://github.com/jj-vcs/jj/discussions/5568#discussioncomment-13007551) 
-- [x] `hj switch`: `hj keepup`, `hj new` and `git switch`, useful for colocation
-  - [x] allow shortcuts: `hj main` for `hj switch main`
-- [x] `hj all`: same as `hj log -r "all()"`
-  - [ ] Other log commands, TBD
-- [ ] `hj rollback`: interactive rollback, using skim
-- [ ] Publish document
+- 🛠️ Seamless Integration with Git and Git Forges
 
+Fully compatible with Git-based CLI tools and IDEs, with special optimizations for GitHub workflows!
 
-## Nice ideas that may be added in `hj`
+- ⭐️ Beginner Friendly
 
-- ✅ [Find the closest bookmark in history to advance it forward](https://github.com/jj-vcs/jj/discussions/5568)
-- ✅ [Select all my branches with the goal of rebasing them all on the trunk](https://github.com/jj-vcs/jj/discussions/4974)
-- [`gh pr create`](https://github.com/jj-vcs/jj/discussions/6279)
-- [jj configurations](https://github.com/jj-vcs/jj/discussions/5812)
-- [GitHub Integration](https://github.com/jj-vcs/jj/issues/4555)
+Get started easily without any knowledge of Git or jj-vcs.
 
+MAKE **VERSION CONTROL** GREAT AGAIN!
 
 ## Now you can try hj ...
 

docs/cn/api-examples.md

@@ -1,5 +1,9 @@
 # 分支
 
+
+
+## 分支的「书签」模型
+
 :::details 对于熟悉 git 的用户
 
 hj 中的分支模型和 git 中不同。每次提交（commit）后，hj 不会像 git 一样将分支的头指针指向新的提交；更新分支头指针只会发生在 `hj push` 和 `hj switch` 时。
@@ -12,6 +16,8 @@ hj 的分支（书签）模型基于 jj 改进而来。`hj push` 和 `hj switch`
 
 :::
 
+TODO
+
 ## 切换分支
 
 :::details 对于熟悉 git 的用户
@@ -48,3 +54,6 @@ hj switch BRANCH
 ```
 
 来切换到一个分支。
+
+
+

docs/cn/branch.md

@@ -214,7 +214,7 @@ hj squash -i --from A --into B
 
 ---
 
-## 将提交中的变更拆分为一个提交
+## 拆分提交
 
 ::: details 对于熟悉 git 的用户
 
@@ -274,3 +274,33 @@ hj rebase -s A -d B
 这将把提交 A 移动到提交 B 之上。
 
 更多用法参见 [jj rebase](https://jj-vcs.github.io/jj/latest/cli-reference/#jj-rebase)。
+
+## 删除提交
+
+::: details 对于熟悉 git 的用户
+
+`hj abandon B` 近似于：
+
+```sh
+git rebase --onto B^ B
+```
+
+特别地，如果 B 是合并提交，`B^`（ B 的父提交）可能存在多个。这种情况下你需要显式地指定，否则命令会失败。
+
+:::
+
+::: details 对于熟悉 jj 的用户
+
+`hj abandon` 和 `jj abandon` 完全等价。
+
+:::
+
+`abandon` 命令可以用来删除一个提交：
+
+```sh
+hj abandon REVSET
+```
+
+这将移除这个提交，并将其子提交变基到其父提交上。
+
+特别地，如果不指定 `REVSET`，将默认为工作副本（`@`）。此时会清空工作副本的所有变更，并自动地创建一个新工作副本提交。

docs/cn/commit.md

@@ -1,6 +1,6 @@
 # 常见问题
 
-## 已经有了 git / jj，为什么还要自己造一个工具？
+## 已经有了 git / jj-vcs，为什么还要自己造一个工具？
 
 [git](https://git-scm.com/) 有着悠久的历史，并且绝大多数开源代码都托管在基于 git 的平台上。几乎不可能撼动 git 的地位。
 
@@ -10,24 +10,24 @@
 
 如果你感兴趣的话，这里有一篇关于 git 的文章：[关于 Git 的礼节](https://www.yinwang.org/blog-cn/2015/03/11/git-etiquette)。
 
-[jj](https://github.com/jj-vcs/jj) 是一个革新性的工具，具备了很多新的理念：
+[jj-vcs](https://github.com/jj-vcs/jj) 是一个革新性的工具，具备了很多新的理念：
 
 - 工作副本（工作区）也是一个提交。这样不需要 stash，而且切换分支和变基永远不会失败。
-- 不需要索引区（index / staging），所有变更默认被提交，也包括 git 中的未追踪文件。
+- 不需要索引区（暂存区），所有变更默认被提交，也包括 git 中的未追踪文件。
 - 不再需要交互式变基，子提交会被自动变基。
 - 使用函数式语言指定文件和变更，而不是使用上古时期的方式解析文本。
 - 有着默认的根提交。
 - ……
 
 这些理念上的革新使得 jj 的本地版本控制非常优秀。
 
-但是 jj 在与 git 远程的互作性上有待进步。例如书签（分支 HEAD）并不会随着提交而推进；pull / push 的模型依然需要非常熟练才能掌握。
+但是 jj 在与 git 远程的互作性上有待进步。例如书签（分支 HEAD）并不会随着提交而推进；pull / push 的模型依然需要非常熟练才能掌握。jj 与 Git Forge（如 GitHub）的互作性也不够好。
 
-而且 jj 是另一套工具，依然有着不小的学习成本。
+而且 jj 是另一套工具和使用理念，不论你是否学过 Git 都有着不小的学习成本。
 
 所以有了 hj，致力于基于 jj 的优秀理念，提供一个 90% 场景下极简的版本控制体验，降低你的学习成本（你甚至可以在不了解 git 和 jj 的情况下上手），并且在一些特殊场景中你可以随时切换回 jj 进行操作。
 
-让我们来举几个例子说明 hj 的极简性：
+让我们来举几个例子说明 hj 相较于 jj 的极简性：
 
 - 你可以一行命令开始版本控制、新建一个默认的主分支、创建一个 GitHub 仓库、并把远程仓库关联到本地：
 
@@ -53,8 +53,19 @@ hj 将不断进步！💪🏻
 
 - `hj undo` 是基于 `jj undo` 的。而 hj 的很多操作不是原子化的，例如 `hj switch` 内部执行了两行 jj 命令，所以 `hj undo` 不能够完全撤销一个操作。未来我们会根据 `hj op restore` 封装一个命令。
 
-- 因为 hj 基于 jj，所以短期内几乎不可能实现各种 IDE 或插件的适配（因为 jj 的知名度远远不够）。如果你非常需要这些适配的话，可以考虑 [与 Git 仓库共存](/init.html#与-git-仓库共存)。
+- 因为 hj 基于 jj，所以短期内几乎不可能实现各种 IDE 或插件的原生适配（因为 jj 的知名度远远不够）。如果你非常需要这些适配的话，可以考虑 [与 Git 仓库共存](/cn/init.html#与-git-仓库共存)。
 
 - hj 的很多改变工作副本指向的操作不会自动推进书签。这是 jj 的特意设计，hj 正在尝试解决。
 
 - hj 还没有发布各架构的 Release。现在你仅能通过 `cargo install --path .` 来安装。
+
+## 路线图
+
+- 🚧　涉及 `gh` CLI 的命令支持省略 `owner`，默认为当前登录的用户。
+- 🚧　`hj clone --fork`
+- 🚧　`hj download` 下载单个文件(夹) 时直接下载到指定的目录，而不包含远程仓库中的文件夹结构。
+- 🚧　`hj init` 时支持下载 `.gitignore`。（[来源](https://github.com/github/gitignore)）
+- 🚧　全面支持 GitLab。
+- 🚧　`hj commit` 和 `hj describe` 时支持打开编辑器进行多行描述的编辑。
+- 🚧　`hj rollback`：交互式选择要回退的命令。
+- 🚧　优化与 Git 仓库共存时的体验。

docs/cn/faq.md

@@ -5,21 +5,28 @@ layout: home
 hero:
   name: "hj"
   text: ""
-  tagline: Fast, opinionated version control experience.
+  tagline: 易用的版本控制工具。
   actions:
     - theme: brand
-      text: Markdown Examples
-      link: /markdown-examples
+      text: 快速上手
+      link: /cn/init
     - theme: alt
-      text: API Examples
-      link: /api-examples
+      text: 为什么选择 hj
+      link: /cn/faq
 
 features:
-  - title: Feature A
-    details: Lorem ipsum dolor sit amet, consectetur adipiscing elit
-  - title: Feature B
-    details: Lorem ipsum dolor sit amet, consectetur adipiscing elit
-  - title: Feature C
-    details: Lorem ipsum dolor sit amet, consectetur adipiscing elit
+  - title: ⚡️ 极简的命令
+    details: 不再使用交互式变基和难记的 Git 命令，一行命令实现所有操作！
+  - title: 🛠️ 与 Git 和 Git Forge 完美集成
+    details: 兼容基于 Git 的命令行工具和 IDE，针对 GitHub 工作流特别优化！
+  - title: ⭐️ 新手友好
+    details: 在不了解 Git 和 jj-vcs 的情况下轻松上手。
 ---
 
+<style module>
+h1 > span {
+  font-family: monospace;
+}
+
+
+</style>

docs/cn/index.md

@@ -42,7 +42,7 @@ jj bookmark set main
 hj init --github
 ```
 
-这将调用本地的命令行工具 [gh](https://cli.github.com/) 来创建一个新的 GitHub 仓库，并将其设置为远程 origin 仓库。仓库默认以 **当前目录名** 命名，并为公开仓库（可以额外传递参数 `--private` 来创建私有仓库）。
+这将调用本地的命令行工具 [gh](https://cli.github.com/) 来创建一个新的 GitHub 仓库，并将其设置为远程名为 `origin` 的仓库。仓库默认以 **当前目录名** 命名，并为公开仓库（可以额外传递参数 `--private` 来创建私有仓库）。
 
 :::tip
 
@@ -85,10 +85,10 @@ hj open
 另外，你可以使用：
 
 ```sh
-hj open REMOTE
+hj open REMOTE   # 默认的远程名是 origin
 ```
 
-来使用默认的浏览器打开远程仓库的网页地址，例如最常见远程名是 `origin`。
+来使用默认的浏览器打开远程仓库的网页地址。
 
 
 <!-- 运行：