Learning to git

A few years ago, I learned from Myriam's fine blog how to build Amarok from source, which is kept in git. It sounds mysterious, but once all the dependencies are installed, PATH is defined and the environment is properly set up, it is extremely easy to refresh the source (git pull) and rebuild. In fact, I usually use the up-arrow in the konsole, which finds the previous commands, so I rarely have to even type anything! Just hit return when the proper command is in place.

Now we're using git for the KDE Frameworks book, so I learned how to not only pull the new or changed source files, but also to commit my own few or edited files locally, then push those commits to git, so others can see and use them.

To be able to write to the repository, an SSH key must be uploaded, in this case done in the KDE Identity account. If the Identity account is not a developer account, that must first be granted.

Just as in building Amarok, first the folders need to be created, and the repository cloned. Once cloned, I can see either in konsole or Dolphin the various files. It's interesting to me to poke around in most of them, but the ones I work in are markdown files, which is a type of text file. I can open them in kate (or your editor of choice) either from Dolphin or directly from the cli (for instance kate ki18n/ki18n.in.md).

Once edited, save the file, then it's time to commit. If there are a number of files to work on, they can be all committed at once. git commit -a is the command you need. Once you hit return, you will be immediately put into nano, a minimal text editor. Up at the top, you will see it is waiting for your commit message, which is a short description of the file or the changes you have made. Most of my commits have said something like "Edited for spelling and grammar." Once your message is complete, hit Control X, and y and return to save your changes.

It's a good idea to do another git pull just to be sure no one else has pushed a conflicting file while the commit message was being crafted, then git push. At this point the passphrase for the ssh key is asked for; once that is typed and you hit return, you'll get something like the following:

Counting objects: 7, done.                                                                                                                                                                              
Delta compression using up to 8 threads.                                                                                                                                                                
Compressing objects: 100% (4/4), done.                                                                                                                                                                  
Writing objects: 100% (4/4), 462 bytes | 0 bytes/s, done.                                                                                                                                                
Total 4 (delta 2), reused 1 (delta 0)                                                                                                                                                                    
remote: This commit is available for viewing at:
remote: http://commits.kde.org/kf5book/90c863e4ee2f82e4d8945ca74ae144b70b9e9b7b
To git@git.kde.org:kf5book                                                                                                                                                                              
   1d078fe..90c863e  master -> master                                                                                                                                                                    
valorie@valorie-HP-Pavilion-dv7-Notebook-PC:~/kde/book/kf5book$

In this case, the new file is now part of the KDE Frameworks 5 book repository. Git is a really nifty way to keep files of any sort organized and backed up. I'm really happy that we decided to develop the book using this powerful tool.