git + LaTeX 工作流程

git + LaTeX workflow

提问by Ivan

I'm writing a very long document in LaTeX. I have my work computer and my laptop, and I work on them both. I need to keep all the files synchronized between the two computers, and also would like to keep a revision history. I chose git as my DVCS, and I'm hosting my repository on my server. I'm also using Kile + Okular to do the editing. Kile doesn't have an integrated git plugin. I'm also not collaborating with anyone on this text. I'm also thinking about putting another private repository on codaset, if my server for some reason is not accessible.

我正在用 LaTeX 写一个很长的文档。我有我的工作电脑和笔记本电脑，我都在用它们工作。我需要保持两台计算机之间的所有文件同步，并且还想保留修订历史。我选择 git 作为我的 DVCS，并将我的存储库托管在我的服务器上。我也在使用 Kile + Okular 进行编辑。Kile 没有集成的 git 插件。我也没有与任何人就本文进行合作。如果由于某种原因无法访问我的服务器，我也在考虑将另一个私有存储库放在 codaset 上。

What is the recommended workflow practice in this case? How can branching be fitted in this working scheme? Is there a way to compare two versions of the same file? What about using a stash?

在这种情况下，推荐的工作流程实践是什么？如何在这个工作方案中安装分支？有没有办法比较同一文件的两个版本？使用 stash 怎么样？

回答by abcd

Changes to your LaTeX workflow:

对 LaTeX 工作流程的更改：

The first step in efficiently managing a git+latex workflow is to make a few changes to your LaTeX habits.

有效管理 git+latex 工作流程的第一步是对您的 LaTeX 习惯进行一些更改。

• For starters, write each sentence on a separate line. Git was written to version control source code, where each line is distinct and has a specific purpose. When you write documents in LaTeX, you often think in terms of paragraphs and write it as a free flowing document. However, in git, changes to a single word in a paragraph get recorded as a change to the entire paragraph.

  One solution is to use git diff --color-words(see my answerto a similar question where I show an example). However, I must emphasize that splitting into separate lines is a much better option (I only mentioned it in passing in that answer), as I've found it to result in very minimal merge conflicts.

• If you need to look at the code diff, use git's native diff. To see the difference between two arbitrary commits (versions), you can do so with the shas of each of the commits. See the documentationfor more details and also this question

  On the other hand, if you need to look at the diff of your formatted output, use latexdiffwhich is an excellent utility (written in perl) that takes two latex files and produces a neat diffed output in pdf like this (image source):

  

  You can combine gitand latexdiff(plus latexpandif needed) in a single command using git-latexdiff(e.g. git latexdiff HEAD^to view the diff between your worktree and the last-but-one commit).

• If you're writing a long document in latex, I'd suggest splitting different chapters into their own filesand call them in the main file using the \include{file}command. This way it is easier for you to edit a localized part of your work, and it is also easier for version control, as you know what changes have been made to each chapter, instead of having to figure it out from the logs of one big file.

• 首先，将每个句子写在单独的行上。Git 被编写为版本控制源代码，其中每一行都是不同的并且有一个特定的目的。当您在 LaTeX 中编写文档时，您通常会根据段落进行思考并将其编写为自由流动的文档。但是，在 git 中，对段落中单个单词的更改会被记录为对整个段落的更改。

  一种解决方案是使用git diff --color-words（请参阅我对类似问题的回答，其中显示了一个示例）。但是，我必须强调，拆分成单独的行是一个更好的选择（我只是在那个答案中提到了它），因为我发现它会导致非常小的合并冲突。

• 如果您需要查看代码差异，请使用 git 的原生差异。要查看两个任意提交（版本）之间的差异，您可以使用sha每个提交的s 来查看。有关更多详细信息以及此问题，请参阅文档

  另一方面，如果您需要查看格式化输出的差异，请使用latexdiff这是一个出色的实用程序（用 perl 编写），它采用两个乳胶文件并在 pdf 中生成这样的整洁差异输出（图像源）：

  

  您可以使用git-latexdiff在单个命令中组合git和latexdiff（latexpand如果需要，加上）（例如，查看您的工作树和最后一次提交之间的差异）。git latexdiff HEAD^

