Git 入门：第一次将本地项目上传到 GitHub 仓库详细教程

一、背景信息

        作为开发者，将本地代码托管到远程仓库（如 GitHub、Gitee 等）是一个基本且重要的技能。这不仅方便代码备份，还能轻松进行版本控制和团队协作。

        本文将详细介绍如何将你已经存在的本地项目，第一次完整地上传到 GitHub 上的一个新的空白仓库。这与 git clone（从远程下载仓库）的操作是相反的。

        我们将一步步走过 Git 命令的操作流程，并附带一些常见问题的处理和进阶技巧。

二、上传操作

2.1 目标读者

        刚开始使用 Git，不熟悉命令行的开发者。

        想将本地已有项目托管到 GitHub 的用户。

2.2 前提准备

1. 已安装 Git 并配置好用户信息（git config --global user.name "Your Name" 和 git config --global user.email "[email protected]"）。
2. 已拥有 GitHub 账号。

2.3 整个流程概览

1. 初始化本地 Git 仓库。
2. 添加并提交本地代码。
3. 在 GitHub 创建一个空白远程仓库。
4. 关联本地仓库与远程仓库。
5. 将本地代码推送到远程仓库。

        接下来，我们一步步进行操作。

第一步：初始化本地 Git 仓库

        首先，你需要进入你的项目目录，这个目录是你实际项目内，而不是该项目再其文件夹下的根目录，然后在这个目录下初始化一个 Git 仓库。

        打开命令行终端（如 Git Bash, CMD, PowerShell 或其他终端），使用 cd 命令进入你的项目根目录。

示例：

cd /path/to/your/project # 将 /path/to/your/project 替换为你的实际项目路径 # 例如：cd E:\A-Auto-yu\AUTO-yu

        确认你在项目目录下后，执行初始化命令：

git init

        这个命令会在你的项目目录下创建一个隐藏的 .git 文件夹，标志着你的项目现在是一个 Git 仓库了。

第二步：添加所有文件到暂存区

        将你项目中的所有文件（除了你不想跟踪的文件，例如编译生成物、日志等，这些通常通过 .gitignore 文件来忽略，我们后面会提到）添加到 Git 的暂存区。

git add .

        这里的“.” 表示当前目录下的所有文件和子目录。

注意： 执行 git add . 后，Git 会开始跟踪你的文件。你可以使用 git status 命令查看哪些文件被添加到了暂存区（显示为绿色）。

第三步：提交更改

        将暂存区中的文件提交到本地仓库的历史记录中。每次提交都代表项目的一个版本。

git commit -m "Initial commit"

• commit 是提交命令。
• -m 参数后面跟着的是本次提交的说明信息。请将 "Initial commit" 替换为你本次提交的简短描述，例如 "首次提交项目代码"。
• 建议提交信息简明扼要，说明本次提交做了什么。

        现在你的本地项目已经有了一个 Git 仓库，并且你的代码已经被添加并提交到了这个本地仓库中。

第四步：在 GitHub 上创建一个新的空白仓库

接下来，我们需要在 GitHub 上为你本地的项目创建一个对应的远程仓库。

1. 登录 GitHub 账号。
2. Repository name (仓库名): 给你的仓库起一个名字。这个名字通常与你的本地项目名相关，例如 AUTO-yu-Automation 或 MyAutomationScripts。
3. 选择 Public (公开) 或 Private (私有)，根据你的需求决定。
4. 非常重要： 不要勾选 "Add a README file", "Add .gitignore", 或 "Choose a license"。因为你已经有本地代码了，这些文件如果你需要可以在本地创建并一起上传。我们现在需要一个完全空白的仓库来接收你的本地代码。

点击绿色的 "Create repository" 按钮。

点击页面右上角的 "+" 号，选择 "New repository"。

创建成功后，GitHub 会显示一个页面，告诉你如何将本地仓库连接到这个新的远程仓库。这个页面上的信息非常重要，我们接下来就会用到它。

第五步：关联本地仓库与 GitHub 上的仓库

        在 GitHub 创建完空白仓库后显示的页面上，你会找到一串指令，告诉你如何将一个已有的本地仓库推送到这个远程仓库。找到类似下面这样的命令：

git remote add origin https://github.com/你的GitHub用户名/你的仓库名.git

1. 请将 你的GitHub用户名 替换为你实际的 GitHub 用户名。
2. 请将 你的仓库名 替换为你刚刚在 GitHub 上创建的仓库名称。
3. 在你的本地 Git 命令行终端中（确保你仍然在你的项目目录下，即 E:\A-Auto-yu\AUTO-yu 或 /path/to/your/project），执行这行命令。

