Debian Codegraph @

texmf-dist/doc/support/git-latexdiff/README.md

raw
1 Git LaTeXdiff
2 =============
3
4 `git-latexdiff` is a tool to graphically visualize differences between
5 different versions of a LaTeX file. Technically, it is a wrapper
6 around [git](http://git-scm.com) and
7 [latexdiff](https://www.ctan.org/pkg/latexdiff).
8
9 If your LaTeX source is split accross several `*.tex` files,
10 `git latexdiff` can call
11 [latexpand](https://www.ctan.org/pkg/latexpand) to expand it before
12 running `latexdiff` (this usually works better than using `latexdiff
13 --flatten`).
14
15 To get the manpage (needed to get `git latexdiff --help` to work), you
16 need the `a2x` tool from the asciidoc package.
17
18 Copying
19 -------
20
21 git-latexdiff's main author is [Matthieu
22 Moy](https://matthieu-moy.fr/). The script is freely distributable and
23 modifyable under the terms of the simplified BSD licence.
24
25 Documentation
26 -------------
27
28 The documentation is available through these commands:
29
30 git latexdiff -h
31 git latexdiff --help-examples
32
33 If you installed the manpage properly, you can get the same
34 documentation with:
35
36 man git-latexdiff
37
38 The output of git-latexdiff -h is given below:
39
40 ```
41 Usage: git latexdiff [options] OLD [NEW]
42 git latexdiff [options] OLD --
43 git latexdiff [options] -- OLD
44 Call latexdiff on two Git revisions of a file.
45
46 OLD and NEW are Git revision identifiers. NEW defaults to HEAD.
47 If "--" is used for NEW, then diff against the working directory.
48
49 Options:
50 --help this help message
51 --help-examples show examples of usage
52 --main <file> name of the main LaTeX, R Sweave,
53 or Emacs Org mode file.
54 The search for the only file containing 'documentclass'
55 will be attempted, if not specified.
56 For non-LaTeX files, a reasonable `prepare` command
57 will be used unless explicitly provided
58 --no-view don't display the resulting PDF file
59 --latex run latex instead of pdflatex
60 --xelatex run xelatex instead of pdflatex
61 --lualatex run lualatex instead of pdflatex
62 --tectonic run tectonic instead of pdflatex
63 --bibtex, --bbl display changes in the bibliography
64 (runs bibtex to generate *.bbl files and
65 include them in the source file using
66 latexpand --expand-bbl before computing
67 the diff)
68 --biber like --bibtex, but runs biber instead.
69 --run-bibtex, -b run bibtex as well as latex to generate the PDF file
70 (pdflatex,bibtex,pdflatex,pdflatex)
71 NOTE: --bibtex usually works better
72 --run-biber run BibLaTex-Biber as well as latex to generate the PDF file
73 (pdflatex,biber,pdflatex,pdflatex)
74 NOTE: --biber usually works better
75 --view view the resulting PDF file
76 (default if -o is not used)
77 --pdf-viewer <cmd> use <cmd> to view the PDF file (default: $PDFVIEWER)
78 --no-cleanup don't cleanup temp dir after running
79 --no-flatten don't call latexpand to flatten the document
80 --cleanup MODE Cleanup temporary files according to MODE:
81
82 - keeppdf (default): keep only the
83 generated PDF file
84
85 - none: keep all temporary files
86 (may eat your diskspace)
87
88 - all: erase all generated files.
89 Problematic with --view when the
90 viewer is e.g. evince, and doesn't
91 like when the file being viewed is
92 deleted.
93
94 --latexmk use latexmk
95 --build-dir use pdfs from specific build directory
96 --latexopt pass additional options to latex (e.g. -shell-escape)
97 -o <file>, --output <file>
98 copy resulting PDF into <file> (usually ending with .pdf)
99 Implies "--cleanup all"
100 --tmpdirprefix where temporary directory will be created (default: /tmp).
101 Relative path will use repository root as a base
102 --verbose, -v give more verbose output
103 --quiet redirect output from subprocesses to log files
104 --prepare <cmd> run <cmd> before latexdiff (e.g. run make to generate
105 included files)
106 --filter <cmd> run <cmd> after latexdiff and before compilation
107 (e.g. to fix up latexdiff output)
108 --ln-untracked symlink uncommited files from the working directory
109 --ln-untracked-dir <dir>
110 symlink subdirectory of uncommited files (relative to the main .tex file)
111 --version show git-latexdiff version.
112 --subtree checkout the tree at and below the main file
113 (enabled by default, disable with --whole-tree)
114 --whole-tree checkout the whole tree (contrast with --subtree)
115 --ignore-latex-errors keep on going even if latex gives errors, so long as
116 a PDF file is produced
117 --ignore-makefile ignore the Makefile, build as though it doesn't exist
118 -* other options are passed directly to latexdiff
119 --latexpand OPT pass option OPT to latexpand. Use multiple times like
120 --latexpand OPT1 --latexpand OPT2 to pass multiple options.
121 --latexdiff-flatten use --flatten from latexdiff instead of latexpand
122 --early-exit-if-equal if two files are identical latexdiff will not be called and git-latexdiff exits gracefully.
123 This option works only if latexpand is used
124
125 Unrecognized options are passed unmodified to latexdiff.
126 ```
127
128 Examples
129 --------
130
131 Diff the previous revision with the latest commit:
132
133 git latexdiff HEAD^
134
135 Diff the latest commit with the working tree:
136
137 git latexdiff HEAD --
138
139 Diff latest commit with branch master:
140
141 git latexdiff master HEAD
142
143 Pass --type=CHANGEBAR to latexdiff to get changebars in the margins
144 instead of red+trike/blue+underline diff:
145
146 git latexdiff --type=CHANGEBAR HEAD^
147
148 Use a specific latexdiff configuration file:
149
150 git latexdiff --config /path/to/file HEAD^
151
152 Add a \makeatletter statement to hopefuly fix some LaTeX compilation errors
153 involving commands containing an @ character:
154
155 git latexdiff --latexpand --makeatletter HEAD^