How to use GitHub for Version Control with Scribus

This tutorial will show you how to use the "GitHub for Desktop" software to supply version control and tracking functions for your Scribus documents.

It's quite long so you might like to have the necessary drinks/snacks at hand if you think you'll need them.

NOTE: This tutorial was prepared on OSX with "GitHub for Desktop" for Mac build 177. If you use a different OS or version of GitHub you may have to do things slightly differently. Check the official GitHub documentation - you might like to look here https://help.github.com/ - for your OS/version to get more details. Also see the "Download the software" section below for more information.

VERY IMPORTANT: While GitHub can give you all sorts of great version control functionality it is not a substitute for properly implementing a good backup plan. I would seriously recommend that you take backups regularly just in case something goes wrong. This is simply common sense.

1. Getting Started

This tutorial is not designed for Scribus beginners. While the techniques used in it are not difficult or complicated it would be best that you learn the basics of Scribus before attempting the procedures below. It's better to learn one thing at a time.

1.1. Background

While Scribus has a lot of features, one thing it doesn't have is a way of keeping track of the changes you make to a document. It has the "Undo" function but that's just a very simple way of backtracking changes since the last Save and it doesn't always work perfectly.

What we sometimes need is a way of keeping track of the changes we make to a document so that, if we do something we later regret - or just don't want anymore - we can go back in time and get an earlier version of the document. This is what we can get from GitHub.

Git was originally designed by a computer programmer - Linus Torvalds who, incidentally, also created the Linux operating system, in case you didn't know - so that computer programmers could control changes to their computer programs. And it's really good for that. But it can also be used by non-programmers to keep in control of other things too. It's used by lots of people all round the world to keep track of things like:

• Copy editing for magazine articles
• Wiki participation
• Translating recipes into different languages
• Recruitment processes
• and much much more.

The main thing about GitHub, for our purposes, is that it can keep track of document changes; it gives us what is sometimes called 'version control'. By using GitHub we can keep track of - and therefore control - multiple versions of our documents and go back to previous versions if necessary. It does way more than that but baby steps first.

1.2. Create a GitHub Account

The first thing you need is a GitHub account. If you haven't already got one you can sign-up at https://github.com. Don't worry about this. It's free - unless you need some private web space - and you only have to give a user name (which can be anything that isn't already used), an email address and a password. No personal details are necessary.

1.3. Download and install the GitHub software

1.3.1. Download the software

You can download the "GitHub for Desktop" software for Mac (OSX) from: https://github.com. The file isn't very big - around than 10MB, expanding to around 40MB on installation.

A Windows version - for Vista and later - is available from https://windows.github.com but the interface isn't the same as the version used here so check the official documentation to see what functions map to which buttons etc.

At the time of writing, no official "GitHub or Desktop" for Linux is available but there are various Linux Git applications, depending on your distro. However, they will most probably work very differently to the official Mac version so you might not be able to follow this tutorial.

1.3.2. Install the software

Installation should be a piece of cake - except for Linux, see above. Just install it the way you would install any other piece of software.

1.3.3. Run GitHub for the first time

When you first run GitHub you need to tell it your GitHub username or email address and password. This is so it can do its synchronising - see below - but we're not really interested in that with this tutorial. Just enter the details necessary and move on.

At some point you might get a dialog which asks if you want to install the command line tools. This is up to you. You don't need them for what you'll be doing here but install them if you want to.

You will also be asked if you want to add any existing repos - see below - but you don't have any so just press "OK" or "Continue".

You might be asked - depending on your operating system - about accessing your GitHub account and using your password. How you handle this is up to you and your own security preferences but if you don't allow access you'll have to enter your password every time you run GitHub.

Once through the initial set-up you won't have to do any of this again and GitHub will automatically handle everything.

2. Some GitHub basics

2.1. Repositories

A 'Repository' - more commonly known as a 'repo' - is just somewhere to put stuff that GitHub can manage. For our purposes it's just a folder, nothing more complicated than that. (Behind the scenes it's more complicated but most things are so why worry?)

2.2. Committing Changes

A 'Commit' is a way of telling GitHub to remember the current state of the document(s) it is tracking. When you commit some changes GitHub looks at how the document was compared to how it is now and remembers what has changed. So, when you commit some changes all you are saying to GitHub is "remember how things are now".

