Dgit

• English
• 简体中文

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

• 安装
• 使用
• 配置
• 注意
• 示例
• 建议
• License

安装

• 全局安装

$ 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

2. 下载资源失败 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