ShareLaTeX and GitHub

Published on January 20, 2015.

Update

This blog post was update in January 20th with excerpts from a email that James Allen send to me.

In this post I will test the bridge between ShareLaTeX and GitHub focusing at dealing with conflicts.

Create Repository at GitHub

The first step was create a Git repository at GitHub to use for this test.

{width=“80%”}

If you already used GitHub this should be easy. I created https://github.com/r-gaia-cs/testing-sharelatex and added https://github.com/abelsiqueira/abelsiqueira.github.io/blob/master/disciplinas/topal2015/ex2015-01-06.tex to it.

Import Repository at ShareLaTeX

The second step was import the Git repository at ShareLaTeX.

{width=“80%”}

Clicking on “New Project” you will find “Import from GitHub”.

Note

This option is only available for paid subscriptions.

{width=“80%”}

The first time that you use this option you will need to authorise ShareLaTeX to access your GitHub account.

{width=“80%”}

After you authorise ShareLaTeX to access your GitHub account you can click again on “New Project” and “Import from GitHub”. You will find a list of all your GitHub repositories and just have to select the one you want to import.

{width=“80%”}

After import your project you can edit it using ShareLaTeX’s web IDE.

{width=“80%”}

Create New Revision on ShareLaTeX

To create a new revision on ShareLaTeX you need to:

  1. Open the menu of the web IDE (at the top left corner).

{width=“80%”}

  1. Select “GitHub”.

{width=“80%”}

  1. Select “Push ShareLaTeX changes to GitHub”.

{width=“80%”}

  1. Write the commit message.

And that’s all. You can download the new revision to your local machine as you always do, e.g. git fetch or git pull.

BUG

If you try to create a new revison without change any file Git will not allow you to do that:

$ git commit -m 'Without change'
On branch master
Your branch is up-to-date with 'origin/master'.
nothing added to commit but untracked files present

For some reason GitHub allow a new revision without any change:

$ git show HEAD
commit 30f4a3abe26bb79e662acf3c965b6332ddf56f71
Author: Raniere Silva <raniere@ime.unicamp.br>
Date:   Tue Jan 20 00:53:26 2015 -0200

    Empty commit

James informed me that:

The offer to ‘push’ even though there aren’t any changes is simply because we don’t have a simple way to detect if any changes have actually been made, at least not without adding a lot of complexity to our backend.

So we made the call to get something out that worked and was useful to people. Even though these things can create an odd user experience in certain cases, they hopefully won’t stop it being usable.

Import New Revision

Note

Here I will cover the case that has a conflict since it is the generic case.

To update your project on ShareLaTeX you need to:

  1. Open the menu of the web IDE (at the top left corner).

{width=“80%”}

  1. Select “GitHub”.

{width=“80%”}

  1. Select “Pull GitHub changes into ShareLaTeX”.

{width=“80%”}

  1. Manually merge the revisions. This can’t be done at the web IDE.
  2. Select “I have manually merged. Continue”.

BUG

ShareLaTeX isn’t smart enough to check if you realy fix the conflict and merge the versions. If you say that you merged the changes he will believe in you and use the version from GitHub without changes. Yes, you will “lose” the work that you do at the web IDE.

James informed me that:

When it comes to overwriting changes made in ShareLaTeX, these will still be available in the track changes (we version every change to a document in ShareLaTeX ourselves as well), and can be rolled back if a mistake happens with the manual merge.

To get the change track made by ShareLaTeX you need to select the “Recent Changes” option at the top left corner of the web IDE.

{width=“80%”}

And if you wish you can restore your document.

  1. Write the commit message.

BUG

For some reason, after pull the changes ShareLaTeX ask you to push the changes. This don’t create any aditional commit.

Conclusions

Note

James’ “final words” about the bugs was:

The bugs you mention are spot on, and something we’re aware of. There are both there by design, at least in the sense that we had to make some compromises given the features available in the GitHub API, and to stop the complexity spiralling out of control.

Have this bridge is a nice feature but in my opinion this will not solve the problem of collaborating with someone that don’t know Git because many times it require to resolve the conflicts locally and allow user to lie about had resolve the conflict in a way that looks like lose the work done.

Since this feature still in beta I hope that ShareLaTeX team improve it in the sort future.

Tags: