Git-Bash向远程仓库上传文件详细教程

使用 Git Bash 向远程仓库上传文件：详细教程

适用系统：Windows 10 / Windows 11 适用平台：GitHub、Gitee、GitLab 及其他兼容 Git 的远程仓库 适用人群：第一次使用 Git Bash 上传项目的初学者

1. 先理解上传过程

使用 Git 上传文件并不是把文件直接拖到网站，而是依次完成下面几步：

常见命令与作用如下：

2. 前期准备

2.1 安装 Git for Windows

打开 Git Bash，输入以下命令检查是否安装成功：

git –version

如果显示类似下面的版本信息，说明安装成功：

git version 2.x.x.windows.x

实际版本号可能不同，不影响后续操作。

2.2 注册远程仓库平台账号

准备一个 GitHub、Gitee 或 GitLab 账号。本教程以 GitHub 风格的地址为例，其他平台的操作逻辑基本相同。

2.3 在网站上创建远程仓库

登录远程仓库平台并新建仓库，例如：

my-project

首次上传本地已有项目时，建议创建一个空仓库：

• 暂时不要自动生成 README.md；
• 暂时不要自动生成 .gitignore；
• 暂时不要选择 License。

这样可以避免本地仓库和远程仓库各自拥有独立提交记录，从而减少首次推送冲突。

创建完成后，页面通常会显示两种仓库地址：

HTTPS：https://github.com/用户名/仓库名.git
SSH：git@github.com:用户名/仓库名.git

例如：

https://github.com/zhangsan/my-project.git

或：

git@github.com:zhangsan/my-project.git

请使用平台页面实际显示的地址，不要直接照抄示例地址。

3. 首次配置 Git 用户信息

Git 会把用户名和邮箱记录到每一次提交中。打开 Git Bash，执行：

git config –global user.name "你的用户名"
git config –global user.email "你的邮箱"

例如：

git config –global user.name "Zhang San"
git config –global user.email "zhangsan@example.com"

查看配置是否成功：

git config –global –list

也可以分别查看：

git config –global user.name
git config –global user.email

说明：

• –global 表示该配置对当前 Windows 用户下的所有 Git 仓库生效；
• 用户名不必与网站登录名完全相同，但为了方便识别，建议保持一致；
• 如果希望 GitHub 正确关联提交记录，应使用 GitHub 账号中已验证的邮箱，或者使用平台提供的隐私邮箱。

如需让某一个项目使用单独的用户名和邮箱，可进入项目目录后去掉 –global：

git config user.name "项目专用用户名"
git config user.email "项目专用邮箱"

4. 选择远程连接方式

HTTPS 和 SSH 都可以上传文件，只需要选择其中一种。

初学者可以先使用 HTTPS；如果需要频繁操作仓库，建议配置 SSH。

5. 方法一：通过 HTTPS 上传本地已有文件夹

下面假设：

• 本地项目目录为 D:\\projects\\my-project；
• 远程空仓库地址为 https://github.com/zhangsan/my-project.git；
• 远程默认分支使用 main。

请把示例路径、用户名、仓库名替换成自己的实际信息。

5.1 进入项目目录

方法一：在 Windows 文件资源管理器中打开项目文件夹，在空白处单击鼠标右键，选择 Open Git Bash here。

方法二：打开 Git Bash 后使用 cd 命令进入项目目录：

cd /d/projects/my-project

Git Bash 中常见的 Windows 路径转换方式：

如果路径包含空格，需要使用引号：

cd "/d/My Projects/my-project"

查看当前所在目录：

pwd

查看当前目录中的文件：

ls

一定要确认自己位于正确的项目根目录，避免误把其他文件上传。

5.2 初始化本地仓库

git init

执行后，当前目录中会生成一个隐藏的 .git 文件夹。它用于保存仓库配置和版本历史，请不要随意删除或修改。

查看仓库状态：

git status

5.3 创建 .gitignore 文件

