This note was written for our group as a minimal working example for collaborative writing using LaTeX and Git, and I'll keep updating this note. Below I show a step-by-step instruction to do version control using Git on the command line. The workflow is specifically designed for writing in LaTeX. Everything is tested on Mac with Git ver.2.3.2, so users of earlier versions should be careful. Please leave me a comment if you spot any mistake :)
Here's a list of steps (hyperlinked):
1. One-time-only setting
2. Clone an existing repository to local end
3. Change remote name
4. Push (pull) progress to (from) remote repository
5. Check the change log
6. Compare the difference between versions
7. Using a master BibTeX file as a Git submodule
8. Combining latexdiff and Git
****************************************
1. One-time-only setting.
Every time someone makes a change in the files, Git would record the submitter's name and email. Therefore, it's necessary to identify oneself in a collaboration work. Below shows how to set up a global Git config ("global" in the sense that every Git project you create on your laptop will use the same config):
[code gutter="false" language="bash"]
$ git config --global user.name "John Doe"
$ git config --global user.email [email protected]
[/code]
This command lets you specify the default editor which will be used in git commit:
[code gutter="false" language="bash"]
$ git config --global core.editor vim
[/code]
For Mac users, one more action is necessary to automatically ignore the annoying .DS_Store file:
[code gutter="false" language="bash"]
$ git config --global core.excludesfile ~/.gitignore
$ echo .DS_Store > ~/.gitignore
[/code]
After above steps, there should be two hidden files placed in the home directory: .gitconfig and .gitignore.
2. Clone an existing repository to local end.
After you collaborators write up something (a draft or a program) and push it to an online repository like GitHub or Overleaf, you'd like to clone it so that you can edit the files on your laptop. Assume you are in a working directory where you'd like to create a folder named temp to store the files, type
[code gutter="false" language="bash"]
$ git clone http://git.example.org/123abc temp
[/code]
Note that the above URL link should be replaced by the one pointing to your own Git project! Now you can cd temp and start working.
3. Change remote name
If you run git status in the temp folder, the output message should look like:
Your branch is up-to-date with 'origin/master'.
nothing to commit, working directory clean
Apart from the branch concepts (in the beginning we only have one branch called master), the "origin" seems confusing. But it is just a name representing the remote host, and you can change it to anything you want to make it clear (effective locally). For example,
[code gutter="false" language="bash"]
$ git remote rename origin overleaf
[/code]
will replace origin/master by overleaf/master.
4. Push (pull) progress to (from) remote repository
Suppose you edit some files, you may want to ask Git to record this version. When you run git status, you'll see files that you've edited but not yet "staged" (meaning Git does not know which file to look at yet). If so, do git add -u, where the -u argument means including all updated files. Run git status again to check the modified files are staged.
But to put staged file into Git's record, we need to "commit" them. Run git commit, and an text editor you specified earlier will be opened to let you type information related to this change. Save it and it's done. Now this version is recorded in your local machine. (If the message you'd like to type is just one line, you can do this in command line by git commit -m "This message will be logged".) Note that the two steps (add and commit) can be combined by git commit -a --- But use this carefully!
To sync the record between the local end and the remote repository, do
[code gutter="false" language="bash"]
$ git push overleaf master
[/code]
will upload the local master branch to "overleaf" (the name specified for the remote host). On the contrary, do
[code gutter="false" language="bash"]
$ git pull overleaf master
[/code]
will download the remote master branch on overleaf to local end. Caution: if you and your collaborators are working on the same branch (say you're writing a small-scale tex file on the master branch), it is highly recommended (see here and here) to use git pull --rebase overleaf master instead!
Two side notes: (i) pull is the combination of fetch and merge; (ii) pull and checkout are different. You use the latter to recover to earlier status when you mess up locally.
5. Check the change log
From the programmer point of view, the change log is extremely important as an essential ingredient of version control. To see the log, type git log. You will see a list of commit history in the following format:
Author: John Doe <[email protected]>
Date: Tue May 10 19:35:35 2016 -0400
Each of these is called a revision with a 40-character identifier. But in practice, the first 6 characters are enough to identify a revision (in this case it's 2277e9).
6. Compare the difference between versions
See the instruction in the "Exploring History" section here. The key idea is to use the 6-character identifiers to do comparisons between revisions.
7. Using a master BibTeX file as a Git submodule
This step closely follows the blog by Andrius Velykis, and the main reason of doing this is to keep one and only one bib file up-to-date without forgetting where it is stored.
Suppose your collaborator or you maintains a bib file on a repository, named RefBib for instance, and you'd like to use it in your tex file. Three scenarios: (i) you just initiated a Git project for writing in LaTeX: in this case, simply run
[code gutter="false" language="bash"]
$ git submodule add git://example.org/user/RefBib
[/code]
to add that bib file as a submodule to your Git project, where the URL points to the repository of RefBib;
(ii) your local repository is out-of-date (without any submodule), and the remote repository is up-to-date (with a submodule recently added): in this case, first pull the latest revision as usual,
[code gutter="false" language="bash"]
$ git pull overleaf master
[/code]
and you may be prompted to input some message regarding this merge (pull involves a merge, remember?). The problem is after pulling the subdirectory of the module (see the discussion below) is empty, and a few more actions are required to make it work:
[code gutter="false" language="bash"]
$ git submodule update --init
$ cd RefBib
$ git checkout master
[/code]
Note that in the second step we need to go to the subdirectory for a reason explained below;
(iii) you have not created the Git project yet and would like to clone from an existing one: this case is like starting from Step 2 above. The only difference is that here the submodule RefBib is assumed existing in the project. Run
[code gutter="false" language="bash"]
$ git clone --recursive http://git.example.org/123abc temp
[/code]
and Git will first pull down the main project, then pull down the submodule (thanks to the --recursive argument), and merge them automatically.
Anyway, after doing so, run ls -al and you'll see inside temp there is a folder named RefBib, which stores the bib file, and a hidden file .gitmodules; both of them should be kept track by Git. Now you can include the bib file as you normally do in your tex file.
Git submodules are sometimes confusing, and there are some subtleties I'd really like to skip here, but basically the key idea is that you should regard temp and RefBib as two different Git projects, each has its own Git version history.
Therefore, if you modify the bib file in RefBib, you should remember to go to the RefBib directory, commit the change, and push it to the remote repository of RefBib so that the status can be synced between your local copy and the remote one. On the other hand, in the main branch temp Git simply notes in .gitmodules that there's a submodule RefBib (pointing to a specific revision!) but does not store the content of it. An alternative of getting around these steps is to run
[code gutter="false" language="bash"]
$ git push --recurse-submodules=on-demand
[/code]
so that both the main project and the submodule will be pushed to their corresponding repositories.
Similarly, if you'd like to update your local submodule to the latest version on remote, you can either go to the subdirectory and pull as usual (because it's a separate project), or stay in the parent directory and run
[code gutter="false" language="bash"]
$ git submodule update --remote
[/code]
Either way would work. For further details of submodule, see here.
8. Combining latexdiff and Git
LaTeX users probably know a convenient Perl script called latexdiff which marks up differences between two tex files. For version control systems such as Git, it has a counterpart called latexdiff-vc, which should already be installed along with latexdiff. The syntax is equally simple. Suppose you'd like to compare the current version of example.tex with that of a particular revision (assuming its 6-character identifier is 2277e9), run
[code gutter="false" language="bash"]
$ latexdiff-vc --git -r 2277e9 example.tex
[/code]
and latexdiff-vc will create a compared tex file for you, just like what latexdiff does. The argument --git tells latexdiff-vc that the version control system is Git, and -r 2277e9 specifies which revision to look at. For more sophisticated uses, see the latexdiff manual.
****************************************
I think these is the basics on Git. I've skipped things like branches (how to create one, to switch between them, to merge them, etc) and handling conflicts, but you can easily find instructions online. Here's a short list I found useful:
The Pro Git ebook
Duke-OSG Workshop material
How to synchronize an Overleaf LaTeX paper with a GitHub repository
Git and Overleaf
The Python distribution that comes with Mac OS X is notorious in that it is not easy to update or install modules, and that there is often a dependency issue for applications not preinstalled. Therefore, for OS X users it's usually recommended that using package managers such as MacPorts and Homebrew instead, installing Python therein, and avoiding using the system Python. A better solution for novices is to install an independent Python distribution, including Anaconda and Enthought.
While most of solutions are available for free, it seems a bit redundant to me to have multiple copies of Python. Sometimes I was confused which Python I was using. Therefore, after a clean installation I decided to test how much the system Python can do. The example I chose is to install a module called IPython which is not preinstalled on OS X and provides a graphical notebook interface similar to Mathematica. The procedure below has been tested on Mac OS X 10.10.3.
After some trial and error I realized that it is impossible to install it with the easy_install command. But pip, however, can be installed by easy_install. Therefore, one can do
[code gutter="false" language="bash"]
sudo easy_install pip
sudo pip install ipython[all]
[/code]
We need sudo because the packages are installed in the system folder which only the root can access. The [all] tag in the second line tells pip to install everything that IPython may depend on. After installation one should be able to execute ipython in the command line. For a graphical interface, run ipython notebook instead.
Some users may run into a problem in which the zmq module is missing (see a related discussion). A possible reason is that the zmq (or pyzmq) module has been previously installed by easy_install, whose egg version is incompatible with IPython (as of ver 3.1.0) and hence not recognized by IPython. The solution is to remove and re-install it using pip:
[code gutter="false" language="bash"]
sudo pip uninstall pyzmq
sudo pip install pyzmq
[/code]
And one can test it by import zmq under the Python command line. It should work if the installation is successful.
One more thing: the --pylab flag in IPython has been deprecated (as of ver 3.1.0). One should instead execute %pylab in the notebook interface. If one wants the plots to be shown in the notebook interface rather than in a separated window, use %pylab inline.
It is really annoying that APS requires to use the extremely user-unfriendly CJK package and the cyberbit font if one wants to add Chinese/Japanese/Korean names in the journal publication with the UTF-8 encoding. (We have XeTeX/XeLaTeX now, dude!) It took me a long time to figure out how to do this. Although the MacTeX 2015 will be coming out soon in a few months, I think it's still worth taking a note on how I did this successfully as an up-to-date reference.
This note is based on several good instructions I found online and I recommend readers to refer to them, including Helmer Aslaksen's webpage, William Adam's mailing list post, Pai Chou's webpage, and the official document of MacTeX on how to install fonts. My quick note aims to give an update on where one should put the relevant files specifically for MacTeX 2014, so this is NOT a self-contained note!
- First of all, the link to the cyberbit font (cyberbit.zip) on various posts are dead. I found it can be downloaded here or here (thank you, Wikipedia!).
- The UCS package is not needed and the CJK package is preinstalled with the TeXLive distribution, so let's move on.
- After generating the .tfm and .enc files, I moved the former to a path I created:
/usr/local/texlive/texmf-local/fonts/tfm/local/cyberbit, and move the latter to/usr/local/texlive/texmf-local/fonts/enc/local/cyberbit. - The map file (cyberbit.map) goes to
/usr/local/texlive/texmf-local/fonts/map/local/cyberbit. - The things below are different: the file
c70cyberbit.fdshould be put in/usr/local/texlive/2014/texmf-dist/tex/latex/cyberbit, and the font file itself (cyberbit.ttf) should be in/usr/local/texlive/2014/texmf-dist/fonts/truetype/cyberbit. - One then adds a line
Map cyberbit.mapto/usr/local/texlive/texmf-local/web2c/updmap.cfg(or create the file if it doesn't exist). - Finally, execute
sudo -H mktexlsrand thensudo -H updmap-systo update the font maps used by LaTeX, and it's done! The way to call the cyberbit font in a tex file is, as usual,\begin{CJK}{UTF8}{cyberbit}.
I hope this note could be helpful for readers who are asked to use the annoying CJK package with the UTF-8 encoding. Let me know if you meet any problem and I'll try to answer your question if I know how to. I may expand this note as a self-contained post one day, but probably not recently...
ps. I found an excellent explanation on how CJK works, but it's written in simplified Chinese.
ps2. Although I could successfully include my Chinese name when compiling the tex file on my laptop, my tex file failed to pass APS's LaTeX compiler twice in a row during initial submission and resubmission. If you have a successful experience, please let me know how you managed. I appreciate it.
]]>[caption id="attachment_133" align="alignleft" width="300"]
Lara Fabian (from Wiki)[/caption]
歌手 Lara Fabian 加上法文歌 Je suis malade 就是我很愛的組合。我是最近才知道有 Lara 這位歌手，但聽了她幾首歌立刻就迷上她了。查了一下發現她大紅的時間點跟 Celine Dion 差不多 (90年代左右，他們還參加了同一屆的歐洲歌唱大賽)，而且跟 Celine Dion 也很像，首先她們都是能唱多國語言的女歌手，其次是我發現 Lara 的音域廣度跟 Celine 有得拼，而且歌曲風格也蠻多元的。Je suis malade 是她第二張專輯收錄的歌，雖然 Lara 並不是原唱 (原唱應該是 Dalida 在1973年唱的)，但應該可以算是她的代表曲。她在早期唱這首歌的唱法跟近期的版本差異相當大，可以聽到同一個歌手唱同一首歌如何隨著年紀增長而改變風格。Je suis malade 翻成英文意思是 I am sick (我生病了)，網路上有英文歌詞可以看，大部分會看我 blog 的人應該都不會說法文 (我也不會)，所以聽這首歌時我建議注意力放在 Lara 如何用飽滿的情緒撐起她的聲音，跟一般流行歌手不同，她的聲音是相當有表情的！以下我列出幾個 Youtube 上找得到的版本讓各位比較看看。
這應該是我能找到網路上最早期的演出，是我突然想聽這首歌的時候會第一個開來聽的版本。仔細聽她進副歌前如何「唸」歌詞唸出一種心理壓力很大、神經衰弱的感覺 (然後如何搖頭晃腦 XD)。
httpvh://www.youtube.com/watch?v=uGthVEza97U
查了一下似乎是 2003 的表演。不知道為什麼她在這個版本看起來特別傷心。最後的清唱很驚人。
httpvh://www.youtube.com/watch?v=dPOI7TRFdAY
這應該是較近期 (2010 後，詳細時間不確定) 的演出，風格看起來更像是一個生了重病的人在呻吟。在最後的副歌把麥克風拿得遠遠的，在這麼寬廣的音樂廳還能唱得這麼有力，真的很厲害。
httpvh://www.youtube.com/watch?v=DjLEVtm00-0
同場加映
另外一些較近期的演出版本
httpvh://www.youtube.com/watch?v=DTt5TQRawPs
httpvh://www.youtube.com/watch?v=snWD2yXzu-I
Lara跟小孩子合唱
httpvh://www.youtube.com/watch?v=2FckQePrlXM
Daniel Lévi 唱給台下的 Lara 聽
httpvh://www.youtube.com/watch?v=lqqUcw4LgBA
Serge Lama (作詞者) 的版本，其實我沒有特別喜歡他的版本，不過也是另一種截然不同的風格
httpvh://www.youtube.com/watch?v=isCJAxWtreY
Serge 和 Lara 對唱 (不愛 XD)
httpvh://www.youtube.com/watch?v=9pfX31PILJw
Update:
For Lara fans: 我找到Youtube上有人上傳完整版的節目。上面介紹的最早期的Je suis malade就是在這節目上唱的！
https://www.youtube.com/watch?v=tfTqWCdI6kE
]]>大嫂團則跑去紐約四處打卡兼血拼 XD
先來談談summer school好了
除去負責主辦的幾位學生很晚才寄行前通知這點讓我有點感冒之外
大致上辦得很不錯
10鎂包含了四天的課程和早午餐
算是物超所值 XD
(不過早餐是一堆bagel+coffee，中餐則是某種神奇的肉+pasta+花椰菜+可樂...我都不愛 Orz)
這次的主題是Quantum computation與Criticality
我覺得安排的不錯
各個講者的題目都或多或少互相有關連
像是Fendley (from Virginia)講完Conformal Field Theory之後
Sachdev (from Harvard)接著講AdS與CFT的關聯
或是Girvin (from Yale)先講quantum circuit
Houck (from Princeton)再接力補完circuit operation & simulation
(而且他們兩個講的題目剛好就是他們之前合作的幾個project!)
諸如此類的
更難能可貴的是幾乎所有講者都全程參與這四天的課程
所以他們很清楚什麼題材是別人已經提過
可以直接跳過講更深入的
在休息和午餐時間也都會跟學員們一起行動
因此大家有很多機會跟講者討論問題
(或是聽Sachdev跟Girvin等人大戰deterministic quantum mechanics做為飯後娛興節目 XD)
感覺蠻不錯的
(待續 XD)
]]>其實我還蠻偷懶的
因為這個題目根本就是幾年前上老闕古力課學的東西 :P
只是因為它可以用covariant formulation描述
所以才稍微跟電磁學扯上關係
不過話雖如此
我從期中考之後也花了好大一番功夫思考
如何把這個題目講的合理又好懂
還搬了一堆書回家查 XD
而且讓人扼腕的是
我只有十五分鐘可以報告
其中五分鐘是用來回答問題的
所以我準時在十分鐘結束時喊卡
(其他人都超過時間～哭哭)
結果只能講到導出古典流體力學為止.......
後面好多精采的(私以為 XD)都沒講到
不過反正自己邊準備也覺得好玩
就不管那麼多了
以下是我做的投影片
Relativistic Fluid Dynamics
而且跟他討論的時候他很堅持這答案是對的
完全不聽我解釋我的作法
因此後來我索性直接把文章寄給全班
事實上我們的算法是等價的
(而且是在凌晨五點自己發現的，哈哈)
但我不了解為什麼他只接受特定的作法
總之這件事已經告一段落了
我也認清跟某些人討論大多只是在浪費時間
效率實在不高
以下是我寫的兩篇文章
potential of a uniformly charged disk – part 1
potential of a uniformly charged disk – part 2