Git 同步本地项目到 Gitee 仓库

作为新手，首次使用 Git 将本地项目同步到 Gitee 仓库时，踩了不少小坑，耗时许久才完成全程操作。整理这份实操指南，记录完整流程与避坑要点，希望能帮到和我一样刚入门的朋友，避免重复踩坑。

前置准备

• 本地已安装 Git（安装后可通过 Git Bash/ PowerShell 验证）；

• Gitee 账号已注册，并创建好空仓库（无需初始化任何文件）；

• 本地项目已准备就绪（本文以 Windows 系统下的项目为例）。

完整操作流程

步骤 1：Git 全局配置（首次安装必做）

打开 Git Bash（或 PowerShell），执行以下命令配置全局用户名和邮箱（关联 Gitee 账号，信息可自定义，无需与 Gitee 账号完全一致）：

git config --global user.name "自定义用户名"
git config --global user.email "自定义邮箱"

配置完成后无需验证，后续提交代码时会自动关联该信息。

步骤 2：进入本地项目目录

通过命令切换到本地项目所在目录（本文示例目录为 D:\Program Files\project-name，实际替换为自己的项目路径即可）：

# Windows 系统切换路径，注意空格转义（两种方式均可）
cd "D:/Program Files/project-name"
# 或
cd /d/Program\ Files/project-name

# 可选：验证路径是否正确
pwd

提示：若执行命令时出现权限提示，建议将项目迁移到非系统目录（如 D:\project-name），避免系统目录权限限制。

步骤 3：初始化本地 Git 仓库

在项目目录下，执行初始化命令，创建本地 Git 仓库（会生成隐藏的 .git 文件夹，用于管理版本信息）：

git init

执行成功后，会提示“Initialized empty Git repository in …”，表示本地仓库创建完成。

步骤 4：添加文件到暂存区

将项目目录下所有文件添加到 Git 暂存区，准备提交到本地仓库：

git add .

补充：若有无需提交的文件（如缓存、日志），可创建 .gitignore 文件进行排除，新手可暂时跳过此步骤。

可能遇到的警告：warning: LF will be replaced by CRLF，这是 Windows 与类 Unix 系统（Linux/Mac）换行符差异导致的（LF 是类 Unix 换行符，CRLF 是 Windows 换行符），虽不影响后续操作，但长期跨平台协作可能出现文件格式混乱，建议同步解决，具体方法如下：

# 全局配置 Git 自动处理换行符（Windows 系统推荐）
git config --global core.autocrlf true
# 可选：禁止 Git 对二进制文件（图片、字体等）做换行符转换，避免文件损坏
git config --global core.safecrlf true

配置完成后，后续提交文件将自动适配系统换行符，警告不再出现；若已出现警告，可执行 git rm --cached -r . 清除缓存，再重新执行 git add . 即可。

步骤 5：提交暂存区文件到本地仓库

给本次提交添加备注（描述提交内容，必填，建议清晰易懂），完成本地提交：

git commit -m "初始化提交：添加项目所有核心文件"

提交成功后，会显示提交的文件数量、修改信息等，此时本地仓库已记录项目内容。

步骤 6：关联 Gitee 远程仓库

1. 登录 Gitee，打开创建好的空仓库，复制仓库的 HTTPS 地址（推荐新手使用 HTTPS 方式，无需配置 SSH 密钥）；

2. 回到命令行，执行以下命令关联远程仓库（替换为自己的 Gitee 仓库 HTTPS 地址）：

git remote add origin https://gitee.com/用户名/仓库名.git

若执行时提示 remote origin already exists，说明已关联过远程仓库，执行 git remote rm origin 删除原有关联后，再重新执行上述命令。

步骤 7：推送到 Gitee 远程仓库

首次推送需关联本地分支与远程分支，执行以下命令（默认分支为 master，若 Gitee 仓库默认分支为 main，替换为 main 即可）：

git push -u origin master

执行后会弹出输入框，输入 Gitee 用户名和私人访问令牌（Gitee 已逐步停用密码认证，推荐使用访问令牌）：

• 私人访问令牌获取：Gitee → 个人设置 → 私人令牌 → 生成新令牌，勾选仓库相关权限，复制令牌（仅显示一次，建议保存）。

步骤 8：验证推送结果

推送成功后，命令行会显示文件上传进度、成功提示，此时登录 Gitee 仓库页面，刷新即可看到本地项目的所有核心文件，推送完成！

常见问题与避坑要点

1. 错误 src refspec main does not match any：本地仓库无提交记录，需先执行 git add . 和 git commit -m "备注" 完成本地提交，再执行推送命令。

2. 错误 Permission denied (publickey)：若使用 SSH 方式关联仓库，需先配置 SSH 密钥（新手建议直接用 HTTPS 方式，更简单）。

3. 换行符警告：无需处理，若想彻底解决，可配置 Git 全局换行符规则（具体可参考相关教程）。

4. 系统目录权限问题：避免将项目放在 Program Files 等系统目录，迁移到普通目录可解决权限不足问题。

后续常用操作

推送成功后，后续修改本地项目文件，只需执行以下3步即可同步到远程仓库：

git add .  # 添加修改的文件
git commit -m "修改备注：描述具体修改内容"  # 提交到本地仓库
git push  # 推送到远程仓库（已关联分支，无需额外参数）

总结

作为新手，首次操作难免遇到各种小问题，但只要按照流程一步步执行，避开权限、分支、认证这几个坑，就能顺利完成本地项目到 Gitee 仓库的同步。Git 版本控制是开发者必备技能，后续可逐步熟悉更多命令，提升效率。