You don't need to commit changes often but you can if you want to, it's up to you. You only really need to commit when you get to a point in editing when you think you might want to come back to things as they are now. You will naturally develop your own routine for committing changes.

2.3. Code

You might not know this but a Scribus document is actually code. Not programming code as such, but a structured list of things which tell Scribus how to build the pages in the document. E.g. Draw a rectangle here, draw a text frame there, set this named colour to that colour value, etc.

For the more technically-minded person it is a variant of XML. You really don't need to know this but it helps to know a little bit about it so you can see what's going on 'under the hood' more clearly. I won't explain more about it here, there are plenty of good resources out there on the web that can tell you what you need to know if you want to know. You can quite easily ignore the code completely if you want.

2.4. Synchronising (Syncing)

Synchronising is what happens when you have a repo on your local machine and a copy of it on the web and you want to keep them looking the same. For our purposes we won't be looking at this but you might want to look it up elsewhere if you think you might need it later. It can be very useful for collaboration with others.

3. Your first repo

3.1. Creating the repo

• Go to GitHub and click on "Repositories" in the top bar.
  
• Click the "Plus" icon on the status bar and choose "Create New Repository..." from the menu.
  
• Enter the name of your new repo. If you're following this tutorial use the name "TestingScribus" (without the quotes).
• Enter a reasonable description of the repo, e.g. "Testing GitHub with Scribus" (again, without the quotes).
• Select a location for your repo. This can be anywhere on your filing system. GitHub will create a new folder with the name you have given.
• Uncheck "Push to GitHub?". This makes the repo a local-only repo which will not be synchronised (published to the web).
• OK the dialog.

Your new repo should now be listed in the main window of GitHub. You can look in your filing system to find the new folder if you want. It's just a normal folder (essentially). That's how easy it is to make a repo.

NOTE: You can get GitHub to start tracking changes in an already existing folder rather than one created by GitHub. Just click the "Plus" icon on the status bar and choose "Add Local Repository..." from the menu to start tracking changes in that folder.

3.2. Adding your first file

• Go to Scribus and create a new document.

The actions within Scribus that I suggest here are only for the purposes of this tutorial. You can do whatever you want in Scribus, GitHub doesn't care.

• Create a text frame and put some text in it, e.g. "My first Scribus/GitHub experiment.".
• Save the document in your repo folder. The name is up to you.
• Go back to GitHub and double-click your repo to see more information about it.
• You should see that the "Changes" icon on the left has been coloured red/green. When this icon is coloured this way it means that GitHub has noticed that something in your repo has changed.
  
• Click the "Changes" icon and you'll get another new view.

On the right-hand side of the view is the code that makes up your Scribus document. As has been said before, Scribus documents are just XML documents which are just structured text. You can ignore the text/code for now unless you're interested in seeing what a Scribus document actually looks like 'under the hood'.

What you may be interested in is the highlighting colour given to the code:

• No highlighting - white background - means no changes.
• Green highlighting means an addition.
• Red highlighting means a deletion.

When you make a change - as opposed to just adding something new or simply removing something - you usually get both green and red code as a change is viewed by GitHub as a deletion of the old code and an addition of the new code. You don't really need to know about this but it might give you more of an idea about what's going on.

On the left-hand side of the view you'll see two areas.

