📌 写在前面：
因为最近开始做一些AI和自己学科相关的项目，需要写大量的代码，因此想要将本地的项目文件夹与github远程仓库相关联，这样的好处是：

• 追踪一些修改
• 备份代码
• 将github作为中心，把本地和智算平台上的项目代码联动

以下是本人实践过程中的步骤和常见问题的整理，可以在以后使用时查阅，也适用于第一次使用github仓库的新手小白。

1. 本地文件夹与github仓库关联：

第一步就是需要把本地项目文件夹（以下用gitproj来代替项目名称）与远程github仓库关联，需要做的是：

1. 本地有一个名为"gitproj"的项目文件夹；
2. 在github网站上建立一个名字相同的仓库，即gitproj（不要选择自动生成readingme选项，否则之后git push可能会冲突，可关联完成后再写readme文件）。

代码：

cd gitproj #把路径改到当前项目文件夹 
git init   # 如果还没 init

#如果是第一次建立仓库，一般用：
git remote add origin <ssh克隆地址>
地址示例：git@github.com:username/gitproj.git
# 下面这个更稳定（可选）
# git remote set-url origin git@github.com:username/gitproj.git 

git add .
git commit -m "Initial commit"
git push -u origin main

以上代码的思路就是，git初始化当前项目文件夹 -> 把这个文件夹和远程的git仓库地址关联 -> 添加我的初始内容/改动 -> commit我的操作 -> push到远程仓库上。

commit说明示例：

以下是一些比较规范的commit说明的写法，可参考，让自己的更新说明更清晰：

chore: update .gitignore
chore: minor changes to README
fix: typo in <filename>
refactor: clean up forward function # 优化代码
docs: add more comments in <filename> #添加注释
debug: add print statements for debugging # 调试和debug
test: temporary test on xxx platform

2. git常用指令

• git status
  查看当前仓库状态，哪些文件有修改、有 staged 等。
• git log
  查看 commit 历史。
• git diff
  查看修改了哪些内容（未 add 的）。
• git diff --cached
  查看已经 add 了的内容有哪些修改。
• git gc --prune=now --aggressive
  清理无用的 git 对象，节省空间
• git reset --soft HEAD~1
  有时候 commit 写错 message，想改，可以用这个撤销最近一次 commit。

3. 撤销错误操作

• git restore <file>
  撤销对某个文件的修改，恢复到上次 commit。
• git reset HEAD <file>
  把 add 进 staging 的文件移除掉（但修改还保留）。

4. 重新设置远程地址

适用场景：如果平台统一要求用ssh或者https时需要切换就可以用git remote set-url origin

• git remote -v
  查看当前远程地址。
• git remote set-url origin <url>
  修改远程地址。

5. 忽略/不再追踪文件夹/文件的更新

这个很重要，有时候一个项目里的数据、模型和输出文件都很大，github不支持大文件（超过300MB）的push，如果只是管理代码，不希望上传这些大文件的话可以创建.gitigore文件，写明需要忽略的路径或者文件和文件类型：

1. 忽略（适用于还未被追踪和commit过）：

# 创建.gitignore文件
touch .gitignore

说明：打开该文件，在mac系统里，会有看不到.开头的隐藏文件的情况，此时按command+shift+.可以看到隐藏文件，相同操作再按一次可以重新隐藏。

.gitignore文件示例：

# 忽略文件夹
model/
outputs/

# Ignore macOS system files
.DS_Store

2. 不再追踪（适用于之前追踪过改变的文件/文件夹）：

git rm -r --cached .DS_Store #filename or file path

“剪掉”某个文件/文件夹的历史commit

适用于不小心commit/push了大文件，push过程卡住的情况：

# 安装 git-filter-repo，如果没有
pip install git-filter-repo

# 执行剪除大文件（比如 model 文件夹）
git filter-repo --path model/ --invert-paths

注意：这个操作会 修改历史，如果其他人 clone 了旧仓库，之后 push 会有冲突，需要大家 re-clone。

6. 备份repository

cd ..
cp -r gitproj gitproj_backup

7. 排查 push 不上去的问题

• git push --verbose
  显示更详细的 push 信息，排查问题。
• git remote show origin
  查看远程仓库信息。

8. 子模块（如果以后项目里引入子模块）

git submodule add <repo>
git submodule update --init --recursive

最后希望大家的项目开展都能顺利！🎉