在执行 git add . 之前，建议先创建 .gitignore，排除不需要上传的文件。例如一个 Python 项目可以使用：

# Python 缓存
__pycache__/
*.py[cod]

# 虚拟环境
.venv/
venv/

# PyCharm
.idea/

# 环境变量与密钥
.env
*.key

# 日志和临时文件
*.log
*.tmp

其他常见忽略项：

# Node.js 依赖
node_modules/

# 构建输出
dist/
build/

# Windows 系统文件
Thumbs.db
Desktop.ini

注意：

• 不要上传密码、访问令牌、API Key、私钥、数据库口令等敏感信息；
• .gitignore 只能阻止尚未被 Git 跟踪的文件。如果敏感文件已经提交，仅把它加入 .gitignore 并不能从历史记录中删除。

5.4 将文件加入暂存区

添加当前目录下所有未被忽略的文件：

git add .

只添加某一个文件：

git add README.md

添加指定文件夹：

git add src/

文件名包含空格时使用引号：

git add "实验报告.md"

再次检查：

git status

位于 Changes to be committed 下方的文件将进入下一次提交。

如果误添加了某个文件，但还没有提交，可以将其移出暂存区：

git restore –staged 文件名

例如：

git restore –staged config.ini

5.5 提交到本地仓库

git commit -m "首次提交"

引号中的内容是提交说明，建议简洁描述本次修改，例如：

git commit -m "添加项目源代码和说明文档"

查看提交记录：

git log –oneline

git add 只是把修改放进暂存区；git commit 才会生成一条本地版本记录。只有提交过的内容才能正常推送。

5.6 将默认分支统一为 main

git branch -M main

查看当前分支：

git branch

分支名前带 * 表示当前所在分支，例如：

* main

5.7 关联远程仓库

git remote add origin https://github.com/zhangsan/my-project.git

请将地址替换为自己仓库页面上的 HTTPS 地址。

检查关联结果：

git remote -v

正常情况下会显示：

origin https://github.com/zhangsan/my-project.git (fetch)
origin https://github.com/zhangsan/my-project.git (push)

其中：

• origin 是远程仓库的本地别名；
• fetch 表示拉取地址；
• push 表示推送地址。

5.8 首次推送到远程仓库

git push -u origin main

参数含义：

• origin：远程仓库别名；
• main：要推送的本地分支；
• -u：将本地 main 与远程 origin/main 建立跟踪关系。

建立跟踪关系后，以后通常只需执行：

git push

推送成功后，刷新远程仓库网页，即可看到上传的文件和提交记录。

5.9 HTTPS 身份认证说明

首次推送时，Git 可能弹出浏览器登录窗口或凭据管理窗口，请按提示登录并授权。

如果终端要求输入用户名和密码：

• Username：输入远程平台用户名；
• Password：对于 GitHub，应输入个人访问令牌（Personal Access Token），而不是账号登录密码。

GitHub 官方说明：个人访问令牌可在命令行进行 HTTPS Git 操作时替代密码。令牌应像密码一样保管，不要写入代码、提交记录或聊天内容中。不同平台的认证页面、令牌名称和权限设置可能不同，请以对应平台的官方说明为准。

6. 方法二：通过 SSH 上传文件

使用 SSH 前，需要先在本机生成密钥，并把公钥添加到远程平台账号。

6.1 检查是否已有 SSH 密钥

ls -al ~/.ssh

常见密钥文件包括：

id_ed25519
id_ed25519.pub

其中：

• id_ed25519 是私钥，绝对不能上传或发给别人；
• id_ed25519.pub 是公钥，可以添加到 GitHub、Gitee 或 GitLab。

如果已有可用密钥，可以直接跳到“复制并添加 SSH 公钥”。如果不确定已有密钥是否正在被其他工作使用，建议不要覆盖它。

6.2 生成新的 SSH 密钥

ssh-keygen -t ed25519 -C "你的邮箱"

