CommunityData:Git: Difference between revisions

From CommunityData
(→‎Using git-annex to manage large files in git: remove annex stuff to move it further down)
Line 42: Line 42:
To create a new repository, you will need to have admin rights. Currently, the administrators are Kaylea, Nate, Jeremy, Aaron, Mako, Sayamindu, and Jim. If you'd like to be an administrator, you should contact one of them!
To create a new repository, you will need to have admin rights. Currently, the administrators are Kaylea, Nate, Jeremy, Aaron, Mako, Sayamindu, and Jim. If you'd like to be an administrator, you should contact one of them!


=== Using git-annex to manage large files in git ===
=
 
{{note}} This is still experimental, and may go away. Don't put files in it without a backup.
 
Git is not a very good system for managing large files, which is a problem for us, since we often have large data files. Enter [https://git-annex.branchable.com/walkthrough/ git-annex], a system that works in tandem with git and lets you store large files (but avoids using git as the data store). Our gitolite installation supports git-annex. To start using git-annex, install git-annex locally in your computer. Most GNU/Linux distributions have git-annex packages. Then, in your existing git repository execute the following initialization command:
 
<source lang='bash'>
$ git annex init
</source>
 
This needs to be done only once. To add a file, in your repository, run the following commands:
 
<source lang='bash'>
$ mkdir data
$ cp ~/largedata.csv.bz2 data/
</source>
 
You should encrypt the file if the data is not public. You can use GNU Privacy Guard to do the encryption, and have all your collaborators as recipients for the file. Once encrypted, execute the following commands to include and push the file to the server.
 
<source lang='bash'>
$ git annex add data/largedata.csv.bz2.gpg
$ git commit -m "Added data file"
$ git push --all
$ git annex copy --to origin
</source>
Once these commands are successful, your collaborators should be able to get the file with the following command (assuming that they have already run <code>git annex init</code>):
 
<source lang='bash'>
$ git annex get data/largedata.csv.bz2.gpg
</source>
 
Once you've encrypted non-public data, git-annex is easy to use using the webapp.
<source lang='bash'>
$ git annex webapp
</source>


=== Details for Administrators ===
=== Details for Administrators ===

Revision as of 20:36, 20 November 2020

Getting Access to the CDSC Git Repository

If you need access to the CDSC Git Repository, you should ask on the #communitydata IRC channel for access. If you need access to a specific repository only, mention which one. If you are a new CDSC member, mention that you need to be added to the @collective group in Gitolite. Anybody in the collective who uses the Git repository will be able add you.

Install Git

To get started, you will need to install git. Doing so requires different steps depending on your operating system. Basic instructions available from the Git website.

Mac OS users should check out this tutorial, which recommends also setting up the "Command Line Tools" as well as the "homebrew" package manager. If you follow the steps for installing git onto your machine, it is only necessary to do the first three (out of five). This includes downloading/installing the command line tools, installing Homebrew, and installing git itself.

Note that RStudio also has Git integration now. Instructions and details available via RStudio support documentation.

Configuring Git for submodules

Once you've installed git, there are some configuration options which will make your life much easier. You can set them globally with the following commands:

git config --global alias.spull '!__git_spull() { git pull "$@" && git submodule sync --recursive && git submodule update --init --recursive; }; __git_spull'
git config --global status.submoduleSummary true

These two commands will ensure that git works a little better with submodules. Submodules are essentially git repositories that are buried inside other git repositories. For example, the wikiresearch repository currently uses the RCommunityData repository as a submodule. If you're working in a repository like this, you'll want to use git spull instead of just git pull which will also check for and pull changes made in any of your submodules.

Gitolite Server

We have a private git server which uses gitolite to manage permissions for git repositories. It's like a private Github server that hosts our respositories, but just ours, and on our server.

Dependencies

Once you've got git installed, you will also need a public SSH key. You can send your public key (usually ~/.ssh/id_rsa.pub) to a current administrator (see the list of administrators below on this page), and they can add you as a new user.

Cloning a repository

"Cloning" a repository downloads the files, as well as the history, of a repository. It also creates a new git instance in that directory, so that you can commit changes to the code.

To clone a repository, run the following command:

 git clone --recursive git@code.communitydata.science:REPOSITORY_NAME

Note that you need to use this SSH syntax rather than the git protocol (e.g., git://code.communitydata.science/repo_name), which doesn't have write permissions.

Creating a new repository

To create a new repository, you will need to have admin rights. Currently, the administrators are Kaylea, Nate, Jeremy, Aaron, Mako, Sayamindu, and Jim. If you'd like to be an administrator, you should contact one of them!

=

Details for Administrators

Creating new repositories

If you are all already administrator, this describes how you will create a new repository.

First, you will need to clone the gitolite-admin repository

$ git clone git@code.communitydata.science:gitolite-admin

And then edit the file conf/gitolite.conf. To add a new project, simply create a new entry at the bottom of the file.

For example,

repo foo
    RW+ = aaron mako
    R   = jdfoote

would create a new repository at git@code.communitydata.science:foo with aaron and mako as admins, and give jdfoote read-only access *once this file was saved, committed, and pushed*.

You could then go to wherever the files are that you would like to track, and add this repository as a remote, like so:

$ cd foo
$ git init
$ git remote add origin git@code.communitydata.science:foo
$ git add ./ # Adding everything to be tracked in git
$ git commit 
$ git push --set-upstream origin master

If this project already exists in git, then it's even easier. Just change the remote, and push it.

$ git remote set-url origin git@code.communitydata.science:foo
$ git push

Adding new users

To add new users, simply add their public key to the keydir/ directory, renamed as username.pub. The persons username (as called in the code/gitolite.conf file) will be whatever the username in the filename above is.