• 如果您正在用 Latex 编写长文档，我建议将不同的章节拆分为各自的文件，并使用\include{file}命令在主文件中调用它们。通过这种方式，您可以更轻松地编辑工作的本地化部分，也更容易进行版本控制，因为您知道对每一章进行了哪些更改，而不必从一个大的日志中弄清楚文件。

Using git efficiently:

有效地使用 git：

• Use branches!. There is perhaps no better advice I can give. I've found branches to be very helpful to keep track of "different ideas" for the text or for "different states" of the work. The masterbranch should be your main body of work, in its most current "ready to publish" state i.e., if of all the branches, if there is one that you are willing to put your name on it, it should be the master branch.

  Branches are also extremelyhelpful if you are a graduate student. As any grad student will attest, the advisor is bound to have numerous corrections, most of which you don't agree with. Yet, you might be expected to atleastchange them for the time being, even if they are reverted later after discussions. So in such cases, you could create a new branch advisorand make changes to their liking, at the same time maintaining your own development branch. You can then merge the two and cherry pick what you need.

• I would also suggest splitting each section into a different branch and focus only the section corresponding to the branch that you're on. Spawn a branch when you create a new section or dummy sections when you make your initial commit (your choice, really). Resist the urge to edit a different section (say, 3) when you're not on its branch. If you need to edit, commit this one and then checkout the other before branching. I find this very helpful because it keeps the history of the section in its own branch and also tells you at a glance (from the tree) how old some section is. Perhaps you've added material to section 3 that requires tweaking to section 5... Of course, these will, in all probability, be observed during a careful reading, but I find it helpful to see this at a glance so that I can shift gears if I'm getting bored of a section.

  Here's an example of my branches and merges from a recent paper (I use SourceTree on OS X and git from the command line on Linux). You'll probably notice that I'm not the world's most frequent committer nor do I leave useful comments all the time, but that's no reason for you not to follow those good habits. The main takeaway message is that working in branches is helpful. My thoughts, ideas and development proceeds non-linearly, but I can keep track of them via branches and merge them when I'm satisfied (I also had other branches that led nowhere that were later deleted). I can also "tag" commits if they mean something (e.g., initial submissions to journals/revised submissions/etc.). Here, I've tagged it "version 1", which is where the draft is as of now. The tree represents a week's worth of work.

  

• Another useful thing to do would be to make document wide changes (such as changing \alphato \betaeverywhere) commits on their own. That way, you can revert changes without having to rollback something else along with it (there are ways you can do this using git, but hey, if your can avoid it, then why not?). The same goes for additions to the preamble.

• Use a remote repo and push your changes upstream regularly. With free service providers like github and bitbucket (the latter even allows you to create private repos with a free account), there is no reason to not be using these if you're working with git/mercurial. At the very least, consider it as a secondary backup (I hope you have a primary one!) for your latex files and a service that allows you to continue editing from where you left on a different machine.

• 使用分支！. 我可能没有更好的建议了。我发现分支对于跟踪文本的“不同想法”或工作的“不同状态”非常有帮助。该master分支应该是你工作的主体，在其最新的“准备发布”状态，即，如果所有的分支，如果有一个你愿意把你的名字就可以了，它应该是主分支。

  如果您是研究生，分支机构也非常有帮助。正如任何研究生都会证明的那样，导师肯定会有许多更正，其中大部分是您不同意的。但是，您可能至少要暂时更改它们，即使它们在讨论后稍后恢复。因此，在这种情况下，您可以创建一个新分支advisor并根据自己的喜好进行更改，同时维护自己的开发分支。然后，您可以合并两者并挑选您需要的。

