From b1b82f5705058dec59f0dc7a532a3da7766a0a65 Mon Sep 17 00:00:00 2001 From: mrbeanc Date: Sat, 3 Aug 2024 17:25:58 +0800 Subject: [PATCH] update README: refer `Libra` --- README.md | 67 +++++++++++++++++++++++++++++---------------------- README_en.md | 68 +++++++++++++++++++++++++++++++--------------------- 2 files changed, 80 insertions(+), 55 deletions(-) diff --git a/README.md b/README.md index 83889b0..37cde09 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ MIT: Mini-Git implementation in Rust -中文文档 | **[English](./README_en.md)** +中文文档 | **[English](./README_en.md)** [项目链接](https://github.com/MrBeanCpp/MIT) @@ -11,65 +11,76 @@ Git in Rust. 用 `Rust` 实现的mini `Git`. Called `mit`. > 旨在简洁易读、高效且安全 > 学习`Git`的最好方法就是去实现`Git` -> +> > 本项目旨在提供一套 [小学二年级] 都能看懂的`Git`实现 -> +> > `// rm -rf 死板的设计模式 & 复杂的仓库架构` -> +> +**注意:** 更完善的`Git`实现，可以参考我们的另一个项目： +[Mega-Libra](https://github.com/web3infra-foundation/mega/tree/main/libra) + ## 良好的跨平台支持 + - [x] Windows - [x] MacOS - [x] Linux (Unix-like...) ## 主要功能 -- 支持的输入路径(`pathspec`)：文件路径、目录路径（绝对或相对，包括`.` `./` `../`） + +- 支持的输入路径(`pathspec`)：文件路径、目录路径（绝对或相对，包括`.` `./` `../`） -- 支持 `mit init`, `mit add`, `mit rm`, `mit commit` +- 支持 `mit init`, `mit add`, `mit rm`, `mit commit` - [x] `init`: 初始化（若仓库已存在，则不执行）- `idempotent` - [x] `add`: 将变更添加至暂存区（包括新建、修改、删除），可指定文件或目录 - - `-A(all)` : 暂存工作区中的所有文件（从根目录开始）变更（新建√ 修改√ 删除√） - - `-u(update)`: 仅对暂存区[`index`]中已跟踪的文件进行操作（新建× 修改√ 删除√） - - [x] `rm`: 将文件从暂存区 &| 工作区移除. - - `--cached` : 仅从暂存区移除，取消跟踪 - - `-r(recursive)`: 递归删除目录，删除目录时必须指定该参数 + - `-A(all)` : 暂存工作区中的所有文件（从根目录开始）变更（新建√ 修改√ 删除√） + - `-u(update)`: 仅对暂存区[`index`]中已跟踪的文件进行操作（新建× 修改√ 删除√） + - [x] `rm`: 将文件从暂存区 &| 工作区移除. + - `--cached` : 仅从暂存区移除，取消跟踪 + - `-r(recursive)`: 递归删除目录，删除目录时必须指定该参数 - [x] `commit` - [x] `status`: 显示工作区、暂存区、`HEAD` 的状态，（只包含当前目录）；分为三部分： - - **Staged to be committed:** 暂存区与`HEAD`(最后一次`Commit::Tree`)比较，即上次的暂存区 - - **Unstaged:** 暂存区与工作区比较，未暂存的工作区变更 - - **Untracked:** 暂存区与工作区比较，从未暂存过的文件（即未跟踪的文件） + - **Staged to be committed:** 暂存区与`HEAD`(最后一次`Commit::Tree`)比较，即上次的暂存区 + - **Unstaged:** 暂存区与工作区比较，未暂存的工作区变更 + - **Untracked:** 暂存区与工作区比较，从未暂存过的文件（即未跟踪的文件） - [x] `log` -- 支持分支 `mit branch`, `mit switch`, `mit restore` +- 支持分支 `mit branch`, `mit switch`, `mit restore` - [x] `branch` - [x] `switch` - 与 `checkout` 不同，`switch` 需要指明`--detach`，才能切换到一个`commit`，否则只能切换分支。 - 同时为里简化实现，有任何未提交的修改，都不能切换分支。 + 与 `checkout` 不同，`switch` 需要指明`--detach`，才能切换到一个`commit`，否则只能切换分支。 + 同时为里简化实现，有任何未提交的修改，都不能切换分支。 - [x] `restore`: 回滚文件 - - 将指定路径（可包含目录）的文件恢复到`--source` 指定的版本，可指定操作暂存区 &| 工作区 + - 将指定路径（可包含目录）的文件恢复到`--source` 指定的版本，可指定操作暂存区 &| 工作区 - `--source`：可指定`Commit Hash` `HEAD` `Branch Name` - - 若不指定`--source`，且无`--staged`，则恢复到`HEAD`版本，否则从暂存区[`index`]恢复 - - 若`--staged`和`--worktree`均未指定，则默认恢复到`--worktree` - - 对于`--source`中不存在的文件，若已跟踪，则删除；否则忽略 + - 若不指定`--source`，且无`--staged`，则恢复到`HEAD`版本，否则从暂存区[`index`]恢复 + - 若`--staged`和`--worktree`均未指定，则默认恢复到`--worktree` + - 对于`--source`中不存在的文件，若已跟踪，则删除；否则忽略 -- 支持简单的合并 `mit merge` (fast-forward) -- - [x] Merge(FF) +- 支持简单的合并 `mit merge` (fast-forward) +- + - [x] Merge(FF) ## 备注 + ### ⚠️测试需要单线程 + ⚠️注意：为了避免冲突，执行测试时请加上`--test-threads=1` 如：`cargo test -- --test-threads=1` 因为测试需要对同一个文件夹进行IO + ### 名词释义 -- 暂存区：`index` or `stage`，保存下一次`commit`需要的的文件快照 -- 工作区：`worktree`，用户直接操作的文件夹 -- 工作目录：`working directory` or `repository`，代码仓库的根目录，即`.mit`所在的目录 -- `HEAD`：指向当前`commit`的指针 -- 已跟踪：`tracked`，指已经在暂存区[`index`]中的文件（即曾经`add`过的文件） + +- 暂存区：`index` or `stage`，保存下一次`commit`需要的的文件快照 +- 工作区：`worktree`，用户直接操作的文件夹 +- 工作目录：`working directory` or `repository`，代码仓库的根目录，即`.mit`所在的目录 +- `HEAD`：指向当前`commit`的指针 +- 已跟踪：`tracked`，指已经在暂存区[`index`]中的文件（即曾经`add`过的文件） ### 介绍视频 + [【Mit】Rust实现的迷你Git - 系统软件开发实践 结课报告_哔哩哔哩_bilibili](https://www.bilibili.com/video/BV1p64y1E78W/) diff --git a/README_en.md b/README_en.md index 19631e5..fdb8ba3 100644 --- a/README_en.md +++ b/README_en.md @@ -2,7 +2,7 @@ MIT: Mini-Git implementation in Rust - **[中文文档](./README.md)** | English +**[中文文档](./README.md)** | English [Project Link](https://github.com/MrBeanCpp/MIT) @@ -11,53 +11,65 @@ Git in Rust. A mini Git implementation called`mit`, implemented in `Rust`. > Designed to be concise, readable, efficient, and secure. > > The best way to learn Git is to implement Git. -> +> > This project aims to provide a `Git` implementation that even a second-grader can understand. -> +> > `// rm -rf rigid design patterns & complex repository architecture` -> +> + +**NOTE:** For a more comprehensive implementation of `Git`, please refer to another project of ours: +[Mega-Libra](https://github.com/web3infra-foundation/mega/tree/main/libra) ## Cross-Platform Support + - [x] Windows - [x] MacOS - [x] Linux (Unix-like...) ## Key Features -- Supports input paths (pathspec): file paths, directory paths (absolute or relative, including `.`, `./`, `../`) -- Supports `mit init`, `mit add`, `mit rm`, `mit commit` +- Supports input paths (pathspec): file paths, directory paths (absolute or relative, including `.`, `./`, `../`) + +- Supports `mit init`, `mit add`, `mit rm`, `mit commit` - [x] `init`: Initialize (does nothing if the repository already exists) - `idempotent` - [x] `add`: Add changes to the staging area (including new, modified, deleted), can specify files or directories - - `-A(all)` : Stage all changes in the working directory (from the root) (new✅ modified✅ deleted✅) - - `-u(update)`: Operate only on tracked files in the staging area [`index`] (new❌ modified✅ deleted✅) - - [x] `rm`: Remove files from the staging area & working directory - - `--cached` : Remove only from the staging area, untrack - - `-r(recursive)`: Recursively delete directories, must specify this parameter when deleting directories + - `-A(all)` : Stage all changes in the working directory (from the root) (new✅ modified✅ deleted✅) + - `-u(update)`: Operate only on tracked files in the staging area [`index`] (new❌ modified✅ deleted✅) + - [x] `rm`: Remove files from the staging area & working directory + - `--cached` : Remove only from the staging area, untrack + - `-r(recursive)`: Recursively delete directories, must specify this parameter when deleting directories - [x] `commit` - - [x] `status`: Display the status of the working directory, staging area, and `HEAD` (only for the current directory); divided into three parts: - - **Staged to be committed:** Changes staged in the staging area compared to `HEAD` (last `Commit::Tree`), i.e., the last staging area - - **Unstaged:** Changes in the working directory not staged in the staging area - - **Untracked:** Files in the working directory not staged or tracked before + - [x] `status`: Display the status of the working directory, staging area, and `HEAD` (only for the current + directory); divided into three parts: + - **Staged to be committed:** Changes staged in the staging area compared to `HEAD` (last `Commit::Tree`), + i.e., the last staging area + - **Unstaged:** Changes in the working directory not staged in the staging area + - **Untracked:** Files in the working directory not staged or tracked before - [x] `log` -- Supports branches`mit branch`, `mit switch`, `mit restore` +- Supports branches`mit branch`, `mit switch`, `mit restore` - [x] `branch` - [x] `switch` - Unlike `checkout`, `switch` requires specifying `--detach` to switch to a `commit`, otherwise, it can only switch branches. + Unlike `checkout`, `switch` requires specifying `--detach` to switch to a `commit`, otherwise, it can only + switch branches. - [x] `restore`: Rollback files - - Restore files at the specified path (including directories) to the version specified by `--source`, can specify staging area & working directory + - Restore files at the specified path (including directories) to the version specified by `--source`, can + specify staging area & working directory - `--source`： Can specify `Commit Hash`, `HEAD`, or `Branch Name` - - If `--source` is not specified and neither `--staged` nor `--worktree` is specified, restore to the `HEAD` version, otherwise, restore from the staging area [`index`] - - If neither `--staged` nor `--worktree` is specified, default to restore to `--worktree` - - For files not present in `--source`, if tracked, delete; otherwise, ignore + - If `--source` is not specified and neither `--staged` nor `--worktree` is specified, restore to the `HEAD` + version, otherwise, restore from the staging area [`index`] + - If neither `--staged` nor `--worktree` is specified, default to restore to `--worktree` + - For files not present in `--source`, if tracked, delete; otherwise, ignore -- Supports simple merging `mit merge` (fast-forward) +- Supports simple merging `mit merge` (fast-forward) - [x] Merge(FF) ## Notes + ### ⚠️Testing requires single-threading + ⚠️ Note: To avoid conflicts, please use `--test-threads=1` when executing tests. For example:`cargo test -- --test-threads=1` @@ -65,11 +77,13 @@ For example:`cargo test -- --test-threads=1` This is because testing involves IO on the same folder. ### Term Definitions -- Staging area: `index` or `stage`, stores file snapshots needed for the next `commit` -- Working directory: `worktree`, the folder directly manipulated by the user -- Repository: `working directory` or `repository`, the root directory of the code repository, where `.mit` is located -- `HEAD`：Points to the current`commit` -- Tracked：`tracked`，files already in the staging area [`index`](i.e., files that have been `add`-ed) + +- Staging area: `index` or `stage`, stores file snapshots needed for the next `commit` +- Working directory: `worktree`, the folder directly manipulated by the user +- Repository: `working directory` or `repository`, the root directory of the code repository, where `.mit` is located +- `HEAD`：Points to the current`commit` +- Tracked：`tracked`，files already in the staging area [`index`](i.e., files that have been `add`-ed) ### Introductory Video + [【Mit】Rust implementation of Mini-Git - System Software Development Practice Final Report_Bilibili](https://www.bilibili.com/video/BV1p64y1E78W/)