Markdown写作 + Git版本管理 已成为全球IT互联网公司的主流写作平台，如果你有心投身这一领域从事技术写作，不妨事前学习一下Markdown语法以及Git版本管理的原理与常用指令。在国内的Gitee上搭个自己的repo，练练手。写作工具用顺手了，无疑可以让你有更多时间来了解产品，专注文档构思与写作。
目前已经快入职三个月了，慢慢对GIT不再恐惧，对GIT命令行也熟悉进来。前几天提交对原文档中几个节点的大修改，Merge Master后出现了一大堆Stashed/Staged的文件，以及莫名其妙的错误提示，彻底慌乱了。最后把产品的本地库删除，重新Clone远程库，重新基于远端分支建本地分支...似乎是搞清楚了一些概念。记录一下。
GIT之于文档管理的优势
目前，Markdown文档的版本管理是，基于Master，每个新feature，建立一个分支。Draft完成后，通过BitBucket Create Pull Request（PR) 。将PR发给Reviewer。Git之于文档管理，一个强大的地方是方便文档审阅。
-
见下图，它清楚地对比出前后两个版本的区别。
Diff对比 -
Reviewer可以直接在某一行加Comments,并且@相关人员。
image.png -
另外，Git的强大版本管理功能（Versioning)。
- 多个TW对同一release分支（for example, release_A)，同步进行文档写作与维护。各个TW在此分支上建新分支(release_A_Joy)。完成评审后，merge回原始release分支(release_A)中。
- 在merge时，可能会产生冲突（比如两位TW对同一文件进行了修改，另一位TW在你之前把他的修订merge到(Release_A)了）。不用担心，在你的分支（Release_A_Joy）上，执行pull origin Release_A操作。此时，在VS Code操作界面，会显示出冲突的内容，让你选择是保留你所做的修订（release_A_Joy)，还是保留目标分支中的修订(Release_A)。
Git存储区域
Git常用命令
图解
常用命令
Clone文档库
cd <本地Repo所在folde>
git clone ssh://git@code.abc.net/pd/xxx.git //只会clone master分支到本地，远端的其它分支是不会clone到本地的
根据远端分支建本地分支
方法1：
Git pull:
Git branch
Git checkout <分支名>
方法2：
Git branch -r //查看远端分支，保证新分支存在
git checkout -b branchname origin/branchname //建立本地分支，并将它map到远端分支
注意！branchname前不加 "/"
提交本地分支到远端分支
如果有新增文件，必须先执行该命令
Git add .如果有repo中没有用到的文件，必须先执行删除，否则commit不会成功
Note: 从BitBucket迁移到GitHub后，如果在本地删除了文件，无需执行此步所述操作。
Git rm <文件名>
Git rm -f <文件名> // 如果需要删除之前修改过并且已经放到暂存区域的文件，则必须要用强制删除选项 -f
注意！删除时要带相对路径
把修改以及增加与删除的文件从本地暂存区提交到本地库**
Git commit -m "reason for the commit" //将修改从本地暂存区提交到本地库
Git commit -am "reason for the commit" //把暂存区的所有被修改或者已删除的文件提交提交到分支，
注意! : 如果有新增的或是删除的文件，必须在commit前，一定要先执行Git add .以及Git rm将本地库修改同步到远端库，新手容易忘记这步！
Git Push
其它通用指令
-
在commit前用该命令，查看显示工作区（workspace)与暂存区(stage/index)的状态。使用此命令能看到那些修改被暂存了, 哪些没有
Git status -
显示所有本地分支
Git branch -
显示所有远端分支
Git branch -r -
回退到本地库中的版本，放弃工作区（workspace）中所做修改
git checkout <file>
git checkout —整个库会退到本地库版本 -
删除.git本地库
- Enter the local repo folder.
- $ rm -rf .git
- In File Manager, delete the repo folder.
-
多个Commit后，如何回到某个Commit （head）的状态
- 查看Commit head id
Git log - 强行回退
git reset --hard <Commit head IDs>
- 查看Commit head id
关于Staged与Stashed files
Staged -- 保存在暂存Stage/Index(缓存区）的文件，也就是完成了git add .的文件，但没有committ。
Stashed--临时需要切换branch，但working区的文件又不想commit，但又想保存在某个地方，以便下次继续开发，可用stash命令，将其暂存在working区的暂存区（并不是stage/index区）。-- PR时会把你所有的commit都显示出来，如果你每做一点点修改，就commit，你的每一次commit记录都会被别人看到。此时，stash命令就比较有用了
文档开发过程中，定期Merge Master内容。
因为Master是总版本，其它writer在不断向其中merge他们的feature分支。提交PR前一定要做Merge操作，一则解决多个writer可能同时修改一个文件产生的冲突，另一则，在GitHub或是BitBucket里查看Diff时才会只标注你所做的修改。
方法一：
- (分支a）Git checkout master
- (本地master) Git pull
- (分支a）Git merge master //merge最新的master
- (分支a) Resolve any merge conflicts, add, commit, and check status. 切记必须commit到本地库
- (分支a） Git Push
方法二：
- 保证本地工作区是没有任何修改代码的，也就是说: 需要将本地工作区编辑过的文件添加到暂存区（git add .），或提交到本地仓库中(git commit)，才可以使用该命令拉取指定分支的代码合并到当前分支中。
- (分支a) Git pull origin master
- (分支a) Resolve any merge conflicts, add, commit, and check status. 切记必须commit到本地库
- (分支a） Git Push
Git stash
https://www.atlassian.com/git/tutorials/saving-changes/git-stash
$ git stash pop stash@{2}
$ git stash apply stash@{2}
$ git stash drop
