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

千光希

于 2025-06-30 12:16:30 发布

阅读量2.7k

点赞数 41

CC 4.0 BY-SA版权

文章标签： Git新手 git命令 git上传文件 Pycharm中使用git

本文链接：https://blog.csdn.net/weixin_43682905/article/details/149019778

一、背景信息

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

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

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

二、上传操作

2.1 目标读者

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

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

2.2 前提准备

已安装 Git 并配置好用户信息（git config --global user.name "Your Name" 和 git config --global user.email "your.email@example.com"）。
已拥有 GitHub 账号。

2.3 整个流程概览

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

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

第一步：初始化本地 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 上为你本地的项目创建一个对应的远程仓库。

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

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

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

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

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

请将你的GitHub用户名替换为你实际的 GitHub 用户名。
请将你的仓库名替换为你刚刚在 GitHub 上创建的仓库名称。
在你的本地 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。这里再次强调处理方法：

确认本地分支： git branch
确认远程仓库别名和地址： git remote -v
方法一：推送到不同名称的远程分支
如果本地是 master，想推到远程 main，且远程别名是 origin：
Generated bash
```
      git push -u origin master:main
    
```
方法二：重命名本地分支后再推送 (推荐)
如果本地是 master，想统一为 main 并推送到远程 main：
Generated bash
```
      git branch -M main # M 参数表示即使分支已存在也强制重命名
git push -u origin main
    
```
IGNORE_WHEN_COPYING_START

content_copydownload
Use code with caution. Bash
IGNORE_WHEN_COPYING_END

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

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

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

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

安装 git-filter-repo: 你可能需要使用 pip 安装 Python 包管理器来安装它。
Generated bash
```
      pip install git-filter-repo
    
```
或者通过其他系统包管理器安装。
清理历史中的文件/目录:
进入你的项目目录，执行清理命令。例如，如果你想删除历史中所有 dist/ 目录的痕迹：
Generated bash
```
      # 重要：请先备份你的仓库！
git filter-repo --path dist/ --invert-paths --force
    
```
- --path dist/：指定要操作的路径。
- --invert-paths：表示保留除了指定路径之外的所有内容（即删除指定路径）。
- --force：强制执行。
如果你想删除一个特定的文件，例如 large_file.zip：
```
      # 重要：请先备份你的仓库！
git filter-repo --path large_file.zip --invert-paths --force
    
```
更详细的用法请参考 git-filter-repo 的文档。
创建或更新 .gitignore 文件:
这是最重要的一步，确保你将来不会再意外地将这些不应跟踪的文件添加到 Git。在你的项目根目录下创建或编辑 .gitignore 文件，添加需要忽略的文件或目录模式。
例如，忽略 dist/ 目录：
```
      # .gitignore 文件内容
dist/
*.log
    
```
将 .gitignore 文件添加到暂存区并提交：
```
      git add .gitignore
git commit -m "Add .gitignore"
    
```
清理本地旧对象:
历史被改写后，本地仓库中可能还保留着旧的对象。运行垃圾回收来清理它们：
```
      git gc --prune=now --aggressive
    
```
强制推送到远程仓库:
因为本地的历史已经被改写，与远程仓库的历史不兼容了，你必须使用强制推送来覆盖远程仓库的历史。
Generated bash
```
      # 重要：强制推送会覆盖远程仓库的历史，请谨慎使用！
# 如果是多人协作项目，请务必提前告知团队成员并协调操作。
git push --force origin main # 将 main 替换为你实际的主分支名称
    
```
完成这些步骤后，你的远程仓库历史中就不会包含那些大文件了。

五、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 等。