例如：

ssh-keygen -t ed25519 -C "zhangsan@example.com"

终端会询问保存位置：

Enter file in which to save the key

直接按 Enter，可保存到默认位置：

~/.ssh/id_ed25519

随后可为私钥设置密码短语（passphrase）。设置密码短语更安全，但以后使用密钥时可能需要输入该密码。

如果旧环境不支持 Ed25519，可按照平台官方说明改用 RSA；一般情况下优先使用 Ed25519。

6.3 启动 SSH Agent 并添加私钥

eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519

如果私钥设置了密码短语，按提示输入即可。

6.4 复制并添加 SSH 公钥

在 Git Bash 中复制公钥：

clip < ~/.ssh/id_ed25519.pub

也可以直接显示公钥：

cat ~/.ssh/id_ed25519.pub

然后进入远程平台账号设置，找到类似以下入口：

Settings → SSH and GPG keys → New SSH key

粘贴完整公钥并保存。公钥通常以 ssh-ed25519 开头。

6.5 测试 SSH 连接

GitHub：

ssh -T git@github.com

Gitee：

ssh -T git@gitee.com

GitLab：

ssh -T git@gitlab.com

第一次连接时可能出现主机真实性确认，并询问是否继续。确认域名无误后输入：

yes

如果输出认证成功或欢迎信息，说明 SSH 配置完成。

6.6 使用 SSH 地址关联并推送

如果尚未添加远程仓库：

git remote add origin git@github.com:zhangsan/my-project.git

如果之前已经添加了 HTTPS 地址，可改为 SSH 地址：

git remote set-url origin git@github.com:zhangsan/my-project.git

检查地址：

git remote -v

首次推送：

git push -u origin main

之后更新时使用：

git push

7. 推荐方案：远程仓库已有 README 等内容时

如果创建远程仓库时已经生成了 README.md、.gitignore 或 License，远程仓库就不是空仓库。此时最稳妥的方法是先克隆远程仓库，再把本地文件复制进去。

7.1 克隆远程仓库

先进入准备保存项目的上级目录：

cd /d/projects

使用 HTTPS 克隆：

git clone https://github.com/zhangsan/my-project.git

或使用 SSH 克隆：

git clone git@github.com:zhangsan/my-project.git

7.2 进入克隆后的仓库

cd my-project

7.3 复制项目文件

将原项目文件复制到这个克隆得到的 my-project 文件夹中。不要用原项目中的 .git 文件夹覆盖克隆仓库中的 .git 文件夹。

复制完成后执行：

git status
git add .
git commit -m "添加本地项目文件"
git push

这种方式会保留远程仓库已有的提交历史，也能避免两个独立仓库历史不相关的问题。

8. 如果本地已经初始化，而远程仓库也有提交

如果本地和远程已经分别产生提交，直接执行 git push 可能出现：

rejected
non-fast-forward

先确认本地修改已经提交，然后尝试获取远程更新并把本地提交变基到其后：

git pull –rebase origin main

如果没有冲突，再执行：

git push -u origin main

8.1 处理变基冲突

如果 Git 提示冲突：

命令示例：

git status
git add 冲突文件名
git rebase –continue

如有多个冲突，重复处理，直到变基完成，然后执行：

git push

如果不想继续本次变基，可以回到变基前的状态：

git rebase –abort

8.2 出现 refusing to merge unrelated histories

该错误说明本地仓库和远程仓库是分别初始化的，两边没有共同的提交起点。初学者建议备份本地文件后，采用第 7 节“先克隆、再复制文件”的方案。

如果明确需要合并两个独立历史，也可以执行：

git pull origin main –allow-unrelated-histories

之后处理可能出现的冲突、完成合并提交，再执行：

git push -u origin main

不要因为推送失败就直接使用强制推送。强制推送可能覆盖远程提交，尤其不适合多人协作仓库。

9. 后续更新文件的标准流程

