Amrita Gitlab usage guide

Guide.md

Guide to Using Amrita's Gitlab CE

Hello! The Coimbatore campus of Amrita Vishwa Vidyapeetham now runs an instance of Gitlab CE on http://git.amritanet.edu

@account-init

Do these things first.

0. Learn how to use git.
1. Generate and upload public SSH key, can do from windows too. No excuse.
   • Navigate to Settings > SSH Keys.
   • You can upload multiple keys, for multiple machines, or emails.
2. Connect any one or both of your existing Google, Github accounts.
   • Navigate to the Settings > Account.
3. Optional Add/change/modify your primary, public, notification emails. For ex., I hardly check the institute mail account, so I've directed all notifications to my primary email.
   • Navigate to Settings > Emails.
4. Keep learning how to use git.

Guides on git

todo!

Terms of Service, aka morals and etiquettes

1. We expect you to use this service responsibly. Though the aim of this service is to improve sharing and collaboration, some projects are by nature secretive.
2. Even if the owners give you access to those repos, you MUST NOT MAKE YOUR FORK OR PROJECT CONTENTS PUBLIC WITHOUT PRIOR PERMISSION FROM OWNER(S).
   • This means, you cannot upload a clone of a secretive repo on any public service including Github, Gitlab, file sharing platforms, etc.

FAQ

In this section, public account refers to accounts on VCS services like Github, Gitlab and ALL file sharing services.

Should I host my work on Amrita or a public account?

We recommend you start with hosting your repos on the Amrita server because it is,

• easier for experienced people, in the campus, to help you out in config problems.
• easier for your awesome work to be found.
• easier to impress everyone and induct juniors into your projects!

Remember that this server is also public and not completely closed to the outside world :)

Work on an existing project.

Most of your peers' projects and even department projects will/are happening here, so if you want to join these projects to contribute, it is best to fork them on Amrita.
Note that you can clone them into your public accounts (if owners give you read access), and still send PRs to the original repo on Amrita. But we don't want you to do that. Please keep your forks here.

Make a new project

• If the project is part of course work, host it here.
• Working on something cool? wish that more people help you? Want to reach out to alumni? Want course credits for project?
• You can choose to deploy on a public environment (DO, GKE, heroku, EC2) from inside here if you wish.
• You can export your repo to any public account in just a few clicks, in the future.

I'm new to git, what is THE Best git client for me?

First things first, a git client is what you use on your machine to manage your repo. You are a user of the git client which usually communicates with a git server (git.amritanet.edu, github.com).

There are 2 classes of clients, good and bad:

• Good == CLI
  • default git CLI on ZSH <---- check this mad combo out!
    • Using ZSH and shell within text editors, the git CLI gets extreme super powers.
• Bad == GUI
  • gitkraken
  • clients integrated into JetBrainz products
  • other GUI clients

It is recommended you use Good clients, because that is the only.. ummm... WYSIWYG method. Once you understand git operations and things that happen under the hood, you may treat yourself to the Bad luxurious clients (if you are really crazy).
GUI clients are Bad --> because they hide away many things --> so newbies usually form invalid or wrong assumptions about git --> usually leads to frustration, pain and ridicule from peers --> which is bad for a newbie.
Hence Proved! ;)

If usage of Bad clients is not checked, one can plunge into chronic depression, bad habits, sense of ever increasing guilt, self-doubt, low self-esteem, lack of healthy social relationships...
Still not convinced? Why? didn't you see that false ad about that guy called Mukesh?
Real story: Poor guy used a GUI client. RIP Mukesh :(
Just don't use GUI clients. Period.

I'm NOT new to git, what is the Best git client for me?

If you still don't know what client is good for you, you're still a git rookie/noob.
Persevere my friend, explore and find your true love, for beauty is in the eye of the beholder.

How do I manage multiple git accounts?

We highly recommend you make a primary account on Github for all your personal software projects. You should strongly consider applying for the absolutely free! Github Student Education Pack which provides you not only (some of) Github's paid services but subscriptions or discounts on many other cool services.
You can easily import projects from your public accounts into Amrita, but remember that exporting projects that you don't completely own to your public accounts is generally, "not cool, bro".
This guide is not "complete", look on Atlassian instead.

You need to configure your git client (terminal or GUI) about your multiple accounts.
You might have noticed there are 2 ways to communicate with the git server: HTTPS and SSH.
Amrita recommends SSH, because that is a safer, easier and faster method.

This guide assumes SSH because it requires some initial setup, unlike HTTPS.

1. You should find out what SSH is. Read the Ubuntu and Arch wikis for excellent write ups, discussion of usage, etc, even if you think you know what SSH is.
2. Add your public SSH key (how to generate one?) to your account.
   Please do use a pass phrase for your key.*

You can create multiple SSH keys (for different accounts), but you don't have to, unless you can adequately justify it. If you do wish to use multiple keys, well you might want to tell the SSH client which one to use. This is not necessary though and alternatives can be found here.

You will now want to clone (download) a project from Amrita or upload one:

1. Clone from remote (Amrita)
   • Make sure you've "added" your key to the client (using ssh-add perhaps).
   • Run $ git clone git@git.amritanet.edu:username/projectname.git
   • You might want to override some global gitconfig fields just for this Amrita repo.
     • Enter the repo directory and edit the fields. git will remember them.
     • Usually you would want to change user.name, user.email.
2. Upload a repo to Amrita OR "add a remote that points to an Amrita repo to your local repo"
   • This means you have a local repo (on your machine), which must push/pull to an Amrita repo.
   • Make sure your SSH client is set up properly.
   • Just add the remote using
     $ git remote add origin git@git.amritanet.edu:username/project.git
   • You can also track remote branches, push them and to them etc.

For more on managing multiple SSH keys for git, see this excellent SO answer.

Have any more questions? Comment here!