Difference between revisions of "Help Connecting to File Repository"

From vjmedia
(Should I Merge My Branch or Publish a New Branch?)
(Generate an SSH key)
 
(53 intermediate revisions by 3 users not shown)
Line 1: Line 1:
=Help Connecting to File Repository=
+
=The Basic Rundown=
 +
==Read this first!!==
 +
These are the basic steps to connecting to a Git Repo
 +
===1. Account and SSH key Creation===
 +
====Make a GitLab Account====
 +
In a browser:
 +
# Go to http://arcgit.wpi.edu and create a Gitlab account '''with your WPI email address'''
 +
# Email Manzo (vjmanzo@wpi.edu) with your ''username'', '''and''' the ''project(s)'' for which you need access
 +
If you are using Windows, try "Connecting Through Tower GIT Client On Windows" first.
 +
 
 +
====Generate an SSH key====
 +
Open ''Terminal'' (Mac), ''cmd.exe'' (Windows), or equivalent and:
 +
# Generate a new SSH key (Not a Deploy Key!!) locally as described [https://arcgit.wpi.edu/help/ssh/README.md here] using the command '''"To generate a new SSH key"''' (Log in using your Gitlab account credential to view if necessary). You can leave the additionally security password blank if desired.
 +
# Copy the SSH key as described [http://arcgit.wpi.edu/help/ssh/README.md here] using the command '''To copy your public key to the clipboard'''
 +
In a browser:
 +
# Add the SSH key info you just copied (Not a ''Deploy Key'' and '''not''' a ''Fingerprint''!!) to your Gitlab profile [http://arcgit.wpi.edu/profile/keys here]
 +
 
 +
===2. Connecting Through Tower GIT Client===
 +