首次上传成功后，每次修改代码或文档，通常按下面的流程操作。

9.1 进入项目目录

cd /d/projects/my-project

9.2 查看修改

git status

查看具体修改内容：

git diff

9.3 多人协作时先同步远程更新

git pull –rebase

9.4 添加修改

添加全部修改：

git add .

或只添加指定文件：

git add src/main.py README.md

9.5 提交修改

git commit -m "修复登录功能并更新说明文档"

9.6 推送到远程仓库

git push

可以把日常流程记成：

git status
git pull –rebase
git add .
git commit -m "本次修改说明"
git push

git pull –rebase 最好在工作区干净，或者本地修改已经提交后执行。团队项目还应遵守项目自己的分支和合并请求规范。

10. 上传、删除和重命名单个文件

10.1 上传单个文件

git add "实验结果.csv"
git commit -m "添加实验结果"
git push

10.2 删除远程仓库中的文件

git rm 不需要的文件.txt
git commit -m "删除无用文件"
git push

如果只想让 Git 停止跟踪文件，但想保留本地文件：

git rm –cached config.ini

然后把该文件加入 .gitignore，再提交并推送：

git add .gitignore
git commit -m "停止跟踪本地配置文件"
git push

10.3 重命名文件

git mv old-name.md new-name.md
git commit -m "重命名说明文档"
git push

11. 分支开发与上传

不建议在团队项目中直接修改 main。可以新建功能分支：

git switch -c feature-login

修改完成后：

git add .
git commit -m "完成登录功能"
git push -u origin feature-login

之后可在 GitHub、Gitee 或 GitLab 网页中创建 Pull Request 或 Merge Request，请团队成员审查并合并到主分支。

查看分支：

git branch

切换回主分支：

git switch main

12. 常见报错及解决方法

12.1 fatal: not a git repository

原因：当前目录不是 Git 仓库，或者进入了错误的目录。

解决方法：

pwd
ls -a

确认项目根目录中是否有 .git。如果是一个尚未初始化的新项目，执行：

git init

12.2 remote origin already exists

原因：名称为 origin 的远程仓库已经存在。

先查看现有地址：

git remote -v

如果地址不正确，直接修改：

git remote set-url origin 正确的仓库地址

例如：

git remote set-url origin https://github.com/zhangsan/my-project.git

12.3 src refspec main does not match any

常见原因：

• 还没有创建任何提交；
• 当前分支不叫 main；
• 提交失败或项目中没有可提交的文件。

检查：

git status
git branch
git log –oneline

通常可以依次执行：

git add .
git commit -m "首次提交"
git branch -M main
git push -u origin main

12.4 Authentication failed

可能原因：

• 用户名、令牌或登录授权不正确；
• 令牌已过期或没有仓库写入权限；
• Windows 中保存了旧凭据；
• 当前账号没有该仓库的写入权限；
• 组织仓库要求额外的单点登录授权。

解决思路：

12.5 Permission denied (publickey)

原因：SSH 公钥没有正确添加、私钥没有加载，或使用了错误账号的密钥。

检查公钥：

ls -al ~/.ssh

重新启动 Agent 并添加私钥：

eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519

测试连接：

ssh -T git@github.com

同时确认远程地址确实是 SSH 地址：

git remote -v

12.6 rejected 或 non-fast-forward

原因：远程分支中存在本地没有的提交。Git 为避免覆盖远程历史而拒绝推送。

先同步再推送：

git pull –rebase origin main
git push

如有冲突，按照第 8 节处理。

12.7 nothing to commit, working tree clean

这不是错误，表示当前没有尚未提交的修改。如果已经提交但尚未推送，可直接执行：

git push

12.8 LF will be replaced by CRLF

这通常是 Windows 与 Linux 换行符差异产生的提示，不一定表示操作失败。团队项目应优先遵守仓库已有的 .gitattributes 和换行符规范，不要因为看到该提示就反复修改文件。

