v1.0.0 · 开源免费

简洁高效的 Git 工具

一条命令完成项目上传与下载，自动检测并处理超过 200MB 的大文件，无需手动配置 Git LFS

⬇ 下载源码 (ZIP) 快速开始 命令参考
源码下载
下载 Git Tool
下载完整源代码压缩包，解压后即可使用，无需任何第三方依赖
📦
git-tool.zip
完整源码包 · 约 13 KB · 包含全部 Python 源文件
⬇ 下载 ZIP

压缩包内容

📁 git_tool/核心源码包
⚙ __init__.py包定义
⚙ config.py配置管理
⚙ utils.py工具函数
⚙ lfs.py大文件 LFS 管理
⚙ core.py核心 Git 操作
⚙ cli.py命令行界面
⚙ main.py程序入口
⚙ setup.py安装配置（可选全局安装）
📄 requirements.txt依赖说明（无需第三方依赖）
核心特性
为什么选择 Git Tool
专注解决日常 Git 操作的痛点，大文件处理从此不再烦恼
⚡

一键上传

upload 命令自动完成 大文件检测 → LFS 跟踪 → add → commit → push 全流程

📦

大文件支持

自动扫描超过阈值的文件，添加 Git LFS 跟踪规则并迁移，支持 >200MB 文件上传

⬇

智能下载

克隆项目后自动识别 LFS 文件并拉取，大文件无需额外操作

⚙

灵活配置

大文件阈值、跟踪扩展名、默认分支等均可自定义，配置持久化存储

🔎

大文件扫描

lfs scan 命令快速定位仓库中的大文件，直观展示文件大小和路径

🔒

零额外依赖

纯 Python 标准库实现，无需 pip install 任何第三方包

快速开始
安装与初始化
只需三步即可开始使用
1

确保已安装 Git 和 Git LFS

Git Tool 依赖 Git 和 Git LFS（用于大文件传输）

bash
# 检查 Git 是否已安装 git --version # 安装 Git LFS（macOS） brew install git-lfs git lfs install # Ubuntu / Debian sudo apt install git-lfs git lfs install
2

下载并解压源码

从上方下载专区获取 git-tool.zip，解压到任意目录后进入该目录

bash
# 解压下载的压缩包 unzip git-tool.zip -d git-tool cd git-tool
3

初始化配置（可选）

首次使用会自动创建默认配置，也可手动初始化

git-tool
# 初始化配置文件 python3 main.py config init # （可选）全局安装，之后可直接使用 git-tool 命令 pip3 install -e .
⚠ 如果未安装 Git LFS，工具会给出安装提示，大文件将无法上传到 LFS 存储，但其余功能正常使用
命令参考
所有命令一览
统一入口 python3 main.py，所有命令通过子命令调用

📁 初始化与远程仓库

init初始化 git 仓库 ▼

在当前目录初始化一个新的 Git 仓库，自动配置用户信息和 Git LFS

示例
python3 main.py init python3 main.py init --bare # 创建裸仓库 python3 main.py init --no-lfs # 跳过 LFS 初始化 python3 main.py -C /path/to/dir init # 指定目录
参数说明
--bare创建裸仓库（无工作区，适用于服务端）
--no-lfs不自动初始化 Git LFS
-C <dir>指定工作目录（全局参数，所有命令通用）
add-remote添加/更新远程仓库 ▼

添加远程仓库地址，若同名远程已存在则更新 URL

示例
python3 main.py add-remote origin https://github.com/user/repo.git python3 main.py add-remote upstream https://gitlab.com/project.git
参数说明
name远程仓库名（如 origin、upstream）
url仓库地址（HTTPS 或 SSH）

🚀 上传与下载

upload上传项目（add + commit + push） ▼

核心命令，一条命令完成：大文件检测 → LFS 跟踪 → git add → git commit → git push

示例
# 最常用：一键上传 python3 main.py upload -m "添加新功能" # 只提交不推送 python3 main.py upload -m "本地提交" --no-push # 不自动 git add（需要手动 add） python3 main.py upload -m "部分提交" --no-add # 指定远程和分支 python3 main.py upload -m "更新" -r origin -b feature-x
参数说明默认
-m / --message提交信息自动生成时间戳
-r / --remote远程仓库名origin
-b / --branch推送分支当前分支
--no-add不自动执行 git add-
--no-push只提交不推送-
ℹ upload 会自动扫描大文件并添加 LFS 跟踪规则，无需手动操作
download下载（克隆）项目 ▼

克隆远程仓库，自动识别 LFS 文件并拉取

示例
# 克隆到当前目录 python3 main.py download https://github.com/user/repo.git # 克隆到指定目录 python3 main.py download https://github.com/user/repo.git ./my-project # 克隆指定分支 python3 main.py download -b develop https://github.com/user/repo.git # 浅克隆（节省时间和空间） python3 main.py download --depth 1 https://github.com/user/repo.git
参数说明
url仓库地址（必填）
dest目标目录（默认当前目录）
-b / --branch指定克隆分支
--depth浅克隆深度
pull拉取远程更新 ▼

拉取远程仓库的最新更新，同时拉取 LFS 大文件

示例
python3 main.py pull python3 main.py pull -r upstream -b main
参数说明默认
-r / --remote远程仓库名origin
-b / --branch分支名当前分支

🔍 查看状态

status查看仓库状态 ▼

显示当前分支、文件变更状态和大文件扫描结果

示例
python3 main.py status python3 main.py -C /path/to/repo status
log查看提交历史 ▼
示例
python3 main.py log python3 main.py log -n 20 # 显示最近 20 条
参数说明默认
-n / --count显示条数10

📦 LFS 大文件管理

lfs scan扫描大文件 ▼

扫描仓库中超过阈值的大文件，显示文件路径和大小

