Version Control¶
Overview¶
Version control is a system that record changes made to one or more files. In this section I will discuss distributed version control systems e.g. Git+GitHub
We are pleased to announce that we have set up a GitHub team account for the cluster [github.com/ubcbraincircuits], under which members can set up their repositories.
Note
Go to the Onboarding section below for instructions on becoming a member
Resources
Not Using Version Control?¶
Why Use Version Control?¶
- Revert your files to a previous version
- Compare changes
- Provides a record of what changed and Why
- Lets you experiment
- Recover files if you make a wrong turn or delete them
- Distruibuted clones of a repository act as full backups
- Collaborate in an organised manner
- Clear attribution of contributions
What Can I use Version Control for?¶
- Code
- Papers
- Theses
- Journals
- Critical data files
Version Control Systems (VCS)¶
Git¶
Git was created to manage the development of the Linux kernel. It is the most popular distributed version control system. You can read more about it here. Git is complex and requires training to use safely and appropriately. This complexity gives Git greater flexibility and more functionality for power users.
Mercurial¶
Mercurial is simpler and easier to use than Git. It makes it more difficult for users to cause inintentional damage. You can read more about it here.
Tip
Git and Mercurial are available on Windows, MacOS and Linux. There are also several graphical user interface options for both options for those who do not prefer to use the command line interface.
Hosting¶
The following platforms can be used to host your repositories remotely:
GitHub | GitLab | Bitbucket | |
---|---|---|---|
VCS Support | Git Only | Git Only | Git and Mercurial |
None of these platforms store data exclusively on Canadian servers, so sensitive data should not be pushed to the remote. If this is absolutely necessary, there is the option of setting up your own server as a remote. This is possible through:
- Enterprise offerings from these platforms that may not benefit from academic pricing
- Setting using an open-source offfering at the expense of losing the rich interfaces of the hosting platforms. One such example is `gogs.io`_.
Using Version Control?¶
Moving existing repositories to central cluster repository¶
It is highly recommended that all existing respositores be transferred to the main cluster GitHub repository.
Please refer to the Setup Instructions
section below for instructions.
The main aims of doing this are:
- Reducing fragmentation by maintaining a centralised code repository under the administration of PIs for easier management
- Access to research repositories after personell leave labs
- Making GitHub Pro and GitHub Team available to all cluster members, providing access to more powerful tools
Spread the Word!¶
Encourage colleagues who have not adopted VCS to do so. Incorporate VCS training during the onboarding process when brining new people into the lab.
Benefits of GitHub Education¶
With the GitHub Education subscription granted to the cluster, members enjoy the benefits like:
Wikis and Websites¶
Free wikis for private and public repositories. Use them to: write down documentation, write lab notes, create a whiteboard, create meeting agendas. Find out more here
You can also create websites using GitHub Pages
Team Collaboration Tools¶
PIs and Researchers can create teams and control who can edit certain repositories. There are also spaces for team discussions
Onboarding¶
1) Get a GitHub account¶
If you do not already have a GitHub account, you can sign up for one here. Skip this step if you have an existing account.
2) Become a Member of the Brain Circuits Repository¶
Contact Jeffrey LeDue and provide your GitHub account name or email to be added as a member. You will receive an invitation via the email account you used to register for GitHub.
3) Move Existing Repositories to the Central Repository¶
If you have exisitng respositories that you desire to move to github.com/ubcbraincircuits
,
the transfer procedure can be found here.
When prompted, set the New Owner's Github username or organisation name
field to UBCBrainCircuits
.
Note
The main aims of doing this are:
- reduce fragmentation by maintaining a centralised code repository under the administration of PIs for efficient management. This also enhances discoverability and the ability to collaborate across labs.
- enable labs to access repositories after members move on
- give cluster members free access to GitHub Team and its benefits
4) Create or Join a Group¶
If your lab has not yet creted a group, you should create one by going to github.com/ubcbraincircuits
clicking on the Teams
, then
on New Group
. Temas can be made private or visible to all member of the cluster.
If your lab has a group, ask an existing member to add you to it.
Visible groups can be nested, and are useful for coordination. All members are able to create other groups as they wish.