12.9 文件太大导致推送失败

远程平台通常会限制单个文件或单次推送大小。大型模型、数据集、视频、压缩包等不适合直接放入普通 Git 历史。

可选做法：

• 使用 Git LFS 管理确实需要版本控制的大文件；
• 把数据集或模型保存在对象存储、网盘或制品仓库；
• 在 README 中提供下载地址和校验信息；
• 使用 .gitignore 排除生成文件和大型中间文件。

13. 常用检查和维护命令

13.1 查看状态

git status

13.2 查看简洁提交历史

git log –oneline –graph –decorate –all

13.3 查看远程仓库地址

git remote -v

13.4 查看当前分支

git branch –show-current

13.5 查看尚未暂存的改动

git diff

13.6 查看已经暂存的改动

git diff –staged

13.7 撤销暂存

git restore –staged 文件名

13.8 放弃尚未提交的文件修改

git restore 文件名

警告：该命令会丢弃该文件尚未提交的本地修改。执行前确认这些修改不再需要，必要时先备份。

13.9 修改尚未推送的最近一次提交说明

git commit –amend -m "新的提交说明"

如果提交已经推送到共享仓库，不要随意改写历史。

14. 完整命令示例

14.1 本地已有项目，远程是空仓库

# 进入项目目录
cd /d/projects/my-project

# 初始化仓库
git init

# 检查文件，并确保已经正确配置 .gitignore
git status

# 添加文件
git add .

# 创建本地提交
git commit -m "首次提交"

# 将主分支命名为 main
git branch -M main

# 关联远程仓库
git remote add origin https://github.com/zhangsan/my-project.git

# 检查远程地址
git remote -v

# 首次推送并建立跟踪关系
git push -u origin main

14.2 远程仓库已有内容

# 进入项目的上级目录
cd /d/projects

# 克隆远程仓库
git clone https://github.com/zhangsan/my-project.git

# 进入克隆目录
cd my-project

# 此时把本地项目文件复制进来，然后执行
git status
git add .
git commit -m "添加项目文件"
git push

14.3 日常更新

cd /d/projects/my-project
git status
git pull –rebase
git add .
git commit -m "更新项目内容"
git push

15. 操作前检查清单

首次上传前逐项检查：

• Git 已正确安装，git –version 能显示版本号；
• 已配置 user.name 和 user.email；
• 当前 Git Bash 位于正确的项目根目录；
• .gitignore 已排除虚拟环境、依赖、缓存和生成文件；
• 没有上传密码、令牌、私钥或其他敏感信息；
• 远程仓库地址属于正确的账号和仓库；
• 已通过 git status 检查待提交文件；
• 已成功执行 git commit；
• 当前分支名与推送命令中的分支名一致；
• 推送后已在网页端核对文件和提交记录。

16. 最容易记住的 Git 上传口诀

首次上传到空远程仓库：

进入目录 → init → add → commit → branch → remote → push

对应命令：

git init
git add .
git commit -m "首次提交"
git branch -M main
git remote add origin 远程仓库地址
git push -u origin main

后续更新：

查看状态 → 同步远程 → 添加修改 → 提交修改 → 推送远程

对应命令：

git status
git pull –rebase
git add .
git commit -m "修改说明"
git push

17. 官方参考资料

• Git 官方文档：git push
• Git 官方文档：git pull
• GitHub：将提交推送到远程仓库
• GitHub：管理个人访问令牌
• GitHub：使用 SSH 连接
• GitHub：处理 non-fast-forward 错误

总结

使用 Git Bash 向远程仓库上传文件的核心是：先通过 git add 和 git commit 在本地形成提交，再通过 git push 把提交发送到远程仓库。首次操作时，要特别注意当前目录、.gitignore、分支名称、远程地址和认证方式。远程仓库如果已有内容，优先采用“先克隆、再复制文件、最后提交和推送”的方式，可以显著减少冲突。