版本控制 on Liangweidong's blog

Git 四大区与 Shelve 搁置：从入门到 IDEA 实战

Tue, 15 Sep 2015 00:00:00 +0800

Git 四大区

Git 内部有 4 个工作区域：

区域	英文	说明
工作区	Working Directory	本地写代码的目录
暂存区	Staging Area / Index	`git add` 后的"准备提交"区
本地仓库	Local Repository	`git commit` 后的本地历史
远程仓库	Remote Repository	`git push` 后的云端历史

1
2
3
4


工作区（写代码）
 → git add → 暂存区（准备提交） git stash 隐藏更改
 → git commit → 本地仓库（本地保存）
 → git push → 远程仓库（云端保存）

git stash 是隐藏工作区的更改到栈里（不提交到任何区），方便你拉最新代码或者切换任务。

git stash：紧急任务切换

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


# 当前正在改功能 A，写了一半
# 突然来了 bugB 要修

# 1. 把功能 A 暂存起来
git stash

# 2. 拉最新代码
git pull origin master

# 3. 切到 bug 分支修
git checkout -b fix-bugB
# ... 改完、commit、push、merge ...

# 4. 切回功能 A 分支
git checkout feature-A

# 5. 恢复暂存
git stash pop

# 6. 继续功能 A 开发

stash 是栈结构，支持多个：

1
2
3
4
5


git stash # 暂存当前
git stash list # 查看所有 stash
git stash apply stash@{0} # 应用指定 stash
git stash drop stash@{0} # 删除指定 stash
git stash pop # 应用并删除最近一个

git restore：撤销本地的编辑

1
2
3
4
5
6
7
8


# 撤销工作区的修改（未 add）
git restore 文件1 文件2

# 撤销暂存（已 add，但未 commit）
git restore --staged 文件1 文件2

# 撤销工作区 + 暂存
git restore --staged --worktree 文件1

IDEA 中的回滚：

VCS → Git → Restore File：相当于 git restore
Local History → Show History：IDEA 自动保存的本地历史
VCS → Git → Reset HEAD：回滚所有未提交修改

IDEA 的 reset 默认不删除"已提交"的文件副本，所以回滚不删除文件——已跟踪的文件从绿变红。

git HEAD：指针机制

HEAD 是当前分支最新提交的"指针"。

HEAD^：上一个提交（HEAD~1）
HEAD^^：上上一个（HEAD~2）
HEAD@{2}：reflog 中第 3 个 HEAD 位置（用于找回 reset 掉的 commit）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


# 查看 reflog
git reflog

# 把 HEAD 切到上一个提交
git checkout HEAD^

# 恢复误删的分支
git reflog
# 找到 commit SHA
git checkout -b recovered-branch <SHA>

git restore vs git checkout vs git reset 三者区别

命令	作用
`git restore <file>`	撤销工作区/暂存区的修改（Git 2.23+ 新命令）
`git checkout -- <file>`	同上（旧语法）
`git reset --soft HEAD^`	撤销 commit，保留暂存
`git reset --mixed HEAD^`	撤销 commit + 暂存，保留工作区
`git reset --hard HEAD^`	撤销 commit + 暂存 + 工作区（危险，慎用）

IDEA 的 Shelve 搁置

什么是 Shelve

IDEA 的 Shelve（搁置） 是 JetBrains IDE 独有的功能，定位：

【任务切换神器】 不是为了拉代码，是为了 把写一半的功能收起来，去干别的事。

它像一个临时的、私有的、微型补丁分支——不污染 git 历史，跨分支切换时不被带走。

使用场景

1
2
3
4
5
6
7
8


正在写【功能 A】，写了一半
突然来了【紧急 bugB】要修！
不想提交 A，也不想删 A

→ 把 A 搁置（Shelve）起来
→ 工作区变干净
→ 去修 bugB
→ 修完把 A 恢复回来继续

操作步骤

