git branch -m main_用Git管理Latex写论文的工作流程

为什么用Latex写论文需要设计“工作流程”

Latex是理工类论文的事实标准，但是对于“写作-合作者审阅-讨论并修订-写作新内容”这样迭代式的写作流程来说，它缺少清晰的修订模式。尤其当作者和合作者并行修改论文时，这个缺陷会经常导致内容冲突、遗失等问题，全靠肉眼一行行地修订非常费时间。

第二个问题是论文是会被拒的。在快则个把月，慢则长达一年的评阅时间之后，再度捡起论文草稿，很难记起当时的写作思路和版本迭代思路。

采用Git管理论文工作流程可以保存所有历史版本、简化内容合并过程。

整体思路

1. 在code hosting网站上建立你的论文仓库（如：my-papers文件夹），每一篇内容独立的论文用一个单独的文件夹保存。网站选择的原则是随时可访问和支持私有库。
2. 每一篇的论文写作，均只从远程仓库pull当前论文的目录，不影响其他论文。
3. 用至少三个分支进行写作。和程序开发相似，master分支的代码总是submission-ready的。每个合作者的修改单独用一个分支保存，比如co-author分支。收到新的修改后，放到co-author分支下，然后merge到当前写作分支，比如my-writing分支。

具体流程

利用Git的sparse-checkout功能建立论文仓库

在代码托管网站上建论文仓库没什么可说的，这里只说一下如何每次只pull当前论文的目录。（ref: http://blog.algony.net/2015/05/git-sparse-checkout/）

$ git init <project>      
$ cd <project>     
$ git remote add origin <your_remote_paper_repo>     
$ git config core.sparsecheckout true # 打开sparse-checkout模式     
$ echo "<current_paper_dir>" >> .git/info/sparse-checkout # 设置需要pull的论文目录     
$ git pull origin master     
$ <edit_your_paper>  # 修修补补你的宝贝论文     
$ git pull origin master # 如果远程仓库有新的修改，则pull下来合并，可选     
$ git push --set-upstream-to origin master # 第一次push需要设置本地分支和远程分支的
                                           # 跟踪关系，之后直接"git push origin"就可以

注意事项：

1. git pull操作相当于git fetch + git merge操作组合。因此如果你不止想pull远程仓库里的master分支，而是所有分支，上述命令中的第一个pull操作可以用git fetch origin代替，后者默认下载origin服务器上所有分支，所取回的更新。这些分支在本地主机上要用"远程主机名/分支名"的形式读取，如remotes/origin/master。
2. git fetch之后本地是没有分支的，本地工作目录也为空。需要在远程分支基础上，使用

$ git checkout -b <new_local_branch> origin/<remote_branch> 

创建一个本地分支<new_local_branch>。

3. 或者执行

$ git checkout merge origin/<remote_branch>  

将origin/<remote_branch>合并到本地master分支。如果当前没有分支，git merge会在本地创建master分支。

4. 或先在本地checkout一个分支，然后执行

git branch --set-upstream-to=origin/<branch>

指定当前本地分支跟踪远程分支

Git写Latex的流程

(ref: https://stackoverflow.com/questions/6188780/git-latex-workflow)

1. 最好每一章一个单独的tex文件，因为论文不中改投的时候可能需要换模板。这时候将每一章直接input到模板文件里就可以。
2. 每句话一段。Git的diff默认以行为单位，而Latex只有在每段话前面有空行时才认为是新的段落，所以每句话一段不影响Latex排版，又可以方便Git做diff。你甚至可以git diff --color-words打开逐字比对的效果。
3. 为每个section开一个分支。合作论文最常见的情况就是一个人写一章，合作者写/改另一章。为每一章开一个单独的分支，方便跟踪进度和合并。
4. 全局性的修改，如将整个论文中的“Section”改成“Chapter”，做成单独的commit。导言区的修改也是如此。这样无论是diff或者patch都很清楚做了什么修改，不会和内容修改相混淆。

和不使用Git的合作者合作

(ref: http://www.math.cmu.edu/~gautam/sj/blog/20130929-git-quickstart.html)

你没有办法让你的合作者为了改你的论文在学会了Latex之后还专门去学Git，尤其是那些德高望重的合作者，比如你的导师。而他们的意见和修改，一般来说是非听不可的。这时我们面临的主要问题有两个：

1. 记住交给合作者的论文版本
2. 合作者返回时，快速定位修改位置，并和你的当前版本合并。
3. 而你的当前版本，可能已经不是当初交给合作者的版本了，甚至push到远程服务器了。（这不算第三个问题。）

有时候你会觉得合作者的意见并不那么靠谱，但是沟通还得继续，他仍然是你的导师，你必须得让他知道你欣然接受了他的意见。这时候可以新开一个分支，用于接受合作者的意见并和他继续往来沟通，而论文的实际发布版本则在另一个分支上。

总之，我们需要一个叫做git-ident的Perl脚本帮我们自动化这些事情。步骤如下：

1. 在你打算commit一个版本，并将这个版本发给合作者之前，在当前论文的根目录下创建/修改.gitattributes文件，内容为：

*.tex ident 
*.bib ident

2. 然后在你要发给合作者的主文件里，如main.tex，加上一句包含$Id$的注释，如：

% DO NOT EDIT -> $Id$ <- DO NOT EDIT

3. 安装git-ident，并在你的论文根目录下添加它的post-commit hook：

$ cd .git/hooks 
$ ln -s /path/to/git-ident/post-commit

4. commit或者checkout你的论文，这时候Git会自动将$Id$替换为当前版本的SHA1值（并不是你commit的版本号）。

这时候你就可以把你最新的commit的版本发给合作者了，静静地等待他的修改，或者自己继续写下一章节。等他返回给你的时候，执行

$ /path/to/git-ident/git-find-commit.pl <your_shared_tex_file>.tex

脚本会输出你当时交给合作者的commit版本号，比如b2234fa5之类。根据这个版本号，你可以创建/转到你的co-author分支，保存他的修改，并merge到你的当前版本：

$ git checkout -b co-author b2234fa5 
$ <save_his_file> # Save his file over yours 
$ git commit --author 'Co Author <who@doesnt.use.git>' 
$ git checkout my-writing 
$ git merge co-author

当你完成你对合作者这次修改的内容的编辑之后，可以重复这个流程，开始下一轮的“写作-合作者审阅-讨论并修订”了。

注意：git-ident需要Perl环境，并安装IPC::Run和IPC::System::Simple模块。方式为：

1. 执行sudo cpan进入cpan环境
2. 执行install MODULE_NAME安装模块

查看修订

第一种办法是用git diff，实现在tex源代码上显示差异。缺陷就是Git以行为单位做diff，而且tex源码上看diff非常不清晰。

第二种办法是使用usepackage{changes}，这需要需要合作者在修订的时候自己加标注，实在难为人。

第三种办法就是用latexdiff工具，一般TeX版本都自带，方法为：

$ latexdiff <old_tex_file>.tex <new_tex_file>.tex  >  <diff_file>.tex

当我们采用每章一个tex文件的方式组织论文时，latexdiff需要加上--flatten参数以展开main.tex中的各种input，但效果并不好。可以试试git-latexdiff工具

另外，latexdiff得到的<diff_file>.tex经常容易出错，尤其在新老文件的section、subsection等名字不一致的时候。自己手动把两个文档改成一样的就行了。