#acl Known:write,read,delete,admin,revert All:read 
###  acl Known:read,write,admin,delete,revert

A version control system is useful when working on a collection of files that evolves over time, in particular if several people are modifying the files. For example, version control is often used in software projects to store the code in a way that several developers can access and contribute to the code without the need to send files by e-mail etc. Another example is when you are writing a paper with your colleagues and you need to efficiently and safely share your additions to the paper. A version control system also keeps track of the history of your contributions; most version control systems can be used to retrieve the state of your files as of a given date. This means that there is no need to create local back-up copies. To make it short and sweet: version control means you can relax. 

= Git =

[[http://http://git-scm.com/|Git]] is currently the preferred version control tool at the department. For starters you might want to look at a git tutorial I wrote some time ago [[attachment:git-tutorial.pdf]]. There are also heaps of tutorials out on the net. A quite comprehensive manual is [[http://www-cs-students.stanford.edu/~blynn/gitmagic/book.pdf| Git Magic]], another pretty good one is [[http://nyuccl.org/pages/GitTutorial/| Git for Scientists]]. It is also quite handy to have a [[attachment:git-cheat-sheet.svg|cheat sheet]] handy beside the keyboard for those quick command-and-options lookups. 

Talk to [[mailto:anders.nilsson@control.lth.se|Anders Nilsson]] in order to have a repository for your files set up, or if you want to know more about version control.

== Setting up GIT ==

 * You can run GIT locally on your machine. How to do this is covered [[http://git-scm.com/documentation|here]]. If you want a repo subsiding on one of the control servers, this is what to do: Go to [[http://gitlab.control.lth.se]], create a user, create a project, follow the instructions.

 * If you need to create an SSH key pair, instructions are found here: [[https://help.github.com/articles/generating-ssh-keys|here]].

 * To push changes to the remote server, first commit locally {{{git commit -am "This version is awesome."}}}, then push to the server {{{git push}}}. Likewise you can pull changes from the server {{{git pull}}}.

 * If you are annoyed by always having to type a message when you commiting:
{{{
git config --global alias.co 'commit -a --allow-empty-message -m ""'
git config --global alias.com 'commit -a --allow-empty-message -m'
}}}

 * On OS X you might encounter annoying warnings like:
{{{
perl: warning: Setting locale failed.
perl: warning: Please check that your locale settings:
	LANGUAGE = (unset),
	LC_ALL = (unset),
	LC_CTYPE = "UTF-8",
	LANG = (unset)
    are supported and installed on your system.
perl: warning: Falling back to the standard locale ("C").
}}}
when communicating with the server. An easy fix to this is to avoid sending your locale settings to the server over SSH, by commenting out {{{SendEnv LANG LC_*}}} in {{{/etc/ssh_config}}} (sing a leading {{{#}}}).

== Deep-remove files in Git ==
'''Warning: Do not use this instructions when you normally remove files, and do not use them if you don't know what you are doing.'''

Sometimes large files or files with sensitive content (like passwords) accidently got added in a git repo. To remove the file with {{{git rm}}} is not then enough, since the content of the file will still be saved in git's history. But there are several ways to remove the traces of the file even in the log files. The easiest one is probably to use the [[BFG Repo-Cleaner|https://rtyley.github.io/bfg-repo-cleaner/]].

Start with mirroring the git-repo
{{{
git clone --mirror git@gitlab.control.lth.se:my-dirty-repo
}}}
Then use the BFG Repo-Cleaner to remove the file you want
{{{
java -jar bfg-1.12.13.jar --delete-files '*.iso' my-dirty-repo.git
}}}
The command above will remove all the .iso-files from the whole repo (all branches included). '''Warning: Again, think twice before doing this, for instance, removing all .pdf files from a course repo isn't probably a good idea, since some of them may not originate from a tex-file. And there is no easy way to get the file back anymore (IF you are lucky, some Anders might can find it on a backup)'''

Once this done
{{{
cd my-dirty-repo.git
git reflog expire --expire=now --all && git gc --prune=now --aggressive
}}}

Then (if you have the right permissions to the project in gitlab) it should just be to run
{{{
git push
}}}

However, I think due to some issues with gitlab, even though I had master permissions to the project I was not allowed to push. The solution was to remove the protection on the master branch in gitlab, push and then add the protection again.

After this is done, it can be an idea to request some housekeeping in gitlab. It looks like the housekeeping runs {{{git gc}}} without the {{{--prune=now}}} flag, which means that it is only housekeeping requested two weeks after the removal of the file, that will actually remove it from the servers storage. But the file will be removed from the repo and the history immediately, so if you make a new clone after doing this, it will be less data to download.

== Gitlab CI ==
In gitlab there are tools to run jobs every time you push to the repository. You can also put restrictions on when to run the jobs, for example only running it if any files in a specific folder are changed. This can be used for many different things, for example running automated tests or maybe automatically uploading any changed files to a homepage as in [[https://wiki.control.lth.se/versionControl/canvasSync|canvas sync]].

== General advices ==
 * For a course repo, when a course is finished for the year, add a tag. This is either done in gitlab or by running {{{git tag 20XX}}}.