Git → Uncommitted Changes → Shelve Changes…
命名（建议"功能A-2026-06-04"）
工作区立刻变干净
切到 bugB 分支修
修完提交
Git → Uncommitted Changes → Unshelve… 选之前搁置的名字
恢复继续功能 A

与 git stash 的区别：Shelve 是 IDE 本地的，跨电脑不共享；stash 是 git 仓库级别的，commit 后可推送。

git-crypt：透明加密

团队项目经常需要提交敏感配置（.env、数据库密码），但又怕直接 push 到公网。git-crypt 是 Git 的透明加密插件：

文件本地是明文
git push 后云端是密文
团队成员对称加密：每个有 GPG key 的人都能解密

1
2
3
4
5
6
7
8


# Linux 下载
wget https://github.com/AGWA/git-crypt/releases/download/0.7.0/git-crypt-0.7.0-linux-x86_64

# Windows 下载
wget https://github.com/AGWA/git-crypt/releases/download/0.7.0/git-crypt-0.7.0-x86_64.exe

# 放到 PATH
mv git-crypt-0.7.0-x86_64 /usr/local/bin/git-crypt

配置 .gitattributes

1
2
3
4
5


# .gitattributes
.env filter=git-crypt diff=git-crypt
config/prod.yaml filter=git-crypt diff=git-crypt
*.key filter=git-crypt diff=git-crypt
*.pem filter=git-crypt diff=git-crypt

初始化

1
2
3


git-crypt init
git add .gitattributes
git commit -m "Add git-crypt config"

添加 GPG 协作者

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


# 协作者生成 GPG key
gpg --gen-key
# 上传公钥到 keyserver
gpg --keyserver keys.openpgp.org --send-keys <KEY_ID>

# 信任他
git-crypt add-gpg-user <GPG_USER_ID>

# 协作者 clone 后 unlock
git-crypt unlock

常用命令速查

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24


# 远程分支
git branch -r

# 检出远程分支
git checkout release_V3.1.4

# 关联分支
git branch --set-upstream-to=origin/master master

# 查看单个文件的历史
git log -p -- path/to/file

# 暂存部分文件
git add -p
# y/n/q/a/d 等交互式命令

# 撤销合并
git revert -m 1 <merge_commit_sha>

# 修改最后一次 commit
git commit --amend

# 改作者邮箱（全局）
git filter-branch --env-filter 'GIT_AUTHOR_EMAIL=xxx'

下一步

想用 GitHub Actions 自动化 CI，看 2017-12-08《K8s Ingress 实战》
想用 monorepo 工具（pnpm + turbo）管理多项目，看 2020-04-15《FSS 全栈脚手架》

参考资料

Pro Git 简体中文：https://git-scm.com/book/zh/v2
git-crypt：https://github.com/AGWA/git-crypt
IDEA Shelve 文档：https://www.jetbrains.com/help/idea/shelving-and-unshelving-changes.html

Git 与版本控制实战：从入门到 GitHub 高级搜索

Sat, 15 Nov 2014 00:00:00 +0800

一、Git 在 2014 的地位

2014 年的 Git 已经基本统一了分布式版本控制市场。GitHub 2014 年 1 月用户突破 1000 万（2008 年成立，2013 年用户 300 万），国内 GitCafe、coding.net 同期兴起。本文整理 Git 从入门到 GitHub 高级搜索的完整工作流。

阅读建议：本文面向用过 SVN 切换到 Git 的开发者，重点在Git 概念 + 实战命令。

二、Git 安装与初始配置

2.1 安装

Windows：https://git-scm.com/download/win（Git for Windows，带 Git Bash）
macOS：brew install git（或装 Xcode Command Line Tools）
Linux：apt install git / yum install git

2.2 全局配置

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


# 必填：用户名 + 邮箱
git config --global user.name "Your Name"
git config --global user.email "you@example.com"

