3 releases (breaking)

0.4.0 Jan 21, 2024
0.2.0 Jan 19, 2024
0.1.0 Dec 16, 2023

#247 in Web programming

28 downloads per month

Apache-2.0

695KB
108 lines

rust实现一个gh-pages工具

nodejs有个gh-pages包,可以把项目里的某个文件夹发布到gh-pages非常方便,因此想用rust实现一个版本,对于rust生态的用户来说,多一个选择。这样使用mdbookgh_page_tool可以非常方便的管理自己的博客。 完整代码在github,gh_page_tool地址

实现原理分析

gh_page_tool使用的时候只有一个命令,gh_page_tool publish -d book -b gh-pages,这个命令行工具,有两个参数-d-b

  1. -d代表静态博客的目录,默认值是book,这个是mdbook的默认输出目录
  2. -b代表发到github的哪个分支,默认是gh-pages分支,这是github的gh-pages功能的分支。

方案选择

从上面的使用方式可以看出,这个命令行就是把某个目录文件,推送到远程的gh-pages分支。

  • 方案一、在当前目录进行操作,调用git的命令进行commit和push。
    • 优点:实现起来简单
    • 缺点:容易对源项目的提交和内容产生影响
  • 方案二、创建一个临时目录,把内容复制到临时目录,在临时目录操作,最后删除临时目录。
    • 优点:对原项目无干扰,
    • 缺点:实现复杂,性能会慢一点点,但对于rust来说不是问题。 综合来看,个人感觉对于原项目不能造成干扰,做好一个工具应该做的事情,因此选用方案二

流程图

下面是一个publish命令的简单执行流程。

graph TB
    A(开始publish) --> B(解析命令参数)
    B(解析命令参数) --> C(创建temp目录)
    C(创建temp目录) --> D(复制静态资源到temp)
    D(复制静态资源到temp) --> E(在temp下git init)
    E(在temp下git init) --> F(复制git config文件)
    F(复制git config文件) --> G(执行git checkout)
    G(执行git checkout) --> H(执行git add)
    H(执行git add) --> I(执行git commit)
    I(执行git commit) --> J(执行git push)
    J(执行git push) --> K(temp自动销毁)

开始实现功能

步骤 1:创建Rust项目

首先,创建一个新的 Rust 项目:

cargo new gh_page_tool
cd gh_page_tool

步骤 2:添加依赖并配置

在项目的 Cargo.toml 文件中添加如下依赖。

  1. clap是用来构建命令行工具的。
  2. fs_extra是用来复制文件夹,简化操作。
  3. tempfile是创建临时文件,支持自动销毁。
[dependencies]
clap = "4.4.0"
fs_extra = "1.2.0" 
tempfile = "3.2.0"

然后运行 cargo build 以安装依赖项。

步骤 3:解析命令行参数

src/main.rs 中,使用 clap 来构建命令行接口并解析参数:

use clap::{arg, Command};
mod publish_lib;
fn main() {
    let matches = Command::new("gh_page")
        .version("1.0")
        .author("tommy")
        .about("Implements gh-pages like functionality")
        .subcommand(
            Command::new("publish")
                .about("Publishes a directory to a gh-pages branch")
                .arg(arg!(-d --directory <DIRECTORY> "Sets the directory to publish"))
                .arg(arg!(-b --branch <BRANCH> "Sets the branch to publish to"))
        )
        .get_matches();

    if let Some(matches) = matches.subcommand_matches("publish") {
        let default_dir = String::from("book");
        let default_branch = String::from("gh-pages");
        let directory = matches.get_one::<String>("directory").unwrap_or(&default_dir);
        let branch = matches.get_one::<String>("branch").unwrap_or(&default_branch);
        publish_lib::publish(directory, branch);
    }
}

步骤 4:实现publish功能

实现 publish 函数以完成推送工作。 这里有几个点需要注意:

  1. 复制文件到temp时,复制的是整个book文件夹,后面执行git操作需要到book目录下面。
  2. 复制git config文件需要在git init之后,要不然config文件会覆盖。
  3. 复制过git config文件后,需要切换到git项目的目录,防止因为路径出问题。
  4. dest_path = dest_path.join(directory);是把目录切换到book目录。
use std::fs;
use std::path::Path;
use std::process::Command;
use tempfile::TempDir;

pub(crate) fn publish(directory: &str, branch: &str) {
    // 创建临时目录
    let temp_dir = TempDir::new_in(".").expect("Failed to create temp directory");
    let temp_dir_path = temp_dir.path();
    let source_path: &Path = Path::new(directory);
    // 确保目录存在
    if !source_path.exists() {
        panic!("Directory :{} does not exist", directory);
    }

    // 复制文件到临时目录
    // 这里我们假设 `directory` 是一个文件夹路径
    let mut dest_path = temp_dir_path.join("gh_page_content");
    // 目录不存在,创建目录
    let _ = fs::create_dir_all(&dest_path)
        .map(|_| println!("created temp dir {} Success", dest_path.to_str().unwrap()));
    if !dest_path.exists() {
        panic!("Directory :{} does not exist", dest_path.to_str().unwrap());
    }

    // 复制 .git 配置到临时目录
    let git_config_path = Path::new(".git/config");

    copy_dir_all(&source_path, &dest_path);
    
    // 切换到book目录
    dest_path = dest_path.join(directory);
    // 在临时目录中进行 Git 操作
    // 初始化 Git 仓库
    let status = Command::new("git")
        .args(&["init"])
        .current_dir(&dest_path)
        .status()
        .expect("Failed to initialize git");
    if !status.success() {
        panic!("Failed to initialize git repository");
    }
    println!("git init success!");

    // 复制 .git 配置到临时目录
    if git_config_path.exists() {
        let target_config_path = dest_path.join(".git/config");
        println!(
            "git copy config start  source:{} , target:{}",
            git_config_path.to_str().unwrap(),
            target_config_path.to_str().unwrap()
        );

        fs::copy(git_config_path, target_config_path).expect("Failed to copy .git/config");
        println!("git copy config success!");
    } else {
        panic!("No .git/config found in the root directory");
    }
    
    // 切换到临时目录
    std::env::set_current_dir(&dest_path).expect("Failed to change to temp directory");

    let status = Command::new("git")
        .args(&["checkout", "-b", branch])
        .status()
        .expect("Failed to checkout branch");
    if !status.success() {
        panic!("Failed to  checkout branch: {}", branch);
    }
    println!("git checkout {} success!", branch);
    
    // 以此类推,添加 git add, git commit 和 git push 的操作
    // ......    

   
    // 退出临时目录
    // 临时目录将在 `temp_dir` 变量离开作用域时自动删除
    let _ = temp_dir.close().expect("drop temp dir failed!");
}

// 递归复制目录
fn copy_dir_all(src: &Path, dst: &Path) {
    let options = fs_extra::dir::CopyOptions::new(); // 默认选项
    fs_extra::dir::copy(src, dst, &options).expect("Failed to copy directory");
    println!("copy_dir_all to temp success!");
}

如果想给命令行工具发布到cargo,开源参考我的两个文章。

  1. 发布到crate教程: https://zhuanlan.zhihu.com/p/668756184
  2. 支持代码提示教程:https://zhuanlan.zhihu.com/p/669543058

步骤 5:copy命令行工具

cargo build
cp target/debug/gh_page_tool ~/.cargo/bin/

步骤 6:验证成果

找个mdbook的测试项目,或者gitbook的,在项目根目录执行 gh_page_tool publish -d book -b gh-pages

参考文档

  1. gh-pages插件:https://www.npmjs.com/package/gh-pages
  2. clap包:https://docs.rs/clap/4.4.0/clap/index.html

Dependencies