Fab Cloud is the Git repository for all Fab Academy and FabLab sites. The first thing you have to do as part of Fab Academy is set up your own repository here for your website. Git very powerful tool used to synchronize multiple versions of files and folders that multiple coders are working on in the same project. Don’t let that scare you though, in the beginning we’ll just be using it to update the webpages on Fab Cloud.
I recommend you learn about using Git in the command line, but that’s a bit scary for some folks. Luckily, the simple basic stuff doesn’t require it (of course, unless you mess something up, then you’ll be learning all about those advanced functions in the command line tool).
Head over to Git for Windows download and install it.
While this downloads and installs, login to your Fab Cloud account. Recall that you’ll login using your FabLabs.io credentials, in fact the two sites are linked. Just click the button to pull in your FabLabs.io login and you’re good to go.
Once in, you’ll be at your dashboard. https://gitlab.fabcloud.org/dashboard/projects . Then click the big green “New Project” button at the top right of the screen. Name this project whatever you want and you can choose whether or not to have a Readme.md file in there. Go ahead and create the Readme.md file. This file is automatically rendered from markdown to html when you visit the directory in your repository it resides in. It’ll start off blank, but we’ll add something to it later.
Now we need to connect the web server and your computer in an encrypted way to transfer files back and forth.
Open Git GUI by clicking your windows start menu button and typing “Git GUI” click the icon when it appears. Since this is the first time you’ll have used the software, it’ll ask you what you’d like to do. Select “Clone Existing Repository” as we will be making a local copy of the one from the web. The local copy will be the one you edit and update and when you are ready, you can upload all your changes to the web.
It is at this point that we have 2 options. If you are on Central Piedmont’s campus, you CANNOT use ssh. You can only use the https method of accessing your gitlab site.
If you are using HTTPS:
Step 1: Visit your gitlab repository’s page and click the blue “Clone” button. You’ll need to select the “Clone with HTTPS” link.
Step 2: Open GitGui on your windows machine by clicking the windows icon and searching for it.
Step 3: Click “Clone Existing Repository”
Step 4a: Paste in your https link in the top box as shown below
Step 4b: Set a target directory on your computer for where you want the files copied to. I created a folder in my Documents named GitGUI. Then you must type in a slash and the name of the folder you want to create. You can’t select a folder that already exists… Here I manually added “/base” after selecting my GitGUI folder.
Step 5: Click “Clone” and it will ask you to login to gitlab.fabcloud.org. If you forget this, simply visit your gitlab.fabcloud page, login via fablabs.io, then look at your account info.
Save your progress locally:
You can now edit the files in that folder, and when you are ready to save your progress locally. You may think “I already saved the files I edited” but you want to make sure to save your progress on the entire repository in gitLab in case you ever need to revert back to this saved point. Think of it like a spawn point in a video game. You WILL break something eventually and need to go back to this save point.
To save your local progress, open gitGUI and open this repo. Then you can click the “scan” button. you’ll see a number of files in the top left pane. These are unsaved changes.
Step 1: Click “ReScan” to scan the folder for changes
Step 2: “Stage Changed” will setup the changes to be committed to your local repository (folder)
Step 3: “Commit” documents this as a save point for the future. You need to enter a comment in the “Commit message” window describing what works and what doesn’t at this point.
Step 4: “Push” Synchronizes these changes with the gitlab.fabcloud server. You’ll likely be asked to login and here you’ll again use your fabcloud credentials.
If you can use SSH use these instructions:
Before we can clone anything, we need to generate an SSH key for our computer. SSH is a encrypted (secure) method for communicating between different machines (be they computers or servers). Only devices with the “key” files can unencrypt the messages sent between the machines. We must generate a key pair on your machine. We need to generate what is called “Asymmetrical encryption” key pair. This consists of a private key (the file which stays on your computer and is not shared) and the public key (which you send to the other machines). Basically, the public key can encrypt messages and send them to your computer which can be decrypted by the private key. More info here.
To generate the keys, Go to Help—> Show SSH Key
In the new window click “Generate Key.” It will ask you to enter a password twice. Make sure to enter the same thing. Next, it will fill out the text box with what looks like gibberish. This is good! That’s the public key. You need to copy this to your clipboard so we can paste it into the website.
Add the SSH key to your gitlab.fabcloud.org account.
Login to your gitlab.fabcloud.org account (remember that it uses fablabs.io login credentials, don’t make a new account, be sure to click the button regarding FabLabs.io and login there.)
Click on your profile icon at the top right of the screen and visit “settings”
In the left column, click “SSH keys”
Paste your public key into the textbox labeled “key.” When you paste it, it should bring up the name of your computer. You have to then click the “Add key” button at the bottom to save this.
Once you do this, you can close the “Generate Key” window and you’re back to the “Clone Existing Repository” window.
The next window asks for two locations. “Source Location” refers to the one on the web server and “Target Directory” is the folder on your local machine you want to store it in.
To get the source location visit that new project you started earlier at and at https://gitlab.fabcloud.org/. At the top right click the blue “clone” button and copy what it says in the SSH window: Example:
git@gitlab.fabcloud.org:acharris/base.git
My username is acharris and I named my repository “base.”
The important thing here is that the folder you want to put it in cannot already exist. So I typed in “base” at the end of the line. Git GUI will create the “base” folder, then store my “base” project in there.
It’ll ask you for your login, so go ahead and type it as many times as it asks for it.
Once it is finished, it will open up the regular Git GUI interface window. It has now created a local branch. (Local means your computer, remote means the gitlab.fabcloud.org server)
In the future, you won’t need to clone this again, You can just “Open from Existing” at the first screen and it’ll bring you right to this window.
This can look intimidating, but it is really simple. First, take a look at the folder we created on your machine. Go to “Repository—> Explore Working Copy” This is the local copy (local branch) of the folder from the server (remote branch). We can add/delete/change any files or folders in this folder while we are working, then upload them all to the server when we reach a good stopping point for the day and it’ll merge the files with anyone else’s who has been working on the same project.
Let’s do a simply workflow.
Let’s change the README.md file. Open it in a text editor (such as sublime or notepad++) and put some text in there. Something like:
I did it!
Save and close the file. Now go into the Git GUI window and notice the buttons. Each time you want to upload files to the server. We will always click these buttons in order from top to bottom, starting with “Rescan” This will magically detect all changes in the project folder. you’ll see the file names in the left Pink panel and the file contents in the right Yellow panel. For now you should just see your txt in green with a + sign in front of it. This pane shows any added or removed text from what is on the server. 
The next button “Stage Changed” will move the files from the top pink pane to the bottom green one. If you only want some of the files and not others, then you can click the icon next to the file name to change its location.
Slight detour… Warning: LF will be changes…
At this point you might get a popup on windows stating
Warning: LF will be replaced by CRLF in README.md. The file will have its original line endings in your working directory
This helps windows and linux compatibility, but in some cases (such as EagleCAD board files) it can break stuff. First we need to unstage the file we just staged by clicking at the top menu bar Commit –> Unstage from Commit then we need to turn that feature off by opening the file base/.git/config and adding autocrlf=false after ignorecase – true line and clicking save. If you can’t see the folder named “.git” it’s because windows is hiding it from you. In the windows file browser, click “view” and check “Hidden items” and “File Name Extensions” and you should be able to see it.
Now you can stage without the issue. This change only affects this one project now, but if you don’t want Git to change ANY files in this manner you can go to a command line, cd into a git project directory and enter the following:
git config core.autocrlf falseBack on track, Sign Off:
Next you want to add text to the comment box:
GIT GUI recommends:
First line : Describe in one sentence what you did.
Second line: Blank
Remaining Lines: Describe why this change is good
Sign Off.
Type your comment, then click the next button in the list to “Sign off” on the changes. It’ll paste a template in the “Comments” textbox. This says that you in particular were the person who uploaded stuff. This is helpful later when something breaks and you want to find out who to yell at.
The next button it “Commit” which will add this to the local branch of the Git repository file. When you click this, the files disappear in the Green pane. This does not mean it it available on the web however.
I hear you asking “Well I just copied the file into that folder, isn’t it already there?”…
The answer is yes and no. It’s on your computer, but it isn’t part of the project from the project. You need to tell Git this new version is what you want to use.
You need to click the last button to “Push” to upload these changes to the server. This will synchronize the entire folder, changes, comments and all to the remote branch (server). A window will pop up and just click “Push” again. You’ll be asked for the password again.
Now what happens if you screwed something up? Well…. don’t. You have plenty of opportunity to check things out before actually Staging, Committing, and Pushing. That’s the hope at least. In practice when stuff gets screwed up somehow or another.
You can fix the error quickly, then push a new copy to the server or you can try to rewrite history. This can get really messy and I do not recommend anyone mess with this unless you know what you are doing with Git already (which I assume is not the audience of this tutorial.)
Customizations:
The base version of Git GUI won’t help much as it is too limited. You have to end up using git commands. There’s two ways to do this. One is to go to you’ll have to get into the Git Bash screen (accessible from the “Repository” menu item at the top of the screen.) Another is to add the commands to Git GUI’s menu. (Wait.. What!?)
Click on Tools –> Add and you’ll be asked for a name you want to add, and the command. Check this one out for instance. Before you push, this will revert the file back to the version from the remote branch (the server):