示例
python3 main.py lfs scan
lfs track为大文件添加 LFS 跟踪 ▼

自动检测大文件并按扩展名生成 .gitattributes 跟踪规则

示例
python3 main.py lfs track
lfs track-ext按扩展名添加跟踪规则 ▼

为指定扩展名或常见大文件类型批量添加 LFS 跟踪规则

示例
# 为常见类型添加跟踪（使用默认列表） python3 main.py lfs track-ext # 为指定扩展名添加跟踪 python3 main.py lfs track-ext "*.mp4" "*.zip" "*.psd"
lfs init初始化 Git LFS ▼
示例
python3 main.py lfs init
lfs status查看 LFS 状态 ▼

显示当前 LFS 跟踪规则和已管理的 LFS 文件列表

示例
python3 main.py lfs status

⚙ 配置管理

config list列出所有配置 ▼
示例
python3 main.py config list
config set设置配置项 ▼
示例
python3 main.py config set lfs_threshold_mb 100 python3 main.py config set default_branch develop python3 main.py config set auto_push false python3 main.py config set user_name "Your Name"
config get获取配置项 ▼
示例
python3 main.py config get lfs_threshold_mb
config reset重置为默认配置 ▼
示例
python3 main.py config reset
配置参考
所有配置项
配置文件存储于 ~/.git_tool/config.json
配置键 类型 默认值 说明
lfs_threshold_mb int 200 大文件阈值（MB），超过此大小自动使用 Git LFS
lfs_extensions list *.zip, *.mp4 ... LFS 跟踪的文件扩展名列表
default_branch str main init 时创建的默认分支名
commit_prefix str "" 提交信息前缀，如 "[项目名]"
auto_config_user bool true 初始化时是否自动配置 user.name / user.email
user_name str Git Tool User 自动配置的用户名
user_email str gittool@example.com 自动配置的邮箱
auto_push bool true upload 时是否自动 push
timeout int 0 命令执行超时时间（秒），0 = 不限制
深入理解
大文件处理流程
了解 upload 命令如何自动处理 >200MB 的大文件
1

扫描大文件

递归扫描仓库目录，找出所有超过 lfs_threshold_mb（默认 200MB）的文件，跳过 .git 目录

2

初始化 Git LFS

若仓库未初始化 LFS，自动执行 git lfs install，创建 .gitattributes 文件

3

添加跟踪规则

按大文件扩展名自动生成 git lfs track 规则并写入 .gitattributes，避免重复添加

4

迁移已跟踪文件

如果大文件已被 git 普通跟踪，自动执行 git rm --cached + git add 将其转为 LFS 管理

5

提交并推送

提交 .gitattributes 和所有变更文件，推送时 LFS 对象会自动上传到 LFS 存储

⚠ 如果文件已经被 git 普通跟踪并提交过，需要执行迁移步骤才能让 LFS 接管。upload 命令会自动处理此情况，但如果仓库历史中已有大文件，建议使用 git lfs migrate 清理历史
常见问题
FAQ
没有安装 Git LFS 可以使用吗？ ▼
可以。Git Tool 的大多数功能（初始化、提交、推送、克隆、拉取等）不依赖 Git LFS。只有在需要上传/管理大文件时才需要 LFS。如果未安装 LFS，工具会在需要时给出安装提示，不会影响其他操作。
如何修改大文件的判定阈值？ ▼
使用 config set 命令修改：
python3 main.py config set lfs_threshold_mb 100
这会将阈值改为 100MB，之后所有超过 100MB 的文件都会被视为大文件。
上传大文件到 GitHub 有什么限制？ ▼
GitHub 免费账户的 LFS 存储配额为 1GB/月，带宽为 1GB/月。如果文件非常大或数量较多，建议：
1. 使用 Git LFS 选择性跟踪，只跟踪必要的大文件
2. 考虑使用 GitHub 的付费计划获取更多配额
3. 对于特别大的文件（如数据集），考虑使用其他存储方案（如 Google Drive、S3）
如何全局安装，让 git-tool 命令随处可用？ ▼
在工具目录下执行：
pip3 install -e .
安装后即可在任何位置直接使用 git-tool 命令替代 python3 main.py。
upload 命令提示"远程仓库不存在"怎么办？ ▼
需要先添加远程仓库地址：
python3 main.py add-remote origin https://github.com/user/repo.git
然后再执行 upload 命令。
支持哪些 Git 托管平台？ ▼
支持所有基于 Git 的托管平台，包括 GitHub、GitLab、Gitee、Bitbucket、自建 Git 服务器等。只要能通过 git clone/push 访问的仓库都可以使用。
快速上手
典型工作流
从零开始，完整演示上传和下载项目的过程

场景一：新项目上传到远程仓库

完整流程
# 1. 进入项目目录 cd /path/to/my-project # 2. 初始化仓库 python3 main.py init # 3. 添加远程仓库 python3 main.py add-remote origin https://github.com/user/my-project.git # 4. 一键上传（自动处理大文件） python3 main.py upload -m "初始化项目"

场景二：下载并修改他人项目

完整流程
# 1. 克隆项目（自动拉取 LFS 大文件） python3 main.py download https://github.com/user/project.git ./project # 2. 进入项目，修改代码... cd project # 3. 拉取最新更新 python3 main.py pull # 4. 修改后上传 python3 main.py upload -m "修复 bug"

场景三：上传包含大文件的项目

完整流程
# 项目中包含 >200MB 的视频/数据文件 cd /path/to/big-data-project python3 main.py init python3 main.py add-remote origin https://github.com/user/big-data.git # 先扫描看看有哪些大文件 python3 main.py lfs scan # 一键上传，自动将大文件交由 LFS 管理 python3 main.py upload -m "添加数据集和模型"