# 推荐：默认编辑器
git config --global core.editor "vim"

# 推荐：默认分支名（Git 2.28+）
git config --global init.defaultBranch main

# 推荐：换行符处理（Windows 推荐）
git config --global core.autocrlf true

2.3 SSH 密钥登录 GitHub

生成密钥对：

1
2
3


ssh-keygen -t ed25519 -C "you@example.com"
# 或传统 RSA
ssh-keygen -t rsa -b 4096 -C "you@example.com"

复制公钥：

1
2
3
4
5
6


# Windows (Git Bash)
clip < ~/.ssh/id_ed25519.pub
# macOS
pbcopy < ~/.ssh/id_ed25519.pub
# Linux
cat ~/.ssh/id_ed25519.pub

GitHub Settings → SSH and GPG keys → New SSH key，粘贴。

验证：

1
2


ssh -T git@github.com
# 输出：Hi <username>! You've successfully authenticated...

2.4 HTTPS + Token 登录（GitHub 2021+ 强制）

2021-08 GitHub 取消密码推送，必须用 Personal Access Token (PAT)：

GitHub → Settings → Developer settings → Personal access tokens → Tokens (classic) → Generate new token
勾选 repo、gist、read:org、workflow
复制 token（只显示一次）

克隆时用 token：

1

git clone https://<TOKEN>@github.com/username/repo.git

IDEA 中：登录 GitHub 时填 token，不要用账户密码

三、Git 核心命令

3.1 本地仓库

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22


# 初始化
git init
git init my-project
git clone https://github.com/xxx/repo.git

# 查看状态
git status
git log --oneline --graph --decorate --all

# 暂存与提交
git add <file>
git add . # 当前目录所有
git add -p # 交互式分块
git commit -m "msg"
git commit -am "msg" # add tracked files + commit

# 撤销
git checkout -- <file> # 丢弃工作区修改
git reset HEAD <file> # 取消暂存
git reset --soft HEAD~1 # 撤销 commit，保留暂存
git reset --hard HEAD~1 # 撤销 commit，丢弃修改（危险）
git revert <commit> # 反向 commit（安全）

3.2 分支

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


# 创建与切换
git branch <name> # 创建
git checkout <name> # 切换
git checkout -b <name> # 创建并切换
git switch <name> # Git 2.23+
git switch -c <name> # 创建并切换

# 推送与拉取
git push origin <branch>
git pull origin <branch>
git pull --rebase origin <branch> # 拉取后变基

# 合并
git merge <branch>
git merge --no-ff <branch> # 保留分支历史
git rebase <branch> # 变基（线性历史）

3.3 远程

1
2
3
4
5


git remote -v
git remote add origin https://github.com/xxx/repo.git
git remote set-url origin <new-url>
git fetch origin
git fetch --all

3.4 标签

1
2
3
4
5
6


git tag # 列出本地标签
git tag v1.0.0 # 轻量标签
git tag -a v1.0.0 -m "msg" # 附注标签
git push origin v1.0.0 # 推送单个
git push origin --tags # 推送所有
git checkout v1.0.0 # 切到标签

3.5 Stash（暂存工作区）

1
2
3
4


git stash # 暂存当前修改
git stash pop # 恢复
git stash list # 列出
git stash apply stash@{0} # 应用指定

四、`.gitignore` 模板

4.1 Java 项目

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30


# 编译产物
target/
build/
out/
*.class
*.jar
*.war

# IDE
.idea/
.vscode/
*.iml
*.iws
*.ipr
.project
.classpath
.settings/

# 日志
*.log
logs/

# 系统
.DS_Store
Thumbs.db

# 密钥
*.pem
*.key
secrets.yaml

4.2 Node 项目

1
2
3
4
5
6
7


node_modules/
npm-debug.log
.env
.env.local
dist/
.next/
.nuxt/

4.3 Python 项目

1
2
3
4
5
6
7