# 示例（请替换为你的实际信息）： git remote add origin https://github.com/your_username/my-automation-scripts.git

• git remote add 命令用于添加一个远程仓库。
• origin 是给这个远程仓库起的一个别名。origin 是一个常用的约定俗成的名字，代表主要的远程仓库。
• 后面的 URL 是你远程仓库的地址。

        你可以通过 git remote -v 命令来查看你当前仓库关联的远程仓库信息：

git remote -v

        它会显示你刚刚添加的 origin 远程仓库的抓取 (fetch) 和推送 (push) 地址。

第六步：将本地代码推送到 GitHub 仓库

        现在，你的本地仓库已经知道远程仓库在哪里了（通过 origin 别名）。接下来就是将本地的代码推送到远程仓库。

        通常，新创建的 GitHub 仓库默认的主分支是 main。你的本地仓库在 git init 后，默认的主分支通常是 master 或 main（新版 Git 默认 main）。

首先，确认你的本地主分支名称：

git branch

        带有 * 号的就是你当前所在的本地分支。如果显示 * main，则你的本地主分支是 main；如果显示 * master，则你的本地主分支是 master。

情况一：本地分支是 main，远程默认分支也是 main (推荐，新版Git默认)

git push -u origin main

情况二：本地分支是 master，远程默认分支是 main (旧版Git常见)

你需要指定将本地的 master 分支推送到远程的 main 分支：

git push -u origin master:main

或者，你可以先将本地的 master 分支重命名为 main，然后再执行推送到 main 的命令：

git branch -M main # 将当前本地分支重命名为 main git push -u origin main # 推送到远程的 main 分支

推荐使用第二种方法，统一本地和远程的主分支名称。

三、命令解释

• git push：执行推送操作。
• -u：这是 --set-upstream 的缩写。这个参数在第一次推送时使用，它会设置本地分支的上游分支。设置后，以后你在这个分支上就可以直接使用 git push 和 git pull 命令，而不需要指定 origin main 或 origin master。
• origin：指定要推送的远程仓库别名（我们之前设置的）。
• main 或 master：指定要推送的本地分支名称。
• master:main：表示将本地的 master 分支推送到远程的 main 分支。

        执行 git push 命令后，Git 会将你的本地提交上传到 GitHub 仓库。你可能需要输入你的 GitHub 用户名和密码（或者使用 Personal Access Token，更安全）。

总结核心操作

• git clone [url]：从远程仓库下载代码到本地。
• git init + git add + git commit + git remote add + git push：将本地代码上传到远程空白仓库。

补充：处理分支名称差异

正如上面提到的，有时你的本地默认分支是 master，而 GitHub 新建仓库默认分支是 main。这里再次强调处理方法：

1. 确认本地分支： git branch
2. 确认远程仓库别名和地址： git remote -v

方法二：重命名本地分支后再推送 (推荐)
如果本地是 master，想统一为 main 并推送到远程 main：Generated bash

git branch -M main # M 参数表示即使分支已存在也强制重命名 git push -u origin main

IGNORE_WHEN_COPYING_STARTcontent_copydownloadUse code with caution. BashIGNORE_WHEN_COPYING_END

方法一：推送到不同名称的远程分支
如果本地是 master，想推到远程 main，且远程别名是 origin：Generated bash

git push -u origin master:main

四、进阶：清理 Git 历史中的大文件（如果需要）

        有时在项目初期，可能会不小心将一些大型文件（如数据库文件、编译输出、大媒体文件等）添加到 Git 历史中。即使后来删除了文件并提交，这些大文件仍然存在于 Git 的历史记录里，导致仓库体积庞大。

重要警告： 清理 Git 历史是一个破坏性操作，会改写提交历史。务必提前备份你的仓库！

使用 git-filter-repo 工具是目前推荐的清理方式，它比旧的 git filter-branch 更快更安全。

• --path dist/：指定要操作的路径。
• --invert-paths：表示保留除了指定路径之外的所有内容（即删除指定路径）。
• --force：强制执行。

强制推送到远程仓库:
因为本地的历史已经被改写，与远程仓库的历史不兼容了，你必须使用强制推送来覆盖远程仓库的历史。Generated bash

# 重要：强制推送会覆盖远程仓库的历史，请谨慎使用！ # 如果是多人协作项目，请务必提前告知团队成员并协调操作。 git push --force origin main # 将 main 替换为你实际的主分支名称