• 我还建议将每个部分分成不同的分支，并只关注与您所在分支相对应的部分。当您进行初始提交（实际上是您的选择）时，在创建新部分或虚拟部分时生成一个分支。当您不在其分支上时，抵制编辑不同部分（例如 3）的冲动。如果你需要编辑，提交这个，然后在分支之前签出另一个。我发现这非常有用，因为它将部分的历史记录保存在自己的分支中，并且还可以一目了然地（从树中）告诉您某个部分的年龄。也许你已经在第 3 节中添加了需要调整到第 5 节的材料......当然，这些内容很可能会在仔细阅读时观察到，但我发现一目了然地看到这一点很有帮助，这样我就可以换档，如果我'

  这是我最近一篇论文中的分支和合并示例（我在 OS X 上使用 SourceTree，在 Linux 上从命令行使用 git）。您可能会注意到，我不是世界上最频繁的提交者，也不会一直留下有用的评论，但这不是您不遵循这些好习惯的理由。主要的外卖信息是在分支机构工作是有帮助的。我的想法、想法和发展是非线性的，但我可以通过分支跟踪它们，并在我满意时合并它们（我也有其他分支，后来无处可去，但后来被删除了）。我也可以“标记”提交，如果它们意味着什么（例如，对期刊的初始提交/修订提交/等）。在这里，我将其标记为“版本 1”，这是目前草稿所在的位置。树代表一周'

  

• 另一个有用的事情是自己进行文档范围的更改（例如更改\alpha为\beta所有地方）提交。这样，您就可以还原更改而不必同时回滚其他内容（您可以使用 git 执行此操作，但是嘿，如果您可以避免它，那为什么不呢？）。对序言的补充也是如此。

• 使用远程仓库并定期向上游推送您的更改。使用 github 和 bitbucket 等免费服务提供商（后者甚至允许您使用免费帐户创建私人存储库），如果您使用 git/mercurial，则没有理由不使用它们。至少，将其视为您的 Latex 文件的辅助备份（我希望您有一个主要备份！），以及一项允许您从在另一台机器上离开的位置继续编辑的服务。

回答by Diego

I have a similar workflow as well. Even though one branch is being worked on at a time, I find it beneficial to have separate branches for different states of work. For example, imagine sending a good rough draft of your paper to your advisor. Then, you get a crazy idea! You want to start changing some core concepts, re-work some major sections, etc. etc. So you branch off and start working. Your master branch is always in a “releasable” state (or as close as you are in that moment). So while your other branch is crazy and has some drastic changes, if another publisher wants to see what you have, or you're a student submitting to a conference, the master branch is always releasable, ready to go (or ready to show your advisor). If your PhD advisor wants to see the draft first thing in the morning, yes you could stash/stage/commit your current changes, use tags or search through the log, but why not keep separate branches?!

我也有类似的工作流程。尽管一次只处理一个分支，但我发现为不同的工作状态设置单独的分支是有益的。例如，想象一下将您论文的草稿发送给您的顾问。然后，你会有一个疯狂的想法！你想开始改变一些核心概念，重新工作一些主要部分，等等。所以你分支并开始工作。你的主分支总是处于“可释放”状态（或者与你当时的状态一样接近）。所以当你的另一个分支很疯狂并且有一些剧烈的变化时，如果另一个出版商想看看你有什么，或者你是一个提交会议的学生，master 分支总是可以发布的，准备好了（或准备好展示你的顾问）。如果你的博士导师想在早上第一时间看到草稿，

Lets say your master branch has the "releasable" state of your work. You now want to submit it to several peer-reviewed journals, each having different formatting requirements for the same content and you're expecting them to come back with several different small criticisms about how you can edit the paper to fit their readers, etc. You could easily create a branch for each journal, make journal specific changes, submit, and when you receive the feedback make the changes on each separate branch.

假设您的主分支具有您工作的“可发布”状态。你现在想把它提交给几个同行评审的期刊，每个期刊对相同的内容都有不同的格式要求，你希望他们回来就如何编辑论文以适应他们的读者等提出几个不同的小批评。您可以轻松地为每个期刊创建一个分支，进行特定于期刊的更改，提交，并在收到反馈时在每个单独的分支上进行更改。