Download [https://www.git-tower.com/students Tower Pro] as your GIT client; its free for Mac and Windows with a .edu email address and connecting to our repository is streamlined; email its@wpi.edu to request a full license. In Tower,
 +
*click on the Cloud icon (or ''View>Show Services'')
 +
*select GitLab CE/EE
 +
*select OAuth
 +
*enter Host as ''http://arcgit.wpi.edu''
 +
*enter your username and password for your GitLab account
 +
*enter your private token from http://arcgit.wpi.edu/profile/account
 
<br>
 
<br>
===Download & Install a Git Client===
+
[[File:Tower_Cloud.png|400px]]<br><br>
A git client is used to connect to the file repositories for our projects. There are many commercial and free git clients out there. If you don't have one that you prefer, try the ones listed below.  
 
  
'''For Mac:'''
+
[[File:pulling repo.png|400px]]<br>
[http://www.git-tower.com/ Tower]
 
  
'''For Windows:'''
 
[http://eclipse.org/egit/ Eclipse]
 
  
 +
'''Then you’re done!''' With this method, all repositories for which you have been give access will appear in the list. You simply need to clone them to your computer by clicking clone, choosing a place to save the files, and:
 +
## Specifying the name ''git'' as the '''username'''
 +
## Specify the ''private SSH key'' [~/.ssh/id_rsa] as the '''password'''.
 +
<br>
 +
<youtube>https://youtu.be/7x9hvswZT4E</youtube>
 +
 +
===2 Alt. Connecting Through Other GIT Clients===
 +
Alternatively, if you're not using Tower as your GIT client, in your GIT client:
 +
# Clone the GIT project using the SSH URL given on the related Wiki page on this site
 +
## Specifying the name ''git'' as the '''username'''
 +
## Specify the ''private SSH key'' [~/.ssh/id_rsa] as the '''password'''.
 +
[[File:Repo_info2016.png|400px]]
 +
<br>
 +
<br>
 +
<br>
 +
 +
=GIT Basics=
  
 
===Understand Git and Versional Control===
 
===Understand Git and Versional Control===
Line 26: Line 63:
 
# the password.  
 
# the password.  
  
The repository link for each project is given on the project page. The login credentials change all the time, so ask [[User:Vjmanzo|Manzo]] for the current username and password.
+
The repository link for each project is given on the project page. Make an account at the address provided, then ask [[User:Vjmanzo|Manzo]] for access.
 
<br>
 
<br>
 
<br>
 
<br>
Line 53: Line 90:
  
 
[[File:Repopull2.png|400px]]
 
[[File:Repopull2.png|400px]]
<mediaplayer>https://www.youtube.com/watch?v=7x9hvswZT4E</mediaplayer>
+
<br><youtube>https://www.youtube.com/watch?v=7x9hvswZT4E</youtube>
 
<br>
 
<br>
 
<br>
 
<br>
Line 61: Line 98:
  
 
===3. Create a New Branch===
 
===3. Create a New Branch===
While you're working on this project, others will be working on aspects of the project simultaneously. For this reason, we'll create a "branch" version of the project for you to work on. Later on, we'll merge your branch with the master project.  
+
While you're working on this project, others will be working on aspects of the project simultaneously. For this reason, we'll create a "branch" version of the project for you to work on. Later on, we'll either upload your branch as a new branch to or merge your branch with the master project. '''You "Absolutely 100% MUST MUST MUST please-for-the-love-of-all-things-sacred" create a new branch once you have pulled the initial project to your computer.'''
  
 
'''To create a new branch:'''
 
'''To create a new branch:'''
 
*Right click the master HEAD branch and click "Create New Branch from Master"
 
*Right click the master HEAD branch and click "Create New Branch from Master"
 
[[File:repobranch1.png]]
 
[[File:repobranch1.png]]
*Give the new branch a folder name like ''Feature'' and a branch name like ''New_Library''
+
*Give the new branch a folder name like ''MyLastName'' and a branch name like ''NewFeature''
 
[[File:repobranch2.png]]
 
[[File:repobranch2.png]]
 
*Finally, mark the new branch as the new HEAD branch by double clicking it. You will see the HEAD icon change to your branch. Any changes made to the git project files will be tracked in this new branch instead of the master head.
 
*Finally, mark the new branch as the new HEAD branch by double clicking it. You will see the HEAD icon change to your branch. Any changes made to the git project files will be tracked in this new branch instead of the master head.
 
[[File:repobranch3.png]]
 
[[File:repobranch3.png]]
  
<mediaplayer>https://www.youtube.com/watch?v=8jLJHCcu7r4</mediaplayer>
+
<br><youtube>https://www.youtube.com/watch?v=8jLJHCcu7r4</youtube>
 
<br>
 
<br>
 
<br>
 
<br>
Line 77: Line 114:
 
<br>
 
<br>
 
<br>
 
<br>
 +
 
===4. Editing Your project Files===
 
===4. Editing Your project Files===
  
Line 103: Line 141:
 
[[File:repocommitmessage.png|400px]]
 
[[File:repocommitmessage.png|400px]]
  
<mediaplayer>https://www.youtube.com/watch?v=oENIN1Ip4HM</mediaplayer>
+
<br><youtube>https://www.youtube.com/watch?v=oENIN1Ip4HM</youtube>
  
 
<br>
 
<br>
Line 122: Line 160:
 
<br>
 
<br>
  
==Merge Your Branch==
+
====Merge Your Branch====
 
Before we push your changes back to the repository, you'll want to merge your changes with the master HEAD branch.  
 
Before we push your changes back to the repository, you'll want to merge your changes with the master HEAD branch.  
  
Line 137: Line 175:
 
[[File:repomerge3.png]]
 
[[File:repomerge3.png]]
  
<mediaplayer>https://www.youtube.com/watch?v=hGmPhhdBAHE</mediaplayer>
+
<br><youtube>https://www.youtube.com/watch?v=hGmPhhdBAHE</youtube>
 
<br>
 
<br>
 
<br>
 
<br>
Line 144: Line 182:
 
<br>
 
<br>
  
==Publish a New Branch==
+
====Publish a New Branch====
 
If your new branch is so radically different from the original HEAD project on the server, such as a "we made a brand new derivative game from the existing game on the master HEAD", you'll want to push your branch to the repository as a new branch instead of merging your changes. Ask [[User:Vjmanzo Manzo] for permission about this first. In most cases, you will likely just need to merge your changes instead of creating a new branch.  
 
If your new branch is so radically different from the original HEAD project on the server, such as a "we made a brand new derivative game from the existing game on the master HEAD", you'll want to push your branch to the repository as a new branch instead of merging your changes. Ask [[User:Vjmanzo Manzo] for permission about this first. In most cases, you will likely just need to merge your changes instead of creating a new branch.  
  
Line 172: Line 210:
 
<br>
 
<br>
 
<br>
 
<br>
 +
=Using Git and Unity 3D=
 +
==Set up your Unity project to work with Git (or any source control)==
 +
In Unity 3D:
 +
#Navigate to Edit -> Project Settings -> Editor
 +
#Change ''Version Control Mode'' to '''Visible Meta Files'''
 +
#Change ''Asset Serialization Mode'' to '''Force Text'''
 +
#Close and restart Unity3D
 +
In your GIT client:
 +
#Use the following Git Ignores in your client:
 +
<nowiki>
 +
# =============== #
 +
# Unity generated #
 +
# =============== #
 +
[Tt]emp/
 +
[Oo]bj/
 +
[Bb]uild
 +
[Ll]ibrary/
 +
sysinfo.txt
 +
*.stackdump
 +
 +
# ===================================== #
 +
# Visual Studio / MonoDevelop generated #
 +
# ===================================== #
 +
[Ee]xported[Oo]bj/
 +
.vs/
 +
/*.userprefs
 +
/*.csproj
 +
/*.pidb
 +
/*.suo
 +
/*.sln*
 +
/*.user
 +
/*.unityproj
 +
/*.booproj
 +
 +
# ============ #
 +
# OS generated #
 +
# ============ #
 +
.DS_Store*
 +
._*
 +
.Spotlight-V100
 +
.Trashes
 +
Icon?
 +
ehthumbs.db
 +
[Tt]humbs.db
 +
</nowiki>
 +
[[Category:Writings, Papers, Tutorials,and Documentation]] [[Category: Advisor:Manzo]]

Latest revision as of 20:08, 7 July 2021

The Basic Rundown

Read this first!!

These are the basic steps to connecting to a Git Repo

1. Account and SSH key Creation

Make a GitLab Account

In a browser:

  1. Go to http://arcgit.wpi.edu and create a Gitlab account with your WPI email address
  2. Email Manzo (vjmanzo@wpi.edu) with your username, and the project(s) for which you need access

If you are using Windows, try "Connecting Through Tower GIT Client On Windows" first.

Generate an SSH key

Open Terminal (Mac), cmd.exe (Windows), or equivalent and:

  1. Generate a new SSH key (Not a Deploy Key!!) locally as described here using the command "To generate a new SSH key" (Log in using your Gitlab account credential to view if necessary). You can leave the additionally security password blank if desired.
  2. Copy the SSH key as described here using the command To copy your public key to the clipboard

In a browser:

  1. Add the SSH key info you just copied (Not a Deploy Key and not a Fingerprint!!) to your Gitlab profile here

2. Connecting Through Tower GIT Client

Download Tower Pro as your GIT client; its free for Mac and Windows with a .edu email address and connecting to our repository is streamlined; email its@wpi.edu to request a full license. In Tower,


Tower Cloud.png

Pulling repo.png


Then you’re done! With this method, all repositories for which you have been give access will appear in the list. You simply need to clone them to your computer by clicking clone, choosing a place to save the files, and:

    1. Specifying the name git as the username
    2. Specify the private SSH key [~/.ssh/id_rsa] as the password.


2 Alt. Connecting Through Other GIT Clients

Alternatively, if you're not using Tower as your GIT client, in your GIT client:

  1. Clone the GIT project using the SSH URL given on the related Wiki page on this site
    1. Specifying the name git as the username
    2. Specify the private SSH key [~/.ssh/id_rsa] as the password.

Repo info2016.png


GIT Basics

Understand Git and Versional Control

Using a Git client allows us to collaborate on projects with version control. Using a Git client, you can download, or "pull" the latest changes to a project from the server, or "repository", modify them on your computer, and upload, or "push" the latest modified files back to repository.

Simple Help Videos




Using the Repository

You need three pieces of information to connect to the repository:

  1. the remote repository address
  2. the username, and
  3. the password.

The repository link for each project is given on the project page. Make an account at the address provided, then ask Manzo for access.




1. Connecting to the Repository

Inside the git clients, look for something that says "Clone" or "Connect to Remote Repository". Remember: a "local repository" refers to the project folder on your computer (local) not the one on the project server (remote).

Repo0.png

Add the appropriate 1) repository address, 2) username, and 3) password to the connection screen and click connect. You should also select a folder on your computer (locally) where you will store the project files.

Repo1.png




2. Pulling the Files

Once you connect to the repository, the git client should automatically begin downloading, or "pulling", the files from the server to the folder you identified in the previous step. If this did not seem to happen automatically, look for an icon that says "Pull" while selected on the project name of the repository you've connected to.


Repopull2.png





3. Create a New Branch

While you're working on this project, others will be working on aspects of the project simultaneously. For this reason, we'll create a "branch" version of the project for you to work on. Later on, we'll either upload your branch as a new branch to or merge your branch with the master project. You "Absolutely 100% MUST MUST MUST please-for-the-love-of-all-things-sacred" create a new branch once you have pulled the initial project to your computer.

To create a new branch:

  • Right click the master HEAD branch and click "Create New Branch from Master"

Repobranch1.png

  • Give the new branch a folder name like MyLastName and a branch name like NewFeature

Repobranch2.png

  • Finally, mark the new branch as the new HEAD branch by double clicking it. You will see the HEAD icon change to your branch. Any changes made to the git project files will be tracked in this new branch instead of the master head.

Repobranch3.png







4. Editing Your project Files

Once the latest files are pulled, you can close the git client and open the local folder changing files as needed to work on the project (using Unity 3D, or Max, or whatever software is associated with those project files). You won't need to open the git client again until you are ready to "commit" the changes to the local project and "push" them to the remote repository. This is obviously the most important stage in the project's development.


Repolocalfolders.png






5. Committing Changes

Once you made the edits you'd like to your project, open your git client again. It should note the files that have changed since you last opened your git client.


Repochanged.png


You need to "Commit" these changes to the local project so your git client can keep track of what you've done. Enter a "Commit" title and message describing the changes you've made to the project since you pulled the files from the server, and click the "Stage All Files" button to prepare them to be published to the remote repository. Note:Depending on number of edits you've done, the "Staging" process make take a little time before the git client allows you to click "Commit" and finalize this step. This tutorial provides no support if you have commitment issues.

In general, only commit related changes at one time "I modified the color scheme for these files", or "I added a sample instrument". Something simple. Don't wait until your commit message lists twenty different major changes to the project like "I restructured the folders, and deleted the old project, and modified the colors for these files, and...". That will make it difficult for everyone to track the evolution of the project. You do not need to commit all changed files shown in the staging area at one time. You can make multiple commits to keep things organized.

Repocommitmessage.png







6.Merge Your Branch with the Head Branch or Publish a New Branch


Should I Merge My Branch or Publish a New Branch?

  • If you are continuing the development of an existing project such as finishing a specific activity, or improving some aspect of the GUI, you should probably Merge your branch into the master branch as described below.
  • If you are creating new or derivative work based on a template or some existing project such as making new activities, audio samples, characters, cutscenes, mini-games, you should probably Publish a New Branch as described below.

In either scenario, ask Manzo if you are unsure.


Merge Your Branch

Before we push your changes back to the repository, you'll want to merge your changes with the master HEAD branch.

To merge your branch with the master HEAD:

  • Click the master HEAD branch from the left menu and click the "Merge" button to merge your branch to the HEAD branch

Repomerge1.png

  • Select the branch that you'd like to merge onto the HEAD branch

Repomerge2.png

  • Finally, click the Merge button to merge your changes. The final step is to publish your changes to the remote repository.

Repomerge3.png







Publish a New Branch

If your new branch is so radically different from the original HEAD project on the server, such as a "we made a brand new derivative game from the existing game on the master HEAD", you'll want to push your branch to the repository as a new branch instead of merging your changes. Ask [[User:Vjmanzo Manzo] for permission about this first. In most cases, you will likely just need to merge your changes instead of creating a new branch.

To publish a new branch:

  • Click your new branch from the left menu and click the "Push" button

Repopublishbranch1.png

  • Select your branch from the dropdown menu (should be the same Folder>Branch structure on both menus

Repopublishbranch2.png

  • Click Publish Branch

Repopublishbranch3.png







5. Pushing Changes

Finally, "Push" the changes by identifying the "Push" button in your git client. This will push your changes to the server. In some cases, Manzo will tell you when it is appropriate to making a new "branch" project, but, in general, push the changes to the "master" branch.

Repopush.png




Using Git and Unity 3D

Set up your Unity project to work with Git (or any source control)

In Unity 3D:

  1. Navigate to Edit -> Project Settings -> Editor
  2. Change Version Control Mode to Visible Meta Files
  3. Change Asset Serialization Mode to Force Text
  4. Close and restart Unity3D

In your GIT client:

  1. Use the following Git Ignores in your client:
# =============== #
# Unity generated #
# =============== #
[Tt]emp/
[Oo]bj/
[Bb]uild
[Ll]ibrary/
sysinfo.txt
*.stackdump
 
# ===================================== #
# Visual Studio / MonoDevelop generated #
# ===================================== #
[Ee]xported[Oo]bj/
.vs/
/*.userprefs
/*.csproj
/*.pidb
/*.suo
/*.sln*
/*.user
/*.unityproj
/*.booproj
 
# ============ #
# OS generated #
# ============ #
.DS_Store*
._*
.Spotlight-V100
.Trashes
Icon?
ehthumbs.db
[Tt]humbs.db