Project Management and Documentation#
Here are a few links I used to setup GitLab and figure out how to use SSH keys: - Pushing an existing project to GitHub - SSH keys tutorial - About GitHub branches
Here is a Markdown cheatsheet.
Git#
I’m in CS so Git is relatively familiar to me, but it can be daunting to someone who’s never used it. Here are the basics :
Starting out#
Git is the most popular version control (or source control) system. It’s the practice of tracking and managing changes to software code. Software developing teams use it all the time to keep track of their code and go back in time to a previous version of their code when something goes wrong.
git config --global user.name “firstname lastname”
git config --global user.email “valid-email”
To clone an existing repo hosted remotely with https
, click on the “Code” button and copy the link under “Clone with https”.
git clone https://www.github.com/username/repo-name
Pushing to a repository#
Go to the root directory of the project you want to push.
git init
This creates a hidden .git directory in your project folder.
Then, add the files to the Git Index:
git add -A
-A
means you “include all”.
Commit the files you just added.
git commit -m "message"
Add a new remote origin. “Remote” refers to a remote version of the same repo which is on a server somewhere else (like GitHub or GitLab). “Origin” is the defult name Git gives to a remote server.
git remote add origin git@gitlab.com:fablab-ulb/enseignements/2024-2025/fabzero-experiments/students/hac.le.git
Finally, push the changes you just commited.
git push -f -u origin main
A passphrase might be required here if you’re using an SSH key (see later).
So, all together :
git init
git add -A
git commit -m "message"
git remote add origin git@gitlab.com:fablab-ulb/enseignements/2024-2025/fabzero-experiments/students/hac.le.git
git push -u -f origin main
SSH keys#
SSH keys that you generate lets Github verify you are the one pushing code and not someone else with malicious intents. Their usage is much more convenient than manually entering your username and password.
An SSH key relies upon the use of two related but asymmetric keys, a public key and a private key, that together create a key pair that is used as the secure access credential. The private key is secret, known only to you, and should be encrypted and stored safely. The public key can be shared freely with any SSH server to which you’d want to connect.
Multiple keys can be associated with one account, i.e. you can have a different way of authenticating yourself on different devices. Should one of your keys get compromised, you can invalidate it without affecting the others. I used the ED25519 key type since they’re more secure than RSA keys.
Check for existing SSH key pair#
- Go to your home directory
- See if the
.ssh/
subdirectory exists
Generate an SSH key pair#
Open a terminal and run :
ssh-keygen -t ed25519 -C "<comment>"
A message asking to indicate the file in which to save the key should display (you can accept the suggested filename and directory). You also have to specify a passphrase, which will add an additional layer of security and will have to be entered each time the SSH key is used. Since your private SSH keys are stored on a device, should said device be accessed or stolen, any system that uses your keys can be accessed. So a passphrase helps prevent this.
After entering the passphrase, a public and private key are generated. Store the private one somewhere secure.
Add the SSH key#
Copy the contents of your public key.
For Windows :
cat ~/.ssh/id_ed25519.pub | clip
For MacOS :
tr -d '\n' < ~/.ssh/id_ed25519.pub | pbcopy
Then, in your GitLab account, in “Edit Profile”, select “SSH Keys” and “Add new key”. Paste the contents of your public key, fill in the title and select its usage. Optionally, you could update its expiration date.
Verify that you can connect#
ssh -T git@gitlab.example.com
You have to replace gitlab.example.com
with your GitLab instance’s hostname.
If this is the first time you connect, you have to verify the authenticity of the GitLab host. After entering the command above into a terminal, a message should appear asking if you want to continue connecting. Type yes
and enter. Then, run the command again.
About branches#
Branches can be worked on in isolation without having to worry about the changes other people are making in the shared repo. A branch is always created from an existing branch.
Make sure you have write access to the repo to manipulate branches.
The default branch in any new repo is main
.
Pull requests#
A pull request is when a contributor/dev is asking to merge new code changes on a branch (the head branch) onto another branch (the base branch).
The head branch can be deleted after the merge. Branches directly associated with open pull requests can’t be deleted.
If a head branch is deleted after its pull request has been merged (a successful pull request), any open pull requests whose base branch is (was) the aforementioned deleted branch is updated. Their new base branch is now the merged pull request’s base branch.
Compressing images#
You can compress images on virtually any OS with their default app to open images.
Since I use Windows 11, I can just use their Photos app.
Click on the 3 dots on the upper left side, then to the Resize image
option.
Alter the image’s dimension (Medium is usually fine).