The top one is where you tell GitHub about the changes it has noticed. The bottom one can be ignored as it is only needed if you are publishing/synchronising your files to the web (which you're not doing here).

• Under where GitHub says "Uncommitted Changes" enter a good summary and description of the change you've made.

The summary should be a short present-tense sentence saying what has changed or the reason for the changes. The description can be whatever you want to use to tell yourself why the changes were made.

• Enter "Add new document" in the Summary field.
• Enter "Started new document." in the Description field.

You don't need to add a description if you don't want to or if it would add nothing to what the summary says. It's for your benefit only so use it only if you get benefit from it.

Just below the Description are some things that tell you what files have changed or been created or deleted. These allow you to control what changes are committed but in general you can ignore them unless you want to check that what GitHub thinks has happened matches what you've been doing. To check this you'll need more experience with GitHub so it's probably best just to ignore them for now. You can always check the GitHub documentation if you want to.

The area under the "Commit" area - with the title "Unsynced Commits" - is for when you are synchronising with the web, which we're not doing here so you can ignore it at the moment.

• Click the "Commit" button to commit the changes.

GitHub has now remembered the state of your new document at this point in time. You'll notice that the "Changes" icon has changed to be coloured yellow. This simply means that the changes have not been synced with the web. If you're not syncing with the web - as we're not doing here - this doesn't matter.

3.3. Checking the history

• Click on the "History" icon on the left of the GitHub window.

This view shows you the history of the changes to all of the documents in your repo. At the moment this isn't very exciting but you can see on the right the summary and description which you entered and the XML code of your Scribus document.

3.3. Changing your document

• Go back to Scribus and create a shape - any basic shape, it doesn't matter which - anywhere you want on the page.
• Save the document.
• Go back to GitHub.

You should notice that the "Changes" icon has been coloured red/green again. Click on the "Changes" icon if you're not already on that view.

On the right-hand side you should see the extra XML code that Scribus has used to create the shape you drew. Again, you don't need to understand it if you don't want to.

• As before, enter a summary and description for your changes, .e.g. "Add new shape" and "Needed to add a shape.".
• Press the "Commit" button to commit the changes.

You've now told GitHub to remember the new state of the document. You can go to the "History" view to see the changes if you want to.

• Go back to Scribus and add another text frame, giving it some text, e.g. "Another text frame".
• Save the document.
• Go back to the GitHub "Changes" view, enter a good summary and description, and press the "Commit" button.
• Select the "History" icon to see all of your changes.

I don't think you'll have had too much of a problem with any of this so far. I hope you'll agree that it's been quite easy.

3.4. Going back in time

What if you now don't want the last change you made? That extra text looks wrong and you don't like the shape you added, so you want to get rid of them both. How can you go back to how the document was before you added them? As they were simple changes you could go into Scribus and delete them but what if there were many changes and you can't remember exactly what you did? Well, it's GitHub to the rescue.

• Close the Scribus document. It's wrong now so we don't need it.
• Click on the "History" icon on the left of the GitHub window (if you're not already there).

You'll now see the list of changes you made. The first one listed is the last change you made and going down the list goes back in time through the changes. There are two ways you can go back to a previous version of your document:

• Revert a commit
• Roll Back to a commit

When you Revert a commit it is the same as using a normal "Undo" function. I.e. You 'undo' the change you have selected. When you Roll Back to a commit you are 'undoing' all of the changes since that commit. I.e. You want to go back to this state of the document. Either way, you are also 'undoing' all changes up to that point. You can't undo a change in the middle of the list and keep changes after it.

• Click on the commit where you added the new document. In this case it will be the one at the bottom.
• Click the "Tools" button at the top-right of the view and choose "Roll Back to this Commit" from the menu.
  

You'll see that GitHub has created its own commit called 'Revert' with some seemingly-random numbers and letters after it. You can ignore the letters and numbers, unless you're feeling particularly technical. (They allow you to track every commit in detail but we're not interested in that here.) If you look at the XML code on the right you'll see that some of the code has been highlighted in red. This means that these sections of code - these changes to the Scribus document - have been removed.

• Go back to Scribus and re-open the document.

Ta da! The changes you made have gone and the document is back to where it was before you made them.

3.5. Oops

Now, what happens if you realise that the document was better the way it was before you reverted/rolled back the changes? Well, that's simple to remedy.

• Close the document in Scribus.
• Back in GitHub, select the "Revert" commit at the top of the History list.
• Press the "Tools" button and choose "Revert this commit" from the menu.

You'll notice that GitHub has added another "Revert" commit to revert the revert. It creates another revert commit so that you know what happened. If you just deleted the last revert commit you wouldn't know it had happened in the first place when you can back to it later. This isn't really relevant for what we're doing but it's more important as a paper trail when multiple people are working on the same document.

• Re-open the document in Scribus.

And you're back to where you were with the last two changes restored. Easy.

Obviously you wouldn't commit changes as often as you have done here. Or maybe you would; who am I to question you? However, I would recommend only committing when you've reached a point where you think you might want to come back to.

4. Branching off

Sometimes you might have a document that you're pretty pleased with but would like to see what certain differences would make without messing everything up. This is something that GitHub can also help with.

Say, for instance, you've got a document that's all nicely formatted using certain fonts and colours but you are wondering what would happen if you changed one or two colours or typefaces but wanted to keep the original to go back to in case it all went wrong.

In cases like these we can use GitHub's "Branches".

A "branch" is copy of the original that doesn't overwrite the original so everything is safe.

4.1. Creating a branch

• Close the Scribus document.
• Go to the GitHub application.
• Click on "Repositories" on the top bar.
• Double-click on the repo you want to make changes to.
• Click on the "Branches" icon on the left (just under the "Changes" icon).

You'll see that you've already got one branch. It's called the 'master' branch because all other branches come off it. Think of a tree with the master as the trunk and you'll get the idea.

To create a new branch:

• Click on the "Plus" icon at the top-right of the 'master' branch.
  
• Give the new branch a name, e.g. "New Colours" and press the "Branch" button.

You've now created a new branch called "New Colours" and GitHub has moved to using that one instead of the master branch. You can see this by the fact that GitHub shows a tick to the left of the branch you are using.

4.2. Making changes

Now you can make some changes.

• Go to Scribus and open the document.
• Change the fill colour of your text frames and the shape.
• Change the font of each of the text frames.
• Save the document.
• Go to GitHub and, in the "Changes" view, commit the changes you've just made with a summary of, say, "Change Colours and Fonts".

Now you have two branches of your document. The original one and a new one with some colour and font changes.

IMPORTANT: You actually only have one copy of the document. It relates to the last commit of the branch you are currently using. This might take some time to get your head around but it's worth doing so.

You can see what's happened very easily.

• Close your Scribus document.
• Go to GitHub and, in the "Branches" view, click on the small down arrow under the plus icon on the top right of the master branch and choose "Switch to the Branch" from the menu.

GitHub has now switched the branches round and you are now using the master branch again. You can see this because of where the tick is.

• Go back to Scribus and re-open the document.

Your document is back to how it was before you made the changes. Amazing!

And just to check that you haven't lost your new version:

• Close the Scribus document again.
• Go back to GitHub and, in the "Branches" view, click on the small down arrow under the plus icon on the top right of the "New Colours" branch and choose "Switch to the Branch" from the menu.
• Go back to Scribus and re-open the document.

Ta da, again! Your font and colour changes are back. Astounding!

NOTE: Personally I don't know how GitHub does this and frankly I don't want to know because it would probably make my head hurt. As long as I assume that there's a bunch of magical fairies behind the scenes ripping up the code and sewing it back together properly then that's good enough for me!

4.3. In with the new

So, what if you're happy with your latest colour and font changes and want to use this version as your master version? Well that's easy.

• Close the Scribus document.
• In GitHub, go to the "Branches" view and press the "Merge View" button at the top-right.

A little 'sub-window' will open up at the top of the "Branches" view.

• Drag the "New Colours" branch to the left-hand "dark hole" in the sub-window. You need to grab the little grey dots on the left-hand side of the branch name to drag it (the mouse pointer will change to a hand).
  
• Drag the master branch to the right-hand "dark hole" in the sub-window.

A message will now show in the sub-window showing "Merging New Colours into master". This tells you what will happen.

• Press the "Merge Branches" button at the top-right.

Your changes have now been merged with the master branch.

• Press the "Merge View" button to dismiss the sub-window.
• Click on the small down arrow under the plus icon on the top right of the master branch and choose "Switch to this Branch".
• Re-open the Scribus document.

And there you are. Your changes have been merged with your master branch. All you have to do now is delete the, now unnecessary, "New Colours" branch. (You don't have to if you don't want to but it's good housekeeping.)

• Click on the small down arrow under the plus icon on the top right of the "New Colours" branch and choose "Delete" from the menu.

You'll be asked if you really want to do this.

• Press the "Delete" button.

And that's that. You're back on track using your master branch as your main document.

If you now go to the "History" view you'll see that the "Change Colours and Fonts" commit has been copied over to your master branch along with a Merge commit showing you what's happened. Re-open the document if you don't believe it.

4.4. Out with the new

And what if, on the other hand, you didn't like the changes you made to the new branch? Well, that's easy to rectify too. In that case all you had to do was click on the small down arrow under the plus icon on the top right of the "New Colours" branch, choose "Delete" from the menu, and press the "Delete" button on the pop-up dialog. Simple.

5. What about my other files?

Ah, but, I hear you say - or it may just be the voices in my head - what if I have other files like images and PDF proofs? Can GitHub handle them too?

Well, the answer is yes.

5.1. PDF proofs

Every now and again it's normal to want to create a PDF so you can see how your document looks, just to make sure nothing is wrong with it so far. GitHub can keep track of these proofs along with your main Scribus document.

• Go back to Scribus and export the document as a PDF in the usual way you do it. You need to create the proof inside the repo folder so that GitHug can track it.
• Return to GitHub and go to the Changes view and you'll see that GitHub is displaying the PDF you just created as a new potential commit.
• Name the commit, as, for example, "Create first PDF draft" and press the Commit button.

You've now told GitHub to remember this first draft PDF.

• Make some changes to your Scribus document.
• Save the changes.
• Export as a PDF again.

Now when you go back to GitHub you'll see that there are two files that have changed, the Scribus document and the PDF.

• Commit these changes as "Create second draft".
• Go to your normal file browser and open the PDF in the normal way just to see that the changes have been made.

Now suppose you want to get the PDF back to the previous version. Well, that's easy.

• Close the Scribus document (and PDF if you have it open).
• Go to the GitHub History view.
• Select the commit called "Create first draft".
• Press the "Tools" button and choose "Roll Back to this Commit" from the menu.

A new revert commit has been created. You'll notice that at the top of the right-hand side of the view there will be information saying that two files have been changed; these are the PDF and the Scribus document. They're both rolled back so that the Scribus document matches the PDF.

• Load the document into Scribus and view the PDF.

They're both as they should be. Brilliant.

And now we want to go back and carry on editing from before we rolled everything back to a previous version.

• Close the Scribus document (and PDF if you have it open).
• Select the last commit from the History view.
• Press the "Tools" button and choose "Revert this commit" from the menu.
• Load the document into Scribus and view the PDF.

And all is back as it was so you can continue. Fantastic.

5.2. Images

GitHub can keep track of your images too as long as they're contained in the repo folder. I usually keep my images in a sub-folder to keep them separate from the rest of the files, and that's what I'll do here, but you can put your images wherever you want in the repo.

• Go to your file system browser and create a new folder, e.g. "images".

If you look in GitHub it has not registered any changes. All you've done is create an empty folder so it doesn't need to track this just yet.

• Copy an image into the "images" folder.
• Go back to the GitHub images view.

You'll now see that GitHub has noticed the change - a new file - but you don't need to commit the change just yet.

• Go to Scribus, add an image frame, and put the image in the frame.
• Save the document.
• Go back to the GitHub Changes view and commit the changes as usual.

And that's all you have to do. GitHub is now tracking the image you've added. If you overwrite the image - with a different version that you've edited in, for example, GIMP - GitHub will notice the change and you can commit it as normal.

NOTE: One thing is worth pointing out with images. If you change the image but don't change any other settings for it in Scribus - e.g. scaling etc. - and re-save the Scribus document it won't register as a change. This is because the Scribus document hasn't changed as Scribus only 'links' to image files. The Scribus document doesn't contain any image files so the file hasn't changed so GitHub has nothing to track. However, if you then create a PDF with the new image in it the change to the PDF will be tracked (if it's in the repo). This isn't a problem but it's worth remembering so you don't think something has gone wrong.

6. What next?

So far you've only just scratched the surface of what GitHub can do for you. It can do so much more than what you've seen but hopefully you've seen enough to be left intrigued and wanting to know more.

In this tutorial you've only been working on one simple document but a GitHub repo - as you might remember - is a folder, and GitHub can manage everything in that folder.

So you can, for instance, manage changes to your articles or chapters as separate files - text/markdown/whatever format it really doesn't matter - in a sub-folder before you import them to your document. Just add the sub-folder to the repo and add the files; GitHub will track them automatically.

Or you can sync your repo with the web and use GitHub to provide collaboration tools where multiple people can work on the same document(s) together.

GitHub on the web also provides issue tracking and discussion features that could be very useful if you work in a group.

And there are a whole load of other features which are totally outside the scope of this tutorial.

So why not give it a try? It's free - unless you want some private space - and you never know what uses you'll find for it unless you give it a go.

WARNING: The procedures and techniques in this tutorial have not been exhaustively tested and no guarantees are given. However, GitHub is used every day by hundreds of thousands of people working on projects that are orders of magnitude more complex than a Scribus document and they seem to be very happy with it.