| Up | Next | Prev | PrevTail | Tail |
The git-based tutorials use two example git repositories called “independence.bundle” and “independence-sherman.bundle,” which can be downloaded from http://sourceforge.net/projects/latextrack/files/examples/. First, save the bundled repositories into a directory of your choice. We call this directory $TUTORIAL. Then, clone from the first bundle to obtain a valid git working tree.
Now we impersonate John Adams to work on this writing project for the Declaration of Independence.
Another way to investigate the current git repository are graphical tools such as gitk (comes with git distribution) or GitX under Mac OS X. Note that GitX is not required to run LTC. Figure 2.1 for using GitX on the just created repository.
The other point to note here is the way that GitX displays the changes in the file independence.tex when using the graphical git interface. It shows the lines in the file that have changed (much like a standard Unix diff would) – however, when looking at changes in LaTeX source code, the granularity of the line-based difference is much too coarse. An author would most likely only care about the change in words of line 15 or even characters such as removing the mistaken ‘d’ in the word “Roger” in line seven.
Collaboration on your writing project mainly happens through git so we show how to setup an example here. Your actual setup for writing projects may differ. Whatever the configuration, it will probably show up under the list of registered remotes for your repository. In our example, we cloned from the downloaded .bundle file, so looking at the remotes will look like this:
As an example of interacting with another repository, let us create a second one on our local file system. In practice, the remote repository will most likely be on a different computer and accessed via certain network protocols reflected in the address. Feel free to adjust the file locations in the example below to your taste.
Now we impersonate Roger Sherman in the newly created repository above, and also check the setting for its remotes.
Next, we make the first repository aware of the second and vice versa. At the same time, we may want to remove the reference to the original bundle so as to not get confused with which repository to synchronize. So in both repositories do
Then, we go into the first one and add a new remote location there:
Afterwards, we go into the second one and add a new remote location there:
Now you can pull from each directory what the other person has done. Notice that you cannot push changes to the other directory, as these git repositories are not “bare.” This means, they contain working copies and thus cannot be altered remotely. However, in most situations you may be using a central repository (such as GitHub or a server) that indeed contains a bare repository. Then, you are typically able to pull and push changes with such a remote repository while your coauthors can do the same to synchronize your work.
We will see examples below in Sections 2.2.7 and 2.3.7 how John Adams and Roger Sherman synchronize changes with each other.
In this section, we assume that the example git repository has been created according to the instructions in Section 2.1 above. And we assume that LTC has been installed using the Emacs directory, as well as Emacs configuration adjustments made that are mentioned in Section 1.3.3.
First, we start the LTC Server from the command line. Assuming you have installed LTC in the directory $LTC, we run this command line for the server. The output will be similar to the following. Leave the server running while performing the rest of this tutorial.
Next, we switch to Emacs and open the tutorial file $TUTORIAL/independence/independence.tex. This should put Emacs into latex-mode but any other mode should work as well. Then, start LTC mode using the command M-x ltc-mode in Emacs. You will see a few messages appearing briefly in the mini buffer (you can also look at them in the *Messages* buffer), such as the following.
Emacs should now look similar to the screen shot in Figure 2.2.
In this figure, we see the changes marked up in various colors and fonts: underlined for additions and inverse for deletions. There is also a smaller buffer called “LTC info (session N)” with N as the session ID, at the bottom (or the right, if your Emacs is in landscape mode) of the buffer with the tutorial file. There, we display the history of the current file under git. We can also see what git currently perceives as the current user at the top of the graph – now John Adams because we had overridden the git settings in this tutorial repository.
The LTC menu and “LTC info” buffer in Emacs allow us to customize the way LTC displays the changes of the file. Section 3.3 contains all the details of how LTC displays the changes including limiting the file history and filtering. In this tutorial, we will just use some of the options and see their effect.
First, notice the colors assigned to each of the authors. To change an author color, for example Roger Sherman’s, perform a single left-click on the name of Roger Sherman. This opens another buffer called *Colors* with a preview of colors and their names. Also look at the mini buffer that requests input. You can enter a name or an RGB value in hex notation. The color names can also be auto-completed, for example type Bro<TAB> (if TAB is your completion key in Emacs) to see Brown. You will want something with contrast to the white background, so brown is a fine choice. When clicking the RETURN key, notice how the text in the editor panel on the top changes color for those parts that are attributed to Roger Sherman’s edits. To abort choosing a color simply enter an empty value.
Next, focus on the typographical errors in the command “\maketitle” in line 11 and the beginning of the first paragraph in line thirteen as well as the spelling errors in the word “political.” Open the LTC menu (in the menu bar and in the mode line) and then the sub-menu “Show/Hide” as seen in Figure 2.3.
If you first uncheck the item LTC ⊳ Show/Hide ⊳ Show small changes , and second, also the item LTC ⊳ Show/Hide ⊳ Show deletions , notice how the text rendering in the editor panel changes.
Figures 2.4 show that “\maketitle” as well as the typos in the word “political” are no longer marked up, and in the third image, the deletion beginning with “If” at the beginning of the paragraph is now omitted.
Now draw your attention back to LTC info buffer with the history of the current file under git (located at the bottom or right of your tracked file). The Emacs representation is using small box characters to draw the graph and its edges. In our current tutorial repository, there are no branches and the graph is a sequential line.
Refer to Figure 2.5 for a screen shot of the example file history. Versions that are included in the tracked changes are not printed in gray. How far we go back in history depends on some filtering settings, which are discussed further in Section 2.2.4 below. By default, we first include all version of the current author at the top. In our example with impersonating John Adams, there are currently no further recent commits of him. Then, we continue down the path and collect all versions of different authors until we find the next version of John Adams in the commit with the message “second version.”
We allow the user to filter and customize how the potentially rich history of a .tex file is selected, so as to provide a better view of the tracked changes. The user can show and hide changes as seen above, limit the authors of interest, and specify a date or revision number to tell LTC how far back in time the history should be considered.
To limit the history by authors, choose menu item LTC ⊳ Limit by ⊳ Set of authors... . This will prompt the user to enter author names to limit by in the mini buffer. Again, automatic completion works, so you can enter Ro<TAB> <RET> and Th<TAB> <RET> <RET> to select authors Roger Sherman and Thomas Jefferson and exit the dialog. After the last author was selected, the system automatically updates the displayed changes.
Notice how any version by the ignored authors Benjamin Franklin and John Adams is now gray as only commits from the selected authors are considered. The first line in the LTC info buffer still shows the currently active author John Adams, so this line is not gray. Again, the history is only taken until the next revision of the current author but since he is being ignored, we go all the way back to the first revision. Compare your Emacs now with the screen shot in Figure 2.6 and see how the file history has changed.
To reset limiting by authors, simply choose the same menu LTC ⊳ Limit by ⊳ Set of authors... again and enter an empty author as the first one. Now the display is back in the original state.
Next, we apply limits on revision and date to control how far back the history of the file is considered. As we had seen, the first version is not taken into account because it was committed before the next commit by the current author John Adams. Let us now choose menu item LTC ⊳ Limit by ⊳ Start at revision... . This will prompt the user to specify a known revision number. Type the first few characters d6d<RET> of the SHA-1 key of the first commit. If unique, it is not necessary to expand the revision number using the TAB key (or whatever key is used for completion in your Emacs configuration). See how the first version is listed in color and considered in the tracked changes above as seen in Figure 2.7. Since changes by the current author John Adams from the first to the second version are now included, notice the text marked up in red appearing in the editor window. We see that John Adams must have added himself as an author in the LaTeX preamble among other edits in the second commit of the file.
Another way of limiting by revision number is to simply left-click the number in the display.
To remove the limit by revision number, simply choose the same menu LTC ⊳ Limit by ⊳ Start at revision... again and enter an empty revision. Or, click into the empty revision column of the first line (denoting the currently active author) to achieve the same effect. Now the display is back in the original state.
Limiting the history by date works similarly. Select menu item LTC ⊳ Limit by ⊳ Start at date... . At the prompt, you can enter a date from the history of the file using auto-completion. For example, enter 2<TAB>11<TAB> <RET> to get the exact date of the third revision. Or, type a date such as Jul 23, 2010 1:11p (should yield the same results if you are in the Central Time Zone) into the field. We employ some software to process times and dates in natural language, and if successful, the field will contain the date string as it was understood translated into the format used in the commit tree. You may also perform a left-click on the date in the history to achieve the same effect. See Figure 2.8 for a screen shot of the effect of limiting to the date of the third revision.
To remove the limit by date, either left-click on the empty date column of the first line of the file history or enter an empty date after selecting menu item LTC ⊳ Limit by ⊳ Start at date... again.
Sometimes the list of commits considered is getting long and the resulting markup of the changes confusing. One additional way to customize how the changes are displayed is a setting to “condense authors.” Now check the menu Condense authors ⊳ Other settings LTC. Then, only the latest version of an author of consecutive commits is considered – in our example, only the sixth version is colored while the fifth version by Roger Sherman is now grayed out as seen in Figure 2.9.
See Figure 2.10 for an example of how condensing authors affects the markup. Since we are only considering the changes that Roger Sherman made in the sixth version, his correction of the name is no longer shown. Condensing authors makes sense when users commit versions often so that they do not loose too much history. Their last version after a number of commits generally has the flavor of a “final” version, ready to be shared with others. Hence, the changes made there compared to the last version of another author is commonly of most interest.
Let us start the next step by resetting all filters to the default configuration, i.e., no limit by authors, date, and revision. Then, we will edit the text in the top buffer to see the latest changes.
Click into the text buffer and enter some text, for example a LaTeX comment reminding John Adams to work on a list of charges against King George III in line nineteen:
The added text will be rendered in red (or the color code for the current author) and underlined. Notice how the commit graph displays the label “modified” in the revision column of the first line of the file history. The mode line of Emacs also displays the symbol ** to denote a modified buffer. Now delete some of the characters you have just entered, for example the word here at the end. The characters simply disappear as they were added by the same author.
Now delete other characters that are either rendered black or a different color than red but not marked as deletions (inverse color). Notice how these characters remain visible but are now colored red and marked up with inverse colors. If you tried to delete anything that is already marked as deletion (i.e., anything in inverse color), nothing will happen as this text is already deleted in a prior version. See Figure 2.11 for a screen shot of the above edits: text in red and underlined was added and text in inverse red was deleted.
Finally, you will want to save the current file to disk. This will cause the label “modified” to change to “on disk” after saving in Emacs, for example with C-x s. If you would then again edit, the label would switch back to “modified” of course.
Saving the file, however, does not tell git to create a new version under its management. In order to commit the current file to git, first, make sure that the .tex file is saved under Emacs and the first line of the commit graph does not say “modified.” Then, on a command line, switch to the directory with the tutorial file and perform the following commit command (printed in bold below). You may want to check the status of git before and after the commit:
To make Emacs aware of the underlying commit, use menu item LTC ⊳ Update buffer or use the command M-x ltc-update. Notice how the recent commit gets included at the top of the list as seen in Figure 2.12.
Next we perform an example collaboration with Roger Sherman’s example repository as setup in Section 2.1.1 above. Remember that Roger Sherman’s repository has had two more commits than the original one we used for John Adams. Since we have made edits and commits as John Adams, both repositories have diverged. To synchronize them, we first pull Roger Sherman’s changes into our working copy after checking that we are in a good state:
Unfortunately, the two repositories have diverged too much and a so-called “merge conflict” has arisen. Now we have to tell git how to fix this before we can proceed. Next, we look at the markers that git has put into our file. You can run M-x ltc-update in Emacs to see these markers as seen in Figure 2.13. On the command line, the file looks similar to this:
We decide that the comment in the version HEAD means the same as the last comment in the merged version 39cd617... so we modify the text so that it looks like this:
It is important to remove the git marker lines starting with <<<<<<<, =======, and >>>>>>> for git to recognize that we have resolved the conflicts. Now committing on the command line yields:
This has resolved the conflict and incorporated Roger Sherman’s prior changes, as a look at the git log with the graphing function reveals:
Once we update Emacs using for example M-x ltc-update, we see the paragraph that was part of the conflicting region now correctly attributed to Roger Sherman. Furthermore, the git commit graph has gotten more interesting with the branching and merging symbolized by parallel vertical lines and empty rows for connecting them at merge points. Refer to Figure 2.14 for a screen shot of the git commit graph and text changes after resolving the conflict, committing and updating Emacs.
One thing to notice in the commit graph with branches is the grayed out row of the commit 8629257 that we had performed just a little while ago as John Adams. When we obtain the history of the file and one commit has more than one ancestor (a merge point), we walk the branch that has the older commit time in order to create a sequential path through the commits. In the future, we want to allow the user to select the branch to use or even overlay parallel branches for better control of the system. You can watch ticket #15 for when we address this problem.
Next we make sure to tell Roger Sherman about our effort to merge changes in the current document. He will want to pull our effort using the following commands.
A look at the git graph on the command line shows that the merge has been applied without conflict.
Now both can continue working on their versions but to prevent future merge conflicts it would be wise if they told each other immediately about newer versions and devised a plan to edit the file at different times. In larger writing projects, we recommend to break up the document into smaller .tex files to be included in a master .tex file. Then, editing different files at the same time for multiple authors minimizes the risk of merge conflicts.
In this section, we assume that the example git repository has been created according to the instructions in Section 2.1 above.
First, we start the LTC Editor to interact with LTC and track the changes of the file. Assuming you have installed LTC in the directory $LTC, we can look at the command line options of the editor:
To open our tutorial file at $TUTORIAL/independence/independence.tex when starting the editor, execute the following command. This will open the editor as a window similar to the screen shot in Figure 2.15.
In this figure, we see a panel at the bottom-right that resembles the upper part of the GitX graphical interface to git. There, we display the history of the current LaTeX file under git. We can also see what git currently perceives as the current user – now John Adams because we had overridden the git settings in this tutorial repository.
The bottom-left panels of the editor allows us to customize the way LTC displays the changes of the file. Section 3.3 contains all the details of how LTC displays the changes including limiting the file history and filtering. In this tutorial, we will just use some of the options and see their effect.
First, notice the colors assigned to each of the authors. To change an author color, for example Roger Sherman’s, perform a double-click on the colored square next to Roger Sherman in the list of authors to open a dialog and choose a dark color such as brown (you will want something with contrast to the white background). Notice how the text in the editor panel on the top changes color for those parts that are attributed to Roger Sherman’s edits.
Next, focus on the typographical errors in the command “\maketitle” in line 11 and the beginning of the first paragraph in line thirteen as well as the spelling errors in the word “political.” If you first uncheck the box for “small” changes and second, also the box for deletions, notice how the text rendering in the editor panel changes.
Figures 2.16 show that “\maketitle” as well as the typos in the word “political” are no longer marked up, and in the third image, the deletion beginning with “If” at the beginning of the paragraph is now omitted.
Now draw your attention back to the graph with the history of the current file under git (located in the bottom-right panel). In our current tutorial repository, this graph is just a line as the authors committed their versions in sequential order.
Refer to Figure 2.17 for a screen shot of the example file history. The first line always contains the current author. Then, revisions that are included in the tracked changes are printed in black and denoted with a filled circle. How far we go back in history depends on some filtering settings, which are discussed further in Section 2.3.4 below. By default, we first include all versions of the current author at the top. In our example with impersonating John Adams, there are currently no further recent commits of him. Then, we continue down the path and collect all versions of different authors until we find the next version of John Adams in the commit with the message “second version.”
We allow the user to filter and customize how the potentially rich history of a .tex file is selected, so as to provide a better view of the tracked changes. The user can show and hide changes as seen above, limit the authors of interest, and specify a date or revision number to tell LTC how far back in time the history should be considered.
To limit the history by authors, select both authors Roger Sherman and Thomas Jefferson through clicking while holding down the CTRL or CMD key in the list of authors in the middle lower panel. Then, click the button “Limit” below the list, which will gray out the unselected authors. For a limiting action to take effect, you need to click “Update.” This is different from showing and hiding various changes as well as changing author colors, which is applied instantly.
Notice how any version by the ignored authors Benjamin Franklin and John Adams is now gray as only commits from the selected authors are considered. Again, the history is only taken until the next revision of the current author but since he is being ignored, we go all the way back to the first revision. Compare your editor window with the screen shot in Figure 2.19 and see how the commit graph has changed.
Then, clicking the “Reset” button followed by “Update” will remove and limits on the history by author, so the original view is restored.
Next, we apply limits on revision and date to control how far back the history of the file is considered. As we had seen, the first version is not taken into account because it was committed before the next commit by the current author John Adams. Let us now type the first few characters d6d of the SHA-1 key of the first commit into the field labeled “Start at revision:” (refer to Figure 2.20) or simply drag the key from the entry in the commit graph, which will copy the complete SHA-1 sequence. Now click “Update” and see how the first version is listed in black and considered in the tracked changes above as seen in Figure 2.21. Since changes by the current author John Adams from the first to the second version are now included, notice the text marked up in red appearing in the editor window. We see that John Adams must have added himself as an author in the LaTeX preamble among other edits.
To remove the limit by revision number, simply erase the text in the field “Start at revision:” and click “Update” again.
Limiting the history by date works similarly. You may drag a date from the commit graph on the right, for example the date of the third version commit, and drop it into the field “Start at date:” on the left. Or, type a date such as Jul 23, 2010 1:11p into the field. We employ some software to process times and dates in natural language, and if successful, the field will contain the date string as it was understood translated into the format used in the commit tree. Again, you will need to click “Update” for the change to take effect or click RETURN while editing the text field. See Figures 2.22 and 2.23 for screenshots. To remove the limit by date, erase all text in the text field and update.
Sometimes the list of commits considered is getting long and the resulting markup of the changes confusing. One additional way to customize how the changes are displayed is a setting to “condense authors.” Find a check box with that name under the list of authors for filtering. If checked, then only the latest version of an author of consecutive commits is considered – in our example, only the sixth version is shown in black while the fifth version by Roger Sherman is now grayed out as seen in Figure 2.24.
See Figure 2.25 for an example of how condensing authors affects the markup. Since we are only considering the changes that Roger Sherman made in the sixth version, his correction of the name is no longer shown. Condensing authors makes sense when users commit versions often so that they do not loose too much history. Their last version after a number of commits generally has the flavor of a “final” version, ready to be shared with others. Hence, the changes made there compared to the last version of another author is commonly of most interest.
Let us start the next step by resetting all filters to the default configuration, i.e., no limit by authors, date, and revision. Also make sure to turn “condense authors” off. Then, we will edit the text in the editor panel to see the latest changes.
Click into the text panel and enter some text, for example a LaTeX comment reminding John Adams to work on a list of charges against King George III in line nineteen:
The added text will be rendered in red (or the color code for the current author) and underlined. Notice how the commit graph adds a first line with the label “modified” and the “Save” button becomes enabled. Now delete some of the characters you have just entered, for example the word here at the end. The characters simply disappear as they were added by the same author.
Now delete other characters that are either rendered black or a different color than red but not marked as deletions (strike-through font). Notice how these characters remain visible but are now colored red and marked up with strike-through. If you tried to delete anything that is already marked as deletion (i.e., anything in strike-through font), nothing will happen as this text is already deleted in a prior version. See Figure 2.26 for a screen shot of the above edits: text in red and underlined was added and text in red and strike-through was deleted.
Finally, you will want to click “Save” to save the current file to disk. This will cause the label “modified” to change to “on disk.” If you would then again edit, the label would switch back to “modified” of course.
Saving the file, however, does not tell git to create a new version under its management. In order to commit the current file to git, first, make sure that the .tex file is saved and the first line in the commit graph is set to “on disk.” Then, on a command line, switch to the directory with the tutorial file and perform the following commit command (printed in bold below). You may want to check the status of git before and after the commit:
To make LTC Editor aware of the underlying commit from the command line, click the “Update” button. Notice how the recent commit gets included at the top of the list as seen in Figure 2.27. Also see that we still include all revisions up to John Adams’ second revision a while ago—all revisions at the top of the graph before any other authors are skipped before looking for the default end point in history.
Now two things can happen depending on your setting for showing changes in comments (lower-left most panel). If the checkbox was off, the newly added comment is no longer marked up in red with underlining. After updating the editor from the commit history, the settings of which changes to show influence the markup of the text. Now the newly entered comment is recognized as such, and if we hide changes in comments, the markup will not show. If the box for “changes in comments” is checked, you will see your latest text still marked up as an addition. Your editor should now look similar to the part shown in either Figure 2.28 or Figure 2.29.
Next we perform an example collaboration with Roger Sherman’s example repository as setup in Section 2.1.1 above. Remember that Roger Sherman’s repository has had two more commits than the original one we used for John Adams. Since we have made edits and commits as John Adams, both repositories have diverged. To synchronize them, we first pull Roger Sherman’s changes into our working copy using the git pull command below:
Unfortunately, the two repositories have diverged too much and a so-called “merge conflict” has arisen. Now we have to tell git how to fix this before we can proceed. So we look at the markers that git has put into our file. You can click the “Update” button in LTC Editor to see these markers there similar to Figure 2.30. On the command line, the file looks similar to this:
We decide that the comments in the HEAD version means the same as the last comment in the merged version 39cd617... so we modify the text so that it looks like this:
It is important to remove the git marker lines starting with <<<<<<<, =======, and >>>>>>> for git to recognize that we have resolved the conflicts. Notice that if you are editing in LTC Editor, all changes are currently marked up in the color of John Adams even though we imported a paragraph from Roger Sherman. This is because we still have not committed the changes to git and the current version on disk is attributed to John Adams. However, we now save and then commit on the command line:
This has resolved the conflict and incorporated Roger Sherman’s prior changes, as a look at the git log with the graphing function reveals:
Once we update LTC Editor, we see the paragraph that was part of the conflicting region now correctly attributed to Roger Sherman. Furthermore, the git commit graph has gotten more interesting with the branching and merging in the first column of the commit graph. Refer to Figure 2.31 for a screen shot of the git commit graph and text changes after resolving the conflict, committing and updating LTC Editor.
This tutorial uses an example svn repository, which is either hosted on the Internet or on your local computer. The first Section 2.4.1 shows how to use a publicly accessible repository with an example file. This is the quickest way to try out LTC with Subversion but you cannot commit new versions to this repository so we cannot go through such advanced topics in the later parts of the tutorial. The second Section 2.4.2 shows how to create a local svn server and populates it with an example repository. This takes a bit more time to setup but then you can go through more advanced topics such as committing to the repository.
To create the example file that is under remote svn version control, go into a directory of your choice (say $TUTORIAL) and do the following. If the server causes a certificate alert, you can accept it permanently by using p as shown in bold below.
Now change into the new directory and confirm that the file has six revisions in its history
Unfortunately, we cannot accept changes to this repository so the tutorials based on svn do not cover how to commit new revisions and how to collaborate. We advise to install a local svn server and repository per the instructions below or to go through the git-based tutorial to cover those points.
The following will show you how to run a local subversion server on your machine. Then, we will create a subversion repository there and add a few users to it, so that you can impersonate different users throughout the later parts of the tutorial below.
First, perform the following steps from a directory of your choice. We assume that this is again $TUTORIAL. There, you will create the root location of your tutorial repositories called svnrepos. You may choose another name but will then have to adjust the commands accordingly.
Now edit the two files
to contain the following lines:
Finally, start the SVN server in daemon mode using:
Now download the file tutorialsvn.dump from http://sourceforge.net/projects/latextrack/files/examples/ to, say, directory $TUTORIAL and load the repository into your server:
Now, we will check out from this repository in a new directory, say independence. If you see a message svn: Can’t connect to host ’localhost’: Connection refused then most like the SVN server process is not running. Restart the server with the svnserve command above.
Collaboration on your writing project happens through the subversion repository so here we show you how to set up an example with a secondary checkout that Roger Sherman uses. You will need to download an additional file independence-sherman.tex from http://sourceforge.net/projects/latextrack/files/examples/, for example to the directory $TUTORIAL.
Now do the following to create the secondary repository with a new version of the file that is not yet committed.
To clean up when you are done with the tutorial, you should stop the running svn server process by finding out the process ID <PID> as seen below. Then, replace it in the kill command before deleting the files associated with the repository.
Finally, you will also want to remove the working copies you had made from the now deleted local repository:
In this section, we assume that the example svn repository has been created according to the instructions in Section 2.4 above. The latter subsections require a local svn repository but the beginning can be done with either the remote example repository or a local one. And we assume that LTC has been installed using the Emacs directory, as well as Emacs configuration adjustments made that are mentioned in Section 1.3.3.
First, we start the LTC Server from the command line. Assuming you have installed LTC in the directory $LTC, we run this command line for the server. The output will be similar to the following. Leave the server running while performing the rest of this tutorial.
Next, we switch to Emacs and open the tutorial file $TUTORIAL/independence/independence.tex. This should put Emacs into latex-mode but any other mode should work as well. Then, start LTC mode using the command M-x ltc-mode in Emacs. Beware that using LTC with a remote subversion server takes longer than using git or a local subversion server, as we have to query the distant server hosting the repository for each version of the .tex file. You will see a few messages appearing briefly in the mini buffer (you can also look at them in the *Messages* buffer), such as the following. While the potential time intensive task of downloading versions from the remote server happen, the mini buffer should say Starting LTC update..., which turns into LTC updates received when the process is done.
Emacs should now look similar to the screen shot in Figure 2.32.
In this figure, we see the changes marked up in various colors and fonts: underlined for additions and inverse for deletions. There is also a smaller buffer called “LTC info (session N)” with N as the session ID, at the bottom (or the right, if your Emacs is in landscape mode) of the buffer with the tutorial file. There, we display the history of the current file under svn. We can also see what svn perceives as the current user at the top of the graph – here the name of the local user.
First, we will override what LTC thinks is the current author in order to make the following tutorial more meaningful. In real life situations you will rarely have to use this command as you typically want the changes in the repository attributed to yourself. In Emacs, type the command M-x ltc-set-self<RET>adams<RET> to impersonate John Adams. This updates the contents in the main buffer and info buffer at the bottom automatically, which may again take a little time with a remote subversion server. The info buffer will then look like the screen shot in Figure 2.33.
The LTC menu and “LTC info” buffer in Emacs allow us to customize the way LTC displays the changes of the file. Section 3.3 contains all the details of how LTC displays the changes including limiting the file history and filtering. In this tutorial, we will just use some of the options and see their effect.
First, notice the colors assigned to each of the authors. To change an author color, for example Roger Sherman’s, perform a single left-click on the name of Roger Sherman. This opens another buffer called *Colors* with a preview of colors and their names. Also look at the mini buffer that requests input. You can enter a name or an RGB value in hex notation. The color names can also be auto-completed, for example type Bro<TAB> (if TAB is your completion key in Emacs) to see Brown. You will want something with contrast to the white background, so brown is a fine choice. When clicking the RETURN key, notice how the text in the editor panel on the top changes color for those parts that are attributed to Roger Sherman’s edits. To abort choosing a color simply enter an empty value.
Next, focus on the typographical errors in the command “\maketitle” in line 11 and the beginning of the first paragraph in line thirteen as well as the spelling errors in the word “political.” Open the LTC menu (in the menu bar and in the mode line) and then the sub-menu “Show/Hide” as seen in Figure 2.34.
If you first uncheck the item LTC ⊳ Show/Hide ⊳ Show small changes , and second, also the item LTC ⊳ Show/Hide ⊳ Show deletions , notice how the text rendering in the editor panel changes. Again, if you work with the remote repository, it might take a little while until all the updates are received from the server and the mini buffer shows the message “LTC updates received.”
Figures 2.35 show that “\maketitle” as well as the typos in the word “political” are no longer marked up, and in the third image, the deletion beginning with “If” at the beginning of the paragraph is now omitted.
Now draw your attention back to LTC info buffer with the history of the current file under svn (located at the bottom or right of your .tex file). The Emacs representation is using small box characters to draw the graph and its edges. In our current tutorial repository, there are no branches and the graph is a sequential line.
Refer back to Figure 2.33 for the screen shot of the example file history. Versions that are included in the tracked changes are not printed in gray. How far we go back in history depends on some filtering settings, which are discussed further in Section 2.5.4 below. By default, we first include all version of the current author at the top. In our example with impersonating John Adams with the user name “adams,” there are currently no further recent commits of him. Then, we continue down the path and collect all versions of different authors until we find the next version of John Adams in the commit with the message “second version.”
We allow the user to filter and customize how the potentially rich history of a .tex file is selected, so as to provide a better view of the tracked changes. The user can show and hide changes as seen above, limit the authors of interest, and specify a date or revision number to tell LTC how far back in time the history should be considered.
To limit the history by authors, choose menu item LTC ⊳ Limit by ⊳ Set of authors... . This will prompt the user to enter author names to limit by in the mini buffer. Again, automatic completion works, so you can enter sh<TAB> <RET> and je<TAB> <RET> <RET> to select authors “sherman” and “jefferson” and exit the dialog. After the last author was selected, the system automatically updates the displayed changes.
Notice how any version by the ignored authors “franklin” and “adams” is now gray as only commits from the selected authors are considered. The first line in the LTC info buffer still shows the currently active author “adams,” so this line is not gray. Again, the history is only taken until the next revision of the current author but since he is being ignored, we go all the way back to the first revision. Compare your Emacs now with the screen shot in Figure 2.36 and see how the file history has changed.
To reset limiting by authors, simply choose the same menu LTC ⊳ Limit by ⊳ Set of authors... again and enter an empty author as the first one. Now the display is back in the original state.
Next, we apply limits on revision and date to control how far back the history of the file is considered. As we had seen, the first version is not taken into account because it was committed before the next commit by the current author John Adams. Let us now choose menu item LTC ⊳ Limit by ⊳ Start at revision... . This will prompt the user to specify a known revision number. Type 1 as the revision number of the first commit and hit ENTER. See how the first version is now listed in color and considered in the tracked changes above as seen in Figure 2.37. Since changes by the current author John Adams from the first to the second version are now included, notice the text marked up in red appearing in the editor window. We see that John Adams must have added himself as an author in the LaTeX preamble among other edits in the second commit of the file.
Another way of limiting by revision number is to simply left-click the number in the display of the commit graph.
To remove the limit by revision number, simply choose the same menu LTC ⊳ Limit by ⊳ Start at revision... again and enter an empty revision. Or, click into the empty revision column of the first line (denoting the currently active author) to achieve the same effect. Now the display is back in the original state.
Limiting the history by date works similarly. Select menu item LTC ⊳ Limit by ⊳ Start at date... . At the prompt, you can enter a date from the history of the file using auto-completion. For example, enter 2<TAB>2:59:0<TAB> <RET> to get the exact date of the third revision. Or, type a date such as Nov 13, 2012 12:59p (should yield the same results if you are in the Central Time Zone) into the field. We employ some software to process times and dates in natural language, and if successful, the field will contain the date string as it was understood translated into the format used in the commit tree. You may also perform a left-click on the date in the history to achieve the same effect. See Figure 2.38 for a screen shot of the effect of limiting to the date of the third revision.
To remove the limit by date, either left-click on the empty date column of the first line of the file history or enter an empty date after selecting menu item LTC ⊳ Limit by ⊳ Start at date... again.
Sometimes the list of commits considered is getting long and the resulting markup of the changes confusing. One additional way to customize how the changes are displayed is a setting to “condense authors.” Now check the menu LTC ⊳ Condense authors . Then, only the latest version of an author of consecutive commits is considered – in our example, only the sixth version is colored while the fifth version by Roger Sherman is now grayed out as seen in Figure 2.39.
See Figure 2.40 for an example of how condensing authors affects the markup. Since we are only considering the changes that Roger Sherman made in the sixth version, his correction of the name is no longer shown. Condensing authors makes sense when users commit versions often so that they do not loose too much history. Their last version after a number of commits generally has the flavor of a “final” version, ready to be shared with others. Hence, the changes made there compared to the last version of another author is commonly of most interest.
Let us start the next step by resetting all filters to the default configuration, i.e., no limit by authors, date, and revision. Then, we will edit the text in the top buffer to see the latest changes.
Click into the text buffer and enter some text, for example a LaTeX comment reminding John Adams to work on a list of charges against King George III in line nineteen:
The added text will be rendered in red (or the color code for the current author) and underlined. Notice how the commit graph displays the label “modified” in the revision column of the first line of the file history. The mode line of Emacs also displays the symbol ** to denote a modified buffer. Now delete some of the characters you have just entered, for example the word here at the end. The characters simply disappear as they were added by the same author.
Now delete other characters that are either rendered black or a different color than red but not marked as deletions (inverse color). Notice how these characters remain visible but are now colored red and marked up with inverse colors. If you tried to delete anything that is already marked as deletion (i.e., anything in inverse color), nothing will happen as this text is already deleted in a prior version. See Figure 2.41 for a screen shot of the above edits: text in red and underlined was added and text in inverse red was deleted.
Finally, you will want to save the current file to disk. This will cause the label “modified” to change to “on disk” after saving in Emacs, for example with C-x s. If you would then again edit, the label would switch back to “modified” of course.
In Subversion, your repository is a central entity that all collaborators commit to. Therefore, unlike distributed version control systems such as git, the collaboration happens when users commit their version. It is a good practice to update your working copy regularly to avoid conflicts during committing. Furthermore, users should communicate with each other to decide who is editing what file at a time.
The following assumes that you are working with a local svn repository per the setup in Sections 2.4.2 and sec:svn-collaborating above. Next, we will simulate that Roger Sherman commits his modified version before John Adams can upload his version, resulting in a merge conflict. To prepare this scenario, first commit the modifications from Roger Sherman’s working copy:
Now the shared repository is already at revision 7 while we (as John Adams) are still editing from revision six. First, check again that you have saved the file in Emacs and that the first entry in the commit graph says “on disk.” When we try to commit our latest changes from the Section 2.5.6 above, using the command line, we get the following error message.
Then, we try to update our repository first to mend the situation, which results in another error message about the conflicting versions. If Roger Sherman and John Adams had been modifying different .tex files in the same repository, we would have not gotten this conflict. To resolve, we choose to postpone so that we can see the differences in Emacs and resolve it there. Our input is marked in bold below.
Our current file is now marked as in conflict, so let us update Emacs using menu item LTC ⊳ Update buffer or M-x ltc-update, to see something similar to the screen shot in Figure 2.42. The conflicting portion at the end is marked with additional lines and we see revision 7 in the history of the file. On the command line, the file looks similar to this:
We decide that the comments in the version .mine version means the same as the last comment in version .r7 so we modify the text in Emacs and save, so that it looks like this on the command line:
It is important to remove the svn marker lines starting with <<<<<<<, =======, and >>>>>>> for svn to recognize that we have resolved the conflicts. We also have to tell svn that the conflict has been resolved. Then we can finally perform the following commit command. The two important commands are printed in bold below. You may want to check the status of svn before and after the commit:
Once we update Emacs using for example M-x ltc-update, we see the latest revision 8 in the commit graph and the marked up latest edits attributed to John Adams and Roger Sherman similar to Figure 2.43.
In this section, we assume that the example svn repository has been created according to the instructions in Section 2.4 above. The latter subsections require a local svn repository but the beginning can be done with either the remote example repository or a local one.
First, we start the LTC Editor to interact with LTC and track the changes of the file. Assuming you have installed LTC in the directory $LTC, we can look at the command line options of the editor:
To open our tutorial file at $TUTORIAL/independence/independence.tex when starting the editor, execute the following command. After the editor opens as a window, we open the combo box under the name for “Self:” by clicking on the small arrow right next to the name and select the author “adams” to impersonate John Adams for the remainder of this tutorial. This will again contact the server to obtain updates about the file history, which may take a little time if you are working with a remote repository. Finally, the window should look similar to the screen shot in Figure 2.44.
In this figure, we see a panel at the bottom-right that displays the history of the current LaTeX file under svn as well as the name of the current user – now John Adams because we had overridden the default, which was your user name.
The bottom-left panels of the editor allows us to customize the way LTC displays the changes of the file. Section 3.3 contains all the details of how LTC displays the changes including limiting the file history and filtering. In this tutorial, we will just use some of the options and see their effect.
First, notice the colors assigned to each of the authors. To change an author color, for example Roger Sherman’s, perform a double-click on the colored square next to “sherman” in the list of authors to open a dialog and choose a dark color such as brown (you will want something with contrast to the white background). Notice, after the updates have come through from the server, how the text in the editor panel on the top changes color for those parts that are attributed to Roger Sherman’s edits.
Next, focus on the typographical errors in the command “\maketitle” in line 11 and the beginning of the first paragraph in line thirteen as well as the spelling errors in the word “political.” If you first uncheck the box for “small” changes and second, also the box for deletions, notice how the text rendering in the editor panel changes.
Figures 2.45 show that “\maketitle” as well as the typos in the word “political” are no longer marked up, and in the third image, the deletion beginning with “If” at the beginning of the paragraph is now omitted.
Now draw your attention back to the graph with the history of the current file under svn (located in the bottom-right panel).
Refer to Figure 2.46 for a screen shot of the example file history. The first line always contains the current author as set in the text field labeled “Self” above. Then, revisions that are included in the tracked changes are not printed in gray. How far we go back in history depends on some filtering settings, which are discussed further in Section 2.6.4 below. By default, we first include all versions of the current author at the top. In our example with impersonating John Adams with the user name “adams,” there are currently no further recent commits of him. Then, we continue down the path and collect all versions of different authors until we find the next version of John Adams in the commit with the message “second version.”
We allow the user to filter and customize how the potentially rich history of a .tex file is selected, so as to provide a better view of the tracked changes. The user can show and hide changes as seen above, limit the authors of interest, and specify a date or revision number to tell LTC how far back in time the history should be considered.
To limit the history by authors, select both authors “sherman” and “jefferson” through clicking while holding down the CTRL or CMD key in the list of authors in the middle lower panel. Then, click the button “Limit” below the list, which will gray out the unselected authors. For a limiting action to take effect, you need to click “Update.” This is different from showing and hiding various changes as well as changing author colors, which is applied instantly.
Notice how any version by the ignored authors Benjamin Franklin and John Adams is now gray as only commits from the selected authors are considered. Again, the history is only taken until the next revision of the current author but since he is being ignored, we go all the way back to the first revision. Compare your editor window with the screen shot in Figure 2.48 and see how the commit graph has changed.
Then, clicking the “Reset” button followed by “Update” will remove and limits on the history by author, so the original view is restored.
Next, we apply limits on revision and date to control how far back the history of the file is considered. As we had seen, the first version is not taken into account because it was committed before the next commit by the current author John Adams. Let us now type 1 as the revision number of the first commit into the field labeled “Start at revision:” (refer to Figure 2.49) or simply drag the number from the entry in the commit graph into the field. Now click “Update” and see how the first version is listed in black and considered in the tracked changes above as seen in Figure 2.50. Since changes by the current author John Adams from the first to the second version are now included, notice the text marked up in red appearing in the editor window. We see that John Adams must have added himself as an author in the LaTeX preamble among other edits.
To remove the limit by revision number, simply erase the text in the field “Start at revision:” and click “Update” again.
Limiting the history by date works similarly. You may drag a date from the commit graph on the right, for example the date of the third version commit, and drop it into the field “Start at date:” on the left. Or, type a date such as Nov 13, 2012 12:59p into the field. We employ some software to process times and dates in natural language, and if successful, the field will contain the date string as it was understood translated into the format used in the commit tree. Again, you will need to click “Update” for the change to take effect or click RETURN while editing the text field. See Figures 2.51 and 2.52 for screenshots. To remove the limit by date, erase all text in the text field and update.
Sometimes the list of commits considered is getting long and the resulting markup of the changes confusing. One additional way to customize how the changes are displayed is a setting to “condense authors.” Find a check box with that name under the list of authors for filtering. If checked, then only the latest version of an author of consecutive commits is considered – in our example, only the sixth version is shown in black while the fifth version by Roger Sherman is now grayed out as seen in Figure 2.53.
See Figure 2.54 for an example of how condensing authors affects the markup. Since we are only considering the changes that Roger Sherman made in the sixth version, his correction of the name is no longer shown. Condensing authors makes sense when users commit versions often so that they do not loose too much history. Their last version after a number of commits generally has the flavor of a “final” version, ready to be shared with others. Hence, the changes made there compared to the last version of another author is commonly of most interest.
Let us start the next step by resetting all filters to the default configuration, i.e., no limit by authors, date, and revision. Also make sure to turn “condense authors” off. Then, we will edit the text in the editor panel to see the latest changes.
Click into the text panel and enter some text, for example a LaTeX comment reminding John Adams to work on a list of charges against King George III in line nineteen:
The added text will be rendered in red (or the color code for the current author) and underlined. Notice how the commit graph adds a first line with the label “modified” and the “Save” button becomes enabled. Now delete some of the characters you have just entered, for example the word here at the end. The characters simply disappear as they were added by the same author.
Now delete other characters that are either rendered black or a different color than red but not marked as deletions (strike-through font). Notice how these characters remain visible but are now colored red and marked up with strike-through. If you tried to delete anything that is already marked as deletion (i.e., anything in strike-through font), nothing will happen as this text is already deleted in a prior version. See Figure 2.55 for a screen shot of the above edits: text in red and underlined was added and text in red and strike-through was deleted.
Finally, you will want to click “Save” to save the current file to disk. This will cause the label “modified” to change to “on disk.” If you would then again edit, the label would switch back to “modified” of course.
In Subversion, your repository is a central entity that all collaborators commit to. Therefore, unlike distributed version control systems such as git, the collaboration happens when users commit their version. It is a good practice to update your working copy regularly to avoid conflicts during committing. Furthermore, users should communicate with each other to decide who is editing what file at a time.
The following assumes that you are working with a local svn repository per the setup in Sections 2.4.2 and 2.4.3 above. Next, we will simulate that Roger Sherman commits his modified version before John Adams can upload his version, resulting in a merge conflict. To prepare this scenario, first commit the modifications from Roger Sherman’s working copy:
Now the shared repository is already at revision 7 while we (as John Adams) are still editing from revision six. First, check again that you have saved the file in LTC Editor using the “Save” button and that the first entry in the commit graph says “on disk.” When we try to commit our latest changes from the Section 2.5.6 above, using the command line, we get the following error message.
Then, we try to update our repository first to mend the situation, which results in another error message about the conflicting versions. If Roger Sherman and John Adams had been modifying different .tex files in the same repository, we would have not gotten this conflict. To resolve, we choose to postpone so that we can see the differences in Emacs and resolve it there. Our input is marked in bold below.
Our current file is now marked as in conflict, so let us click the “Update” button in LTC Editor to see something similar to the screen shot in Figure 2.56. The conflicting portion at the end is marked with additional lines and we see revision 7 in the history of the file. On the command line, the file looks similar to this:
We decide that the comments in the version .mine version means the same as the last comment in version .r7 so we modify the text in LTC Editor and save, so that it looks like the following on the command line or as seen in the screen shot in Figure 2.57.
It is important to remove the svn marker lines starting with <<<<<<<, =======, and >>>>>>> for svn to recognize that we have resolved the conflicts. We also have to tell svn that the conflict has been resolved. Then we can finally perform the following commit command. The two important commands are printed in bold below. You may want to check the status of svn before and after the commit:
Once we click the “Update” button in LTC Editor, we see the latest revision 8 in the commit graph and the marked up latest edits attributed to John Adams and Roger Sherman similar to Figure 2.58. Also see that we still include all revisions up to John Adams’ second revision a while ago—all revisions at the top of the graph before any other authors are skipped before looking for the default end point in history.
| Up | Next | Prev | PrevTail | Front |