I have also used Dropbox and git to create the system you describe above. You can create a bare-bones repository in your dropbox folder. You can then push/pull from either computer to your dropbox to stay up to date on all ends. This system usually only works when the number of collaborators are small since there is a possibility of corruption if people try to push to the dropbox repo at the same time.

我还使用 Dropbox 和 git 来创建你上面描述的系统。您可以在 Dropbox 文件夹中创建一个基本存储库。然后，您可以从任何一台计算机推/拉到您的保管箱，以在所有方面保持最新状态。该系统通常仅在协作者数量较少时才起作用，因为如果人们同时尝试推送到 Dropbox 存储库，则存在损坏的可能性。

You could technically also just keep ONE repository inside the dropbox folder and do all your work from there. I would discourage this however, as people have mentioned that dropbox has some trouble synchronizing files that are constantly changing (gits internal files).

从技术上讲，您也可以在 dropbox 文件夹中保留一个存储库，然后从那里完成所有工作。然而，我不鼓励这样做，因为人们已经提到 dropbox 在同步不断变化的文件（gits 内部文件）时遇到了一些麻烦。

回答by Rafareino

I tried to implement this as a bash function, I've included it in my ~/.bashrcto make it always available.

我试图将它实现为一个 bash 函数，我已经将它包含在我的中~/.bashrc以使其始终可用。

function git-latexdiff {    
    if [[ $# != 2 ]];    
    then      
        printf "\tusage: git-latexdiff <file> <back-revision>  \n";    
    elif [[  -lt 0 ]];     
    then     
        printf "\t<Back-revision> must be positive\n";   
    else      
        dire=$(dirname $PWD/);      
        based=$(git rev-parse --show-toplevel);      
        git show HEAD~:$(echo $dire| sed 's!'$(echo $based)'/!!')/ > _diff.tmp;      
        latexdiff  _diff.tmp > _diff.tex;      
        pdflatex _diff.tex;     
        okular _diff.pdf;      
        rm _diff*;   
    fi; 
}

Note that this function needs latexdiffto be installed (and be found on the path). It is also important for it to to find pdflatexand okular.

注意这个功能需要latexdiff安装（并且在路径上找到）。找到pdflatex和也很重要okular。

The first is my preferedway to process LaTeX, so you can chage it to latexas well. The second is my PDF reader, I supose you'll want to use evinceunder gnome, or some other solution.

第一种是我首选的处理 LaTeX 的方式，因此您也可以将其更改latex为。第二个是我的 PDF 阅读器，我假设您想evince在 gnome 或其他一些解决方案下使用。

This is a quick version, made with a single document in mind, and that is because with git, you will lose a lot of time and effort tracking a multi file LaTeX document. You may let git do this task as well, but if you want, you can also continue using \include

这是一个快速版本，考虑到单个文档，这是因为使用 git，您将失去大量时间和精力来跟踪多文件 LaTeX 文档。你也可以让 git 来做这个任务，但如果你愿意，你也可以继续使用\include

回答by Alberto Pepe

Another option is to use Authoreawhich is some sort of Github for scientific papers. Every article in Authorea is a Git repo. And the LaTeX you compose gets rendered to HTML5 (as well as PDF, when you compile).

另一种选择是使用Authorea，它是某种用于科学论文的 Github。Authorea 中的每篇文章都是一个 Git 存储库。您编写的 LaTeX 将呈现为 HTML5（以及编译时的 PDF）。

回答by redreamality

use this for version diffin case you are on windows, no installment, just a simple batscript It works perfectly on windows10, miktex2.9:

如果您在 Windows 上，无需分期付款，只需一个简单的脚本，请将此用于版本差异bat它在 windows10、miktex2.9 上完美运行：

https://github.com/redreamality/git-latexdiff

https://github.com/redreamality/git-latexdiff