__pycache__/
*.pyc
.venv/
venv/
*.egg-info/
.pytest_cache/
.mypy_cache/

五、分支管理策略

5.1 Git Flow（2010 年 Vincent Driessen 提出）

1
2
3
4
5


master（生产）
 └── hotfix-*（紧急修复）
develop（开发）
 ├── feature-*（功能）
 └── release-*（预发布）

master：每个 commit 都是稳定版本，打 tag
develop：日常开发主分支
feature/*：功能分支，开发完 merge 回 develop
release/*：预发布分支，测试通过后 merge 到 master + develop
hotfix/*：紧急修复，直接从 master 拉，修完 merge 回 master + develop

5.2 GitHub Flow（2011 年 GitHub 提出）

只有 main + feature 分支：

从 main 拉 feature 分支
提交 + 推送到 GitHub
开 Pull Request
CI/CD 自动跑
Code Review
合并到 main
main 自动部署

适合：持续部署、单一版本的产品。

5.3 Trunk-Based Development（主干开发）

所有人在 main 上开发，短期分支（< 1 天）：

Feature flag：用代码开关控制新功能
每提交必测：CI 跑全量测试
每日合并：避免长寿命分支

适合：超大规模团队（Google、Facebook）。

六、GitHub 高级搜索

GitHub 搜索语法 2013 年就成熟了，对找开源项目、找开发者极有用。

6.1 关键词

语法	含义
`in:name xxx`	仓库名含 xxx
`in:description xxx`	描述含 xxx
`in:readme xxx`	README 含 xxx

6.2 数量

语法	含义
`stars:>xxx`	star > xxx
`stars:xx..xx`	star 在范围内
`forks:>xxx`	fork > xxx

6.3 地区/语言

语法	含义
`location:china`	地区
`language:javascript`	主语言

6.4 大小/日期

语法	含义
`size:>=5000`	仓库大小（KB）
`pushed:>2020-01-01`	最后 push 时间
`created:>2020-01-01`	创建时间

6.5 找组织/开发者

语法	含义
`user:xxx`	找用户
`org:xxx`	找组织
`followers:>=xxx`	关注者数量

6.6 License

语法	含义
`license:apache-2.0`	Apache 2.0
`license:mit`	MIT
`license:gpl-3.0`	GPL 3.0

6.7 实战示例

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


# 找 Java 写的、star > 10k 的 Spring Boot 项目
language:java spring boot stars:>10000

# 找 2020 年后更新的 Python 机器学习项目
language:python machine learning pushed:>2020-01-01

# 找 Apache 2.0 协议的 React 组件
react license:apache-2.0 in:readme

# 找来自中国的 JavaScript 全栈开发者
language:javascript location:china followers:>100

七、常用 Git 工作流

7.1 Fork 同步上游

Fork 别人的仓库后，怎么同步上游更新？

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


# 1. 关联上游仓库
git remote add upstream https://github.com/original-owner/repo.git
git remote -v

# 2. 拉取上游更新
git fetch upstream
git checkout main
git merge upstream/main

# 3. 推到自己 Fork
git push origin main

7.2 Git-FTP：用 FTP 部署静态站点

git-ftp 工具（https://github.com/git-ftp/git-ftp）让 Git 管理 FTP 部署：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


# 安装
# Windows: scoop install git-ftp
# macOS: brew install git-ftp

# 初始化
git ftp init --user <USER> --passwd <PASS> ftp://host/

# 部署
git ftp push --user <USER> --passwd <PASS> ftp://host/

# 只部署 master
git ftp push --syncroot . --user <USER> --passwd <PASS> ftp://host/

适用：没有 CI/CD 的小项目，纯 FTP 部署。

7.3 Git 配合 Jenkins

Jenkinsfile 经典写法：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28


pipeline {
 agent any
 stages {
 stage('Checkout') {
 steps {
 git branch: 'main',
 url: 'https://github.com/xxx/repo.git',
 credentialsId: 'github-token'
 }
 }
 stage('Build') {
 steps {
 sh 'mvn clean package -DskipTests'
 }
 }
 stage('Test') {
 steps {
 sh 'mvn test'
 }
 }
 stage('Deploy') {
 when { branch 'main' }
 steps {
 sh 'mvn deploy'
 }
 }
 }
}

7.4 Git 标签发版

1
2
3
4
5
6
7
8


# 发版流程
git checkout main
git pull
# 写 CHANGELOG
git tag -a v1.5.0 -m "Release 1.5.0"
git push origin v1.5.0

# GitHub 上：Releases → Draft a new release → 选 tag → 写变更

八、Git 内部原理

8.1 三个区

1
2
3
4
5
6
7


工作区（Working Directory）
 ↓ git add
暂存区（Staging / Index）
 ↓ git commit
本地仓库（Repository / .git）
 ↓ git push
远程仓库（Remote）

8.2 Git 对象

blob：文件内容
tree：目录结构
commit：一次提交（含 tree + parent + author + message）
tag：标签对象

每个对象都有 SHA-1 hash，git cat-file -p <hash> 看内容。

8.3 分支本质

分支是 commit 的指针。.git/refs/heads/main 文件里就一个 40 字符的 hash。

1
2
3


# 查看分支指向
cat .git/refs/heads/main
# 输出：a1b2c3d4e5f6...

九、常见问题

9.1 “Failed to connect to github.com port 443: Timed out”

1
2
3
4
5
6
7


# 设代理
git config --global http.proxy http://127.0.0.1:1081
git config --global https.proxy http://127.0.0.1:1081

# 取消代理
git config --global --unset http.proxy
git config --global --unset https.proxy

9.2 “Could not resolve host: github.com”

1
2
3
4


# 改 hosts（Windows 路径：C:\Windows\System32\drivers\etc\hosts）
# 注意：先去掉"只读"属性
140.82.112.4 github.com
140.82.112.3 github.com

或者用 SwitchHosts 工具可视化编辑。

9.3 “Your branch is ahead of ‘origin/main’ by N commits”

1

git push origin main

9.4 合并冲突

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


# 1. 拉取冲突代码
git pull origin main
# 输出：CONFLICT (content): Merge conflict in <file>

# 2. 打开文件，找到冲突标记
<<<<<<< HEAD
你的代码
=======
别人的代码
>>>>>>> branch-name

# 3. 手动编辑（保留你想要的）

# 4. 标记为已解决
git add <file>
git commit -m "resolve conflict"

9.5 “Permission denied (publickey)”

1
2
3
4
5
6
7
8


# 检查 SSH key 是否加载
ssh-add -l

# 如果没加载
ssh-add ~/.ssh/id_ed25519

# 测试连接
ssh -T git@github.com

9.6 误删分支恢复

1
2
3
4
5


# 1. 找到最后一次 commit hash
git reflog

# 2. 重建分支
git checkout -b <branch> <hash>

9.7 .git 占用空间过大

1
2
3
4
5
6


# 清理大文件历史
git gc --aggressive --prune=now
# 或用 BFG Repo-Cleaner
bfg --delete-files "*.jar" --no-blob-protection
git reflog expire --expire=now --all
git gc --prune=now --aggressive

十、下一步

想看 Java 主力 IDE：[2014-04-15 IntelliJ IDEA 全攻略]
想看 CI/CD：项目全流程 章节中的 Jenkins 实战
想看 Git 托管平台对比：[2021-05-10 开源生态观察]

本文写于 2014 年，回看当时：Git 2.1 是当时最新版，git switch / git restore 还没出来（2019 年 2.23 才发布）；GitHub 高级搜索语法至今未大变；Git Flow 在 2014 已是行业事实，但 2017 年后 Trunk-Based 越来越流行——Git 工作流的演化反映了 CI/CD 文化的演进。