完成这些步骤后，你的远程仓库历史中就不会包含那些大文件了。

清理本地旧对象:
历史被改写后，本地仓库中可能还保留着旧的对象。运行垃圾回收来清理它们： 

git gc --prune=now --aggressive

创建或更新 .gitignore 文件:
这是最重要的一步，确保你将来不会再意外地将这些不应跟踪的文件添加到 Git。在你的项目根目录下创建或编辑 .gitignore 文件，添加需要忽略的文件或目录模式。
例如，忽略 dist/ 目录：

# .gitignore 文件内容 dist/ *.log

将 .gitignore 文件添加到暂存区并提交：

git add .gitignore git commit -m "Add .gitignore"

清理历史中的文件/目录:
进入你的项目目录，执行清理命令。例如，如果你想删除历史中所有 dist/ 目录的痕迹：Generated bash

# 重要：请先备份你的仓库！ git filter-repo --path dist/ --invert-paths --force

如果你想删除一个特定的文件，例如 large_file.zip：

# 重要：请先备份你的仓库！ git filter-repo --path large_file.zip --invert-paths --force

更详细的用法请参考 git-filter-repo 的文档。

安装 git-filter-repo: 你可能需要使用 pip 安装 Python 包管理器来安装它。Generated bash

pip install git-filter-repo

或者通过其他系统包管理器安装。

五、Git 常用命令别名 (Aliases)

        为了提高效率，你可以为常用的 Git 命令设置别名。将以下配置添加到你的全局 Git 配置中（可以通过编辑 ~/.gitconfig 文件或直接使用命令行）：

git config --global alias.st status # git st == git status (查看状态) git config --global alias.co checkout # git co == git checkout (切换分支等) git config --global alias.br branch # git br == git branch (查看分支) git config --global alias.ci commit # git ci == git commit (提交) git config --global alias.ciam "commit --amend" # git ciam == git commit --amend (修改上一次提交) git config --global alias.di diff # git di == git diff (查看差异) git config --global alias.dc diff --cached # git dc == git diff --cached (查看暂存区与上一次提交的差异) git config --global alias.unstage "reset HEAD --" # git unstage <file> == git reset HEAD -- <file> (取消暂存文件) git config --global alias.last "log -1 HEAD" # git last == git log -1 HEAD (查看最近一次提交信息) git config --global alias.ll "log --pretty=oneline --abbrev-commit --" # git ll == git log --pretty=oneline --abbrev-commit -- (简洁查看提交历史) git config --global alias.lol "log --graph --decorate --pretty=oneline --abbrev-commit" # git lol == git log --graph --decorate --pretty=oneline --abbrev-commit (图形化简洁查看提交历史) git config --global alias.pom "push origin main" # git pom == git push origin main (推送到 origin main 分支) git config --global alias.plom "pull origin main" # git plom == git pull origin main (从 origin main 分支拉取)

        设置完成后，你就可以使用 git st 代替 git status，git ci 代替 git commit 等。

六、在 PyCharm 中进行 Git 操作

        如果你使用 PyCharm 等集成开发环境 (IDE)，通常它们都内置了 Git 支持，可以图形化地完成大多数 Git 操作。

        在 PyCharm 中，常用的 Git 操作快捷键：

• Ctrl + V (或 `Alt + ``)： 打开 VCS Operations Popup，可以进行各种版本控制操作。
• Ctrl + K： 打开 Commit Tool Window，用于查看文件变更、暂存、编写提交信息和提交。
• Ctrl + Shift + K： 推送 (Push) 更改到远程仓库。
• Ctrl + T： 拉取 (Pull) 远程仓库的最新代码。

        使用 IDE 可以更直观地看到文件状态、历史记录、分支等信息，对于初学者来说也是一个很好的选择。

总结

        将本地项目第一次上传到 GitHub 的基本流程是：

1. git init：初始化本地仓库。
2. git add .：添加所有文件到暂存区。
3. git commit -m "..."：提交更改到本地仓库。
4. 在 GitHub 创建一个空白远程仓库。
5. git remote add origin [url]：关联本地与远程仓库。
6. git push -u origin main (或 master:main)：将本地代码推送到远程仓库。

        掌握这个流程是使用 Git 进行版本控制的第一步。随着你的熟练度提升，你会接触到更多 Git 的强大功能，如分支管理、合并、标签等。

希望这篇详细教程对你有所帮助！如果在操作过程中遇到任何问题，可以在评论区留言交流。