Learning git (for svn users)

Since I had to start programming for gnome, I had to start learning how to use git. I had heard of git before, about all its wonders… but I was ok with svn, I knew how to work with it and all the other projects I was working on were using svn. Of course these projects did not have hundreds or thousands of collaborators 😉

It was a rough patch in the beginning, and I still struggle with conflicts and rebasing and such from time to time, but it’s getting better. I decided to write this for svn users that suddenly had to change to git, since the shift, at least for me, was not so straightforward as some people claim.

This need to be *really* clear:

git commits are *not* svn commits.

git checkouts are *not* svn checkouts.

Now let me show a picture of how I see the cycle of information on svn and on git.

While commits in svn will send your changes to the server (and keep them safe there), git commits are just “checkpoints” which help you keep changes related to some task together. I had a lot of troubles with this in the beginning, probably because I also use svn as a backup system. If I am working on something on one machine, and need to change to another, I would commit my work to svn and then update the code on the other side. You might imagine that they were not the cleanest commits… In git this would not work. My commit will only stay local, unless I push it to the server. Of course you can push this to the server, but then when someone wants a patch from your changes you will need to reorganize the commits by rebasing and squashing and editing until you get a clean one. Trust me, you don’t want to keep rebasing all the time… specially if these commits are not the latest ones. The lesson I learned from this was: git is *not* a backup system. A commit should be a clean, self-contained, change in the code for a specific purpose. It goes without saying that the change must compile and run!

Now about the checkout. The equivalent of an svn checkout in git is clone. This command will get the source from the server and create a copy on your machine. Git’s checkout is a completely different thing. It is related to branches. While svn branches are created on the server from where you can check them out, git branches are local or on the server. And these are not necessarily in 1:1 correspondence. You can have 5 local branches and the server can have 3, and you can push commits of any of your local branches to any of the server’s branches (although it is safer if you keep a 1:1 correspondence for pushes). Git checkout will only change the local branch you are working on (quite fast actually, so you can do this all the time). Currently I am keeping three branches, one “master” which is always in sync with Gnome’s, one “multiscreen” with some commits I had regarding multiscreen support, and one “annotations” with the commits related to annotations.

I hope this is more or less helpful to understand some of git’s semantic.

PDF, annotations and evince

So, my GSoC project is regarding PDF files. More specifically, I’ll be working on evince and improving its annotation system (yes! evince has annotations! It is kind of hidden and I also didn’t know about it, but we’ll improve that now 😉

I started reading about the PDF file format last week, and I was impressed how much you can do with it. When I think of PDFs, text files immediately come to mind. Of course you can have some forms to fill in (which is quite practical) and pictures, but it is used mostly for text. So what was my surprise when the first chapters of the PDF book I am reading (Developing with PDF by Leonard Rosenthol) were all about paths… In principle, I can draw *anything* in a pdf. Pretty cool, no?
But I am deviating.

I will improve annotations, so I need to know how annotations work. These are embedded in the pdf file itself, and there are 17 possible types. Whenever you are implementing a viewer for pdfs, you need to be able to read these elements and show them on the screen. In the case of evince, poppler is responsible for reading the pdf info, and poppler elements are then translated into evince elements, which are displayed properly.

Currently, evince supports 2 annotations (text and file attachment) as annotations themselves and 2 (link and widget) not exactly as annotations internally. From the supported annotations, the text one presents some problems. The text annotation is like a comment, like a post-it note on the document, and it is not associated with any part of the text (that’s the popup annotation).
I am trusting that poppler has the necessary support for all annotations, otherwise I’ll have to tweak some code there too.

My main goal will be to fix this text annotation and extend the support for other types, such as highlighting, underlining and popup.