Skip to content

xlei1123/limux-dgit

Repository files navigation

Dgit

Dgit 是一个便携下载 github 仓库指定目录或者指定文件的工具,它可以作为命令行全局安装在终端使用,也可以作为node模块加载使用。 该工具不依赖本地git,可以直接下载指定目录指定文件,减少流量消耗,对于希望下载很大项目的场景非常适合,可以直接下载你需要的内容。

安装

  • 全局安装
$ npm install @limu-x/dgit -g
  • 本地安装
$ npm install @limu-x/dgit --save
$ yarn add @limu-x/dgit

使用

特别说明,默认仓库托管在github上,国内可以拉取gitee仓库代码,请配置gitType: 'gitee'

  • 全局安装,作为命令行使用
$ dgit d https://github.com/xlei1123/limu-ele-pro/tree/master/src -d ./abc
  • 本地安装,作为模块使用
import dgit from '@limu-x/dgit';

(async () => {
    await dgit(
        {
            owner: 'xlei1123',
            repoName: 'limu-ele-pro',
            ref: 'master',
            relativePath: 'src',
            gitType: 'gitee'
        },
        './aaa',
    );
    console.log('download succeed');
})()

配置

  • 全局安装,作为命令行使用,可配置参数

    • Commands:
      • download|d [options] [githubLink] 下载指定仓库的指定文件,或指定目录下的所有文件.
    • Options:
      • --owner git 仓库作者名,当不指定 githubLink的时候可以使用.
      • --repo-name git 仓库名称,当不指定 githubLink的时候可以使用.
      • --ref git 仓库指定 branch,commit hash 或 tagname,当不指定 githubLink的时候可以使用.
      • --relative-path 指定git所需要下载的目录或者文件相对位置,默认为当前目录 '.'
      • -d, --dest 指定文件输出目录,可以是绝对路径,也可以是当前终端执行路径的相对路径.
      • -l, --parallel-limit, 指定并行下载数量,默认为 10.
      • -u, --username, 指定git用户名, 在下载私有仓库时需要的配置参数.
      • -p --password, 指定git密码, 同username 一起使用,在下载私有仓库时需要的配置参数.
      • -t --token, git token 是另一种登录方式的可配置参数,用于下载私有仓库.
      • -e --exclude, <relativePath,...,relativePath> 指定当前下载目录需要排除的文件或目录路径集合.
      • -i --include, <relativePath,...,relativePath> 指定当前排除的文件路径集合中需要重新包含的文件或目录集合.
      • -h, --help 帮助文档
  • 局部安装,作为模块使用时,可配置参数

    import dgit from '@limu-x/dgit';
    import path from 'path';
    const repoOption = {
        owner: 'xlei1123'; // git 仓库作者名
        repoName: 'limu-ele-pro'; // git 仓库名称
        ref: 'master'; // git 仓库指定 branch,commit 或 tag,
        relativePath: '.'; // 指定git所需要下载的目录或者文件相对位置
        username: ''; // 指定git用户名, 在下载私有仓库时需要的配置参数.
        password: ''; // 指定git密码, 同username 一起使用,在下载私有仓库时需要的配置参数.
        token: ''; // git token 是另一种登录方式的可配置参数,用于下载私有仓库.
    }
    
    const githubLinkOption = {
        githubLink: 'https://github.com/xlei1123/limu-ele-pro/blob/master/PLAN.txt', // 也可以直接指定github 需要下载路径的地址
    }
    
    const destPath = path.resolve(__dirname, './aaa'); // 目标下载路径
    
    const dgitOptions = {
        maxRetryCount: 3, // 网络问题下载失败时尝试最大重新下载次数
        parallelLimit: 10, // 并行下载个数
        log: false, // 是否开启内部日志
        logSuffix: '', // 日志前缀
        exclude: [], // 需要排除的文件路径,
        include: [], // 需要包含的文件路径
    }
    
    const hooks = {
        onSuccess: () => void,
        onError: (err) => err,
        onProgress: (status, node) => void,
        onResolved: (status) => void,
    }
    
    
    (async () => {
        await dgit(
            repoOption,
            destPath,
            dgitOptions,
            hooks,
        );
        console.log('repoOption download succeed.');
    
        await dgit(
            githubLinkOption,
            destPath,
            dgitOptions,
            hooks,
        );
        console.log('githubLinkOption download succeed.');
    })()

注意

  1. 在下载私有仓库的时候需要提供下载权限,此时需要传入额外的参数,方式有两种
  • Basic authentication

    通过传入 用户名 和 密码,来提供下载权限, 当传入用户名,可以不显式提供密码,在没有提供密码时,会单独出现密码提示

    $ dgit d https://github.com/xlei1123/limu-ele-pro/tree/master/src -d ./abc -u xlei1123
  • OAuth2 token

    Token 是另一种 github 提供的权限认证的方式。

    设置token方法 ,就位于Github Settings -> Developer settings -> Personal access tokens

    $ dgit d https://github.com/xlei1123/limu-ele-pro/tree/master/src -d ./abc -t OAUTH-TOKEN
  1. 下载资源失败 raw.githubusercontent.com 连接失败
    由于国内访问 raw.githubusercontent.com 地址,除了墙以外,大多数还有一种情况就是域名 dns污染 ,需要查询正确的 ip 地址

    • 【查询方案1】:打开 https://www.ipaddress.com/ 输入访问不了的域名,查询之后可以获得正确的 IP 地址,

    Tips: 可能该 ip 因为墙的问题还是访问不了,可以使用下面的方案

    • 【查询方案2】:打开 https://site.ip138.com/raw.githubusercontent.com/ ,可以查询到对应国内中国香港的 IP 地址

    在本机的 host 文件中添加映射,建议使用 switchhosts 方便 host 管理,在 host文件中追加记录,如下选取其中一个即可,国内建议用第二个

    199.232.68.133 raw.githubusercontent.com # 美国
    151.101.76.133 raw.githubusercontent.com # 中国香港

建议

欢迎创建issue 或者 pr here.

License

MIT