Home

🚧 Under construction, sorry for the spelling 🚨

Welcome

Hope you are going well. In this wiki, you can find information on how to use Git & the Unity Package Manager.

This main pages is a step-by-step from A-Z for newbies 😊.
If you look for more detailed information, you can look here:

The Footer on your right 👉
👁 The Issue that I use for my research on the subject
👁 The Magic Door project, that is a group workshop

Ok... Let's start 😈 🤗

Step: Hello Git!

Oooh boy, I hope you know what is Git.

Step: Git what ?

It is an amazing tool that allow you to work with people without having to work with them 😋. You can even work with yourself of the past and create gift for your future self!

Branch	Synchronized

When you use graphic interface, it looks like this. Source Tree example
You have information on:

Who did: what, When, how?
Are they working on development or production?
Are their feature ready or not?

All that without having to talk to them 😎!

Linus Torvalds: Linux, Opensource & Git

"So really, Git kind of arose almost as an unintended consequence of your desire not to have to work with too many people.", Linus:"Absolutely, Yes! 😎" #Epic

Back-Up: You will never lose your files anymore

Git is also the best back-up system for small files ever invented. Why ? You will see that Git is a bit like Dropbox and Google Drive except that you have total control on what happens to your files.

You have a local version that is on your computer(s) and a online version store on the provider you want.

Both have also the complet history of your project: Who did what and when.
Meaning that you can alway come back in time on a stable version. Very easily.

You can't break a project of a team that use Git.

So in case you computer broke. Use the backup of your provider
You provider is down. Use the backup on your computer
If the world is on fire 🌎+🔥, use any local version on one of your harddrive or computer backup. Push your save on the new Lord Commander server to be sure. And you are save again 😎.

Branch: Manage the public and in development state of your work

You can work in team, you can back-up for eternity.
But you can also manage the state of your project.
That what we call in professionnal industry a project workflow.

Relax... You don't need that level of complexity 😅
But when you will, git will be there for you.

Workflow

Don't hesitate to abuse of git in your life

For example, this workshop and every workshops I worked on use git.

Meaning that you can access to the current version on GitHub but also to the archive of it with a git clone and a git reset commands.
I can easily review it with my friend, Vincent, who helped on it since his home.
I can change some of the page from my phone when I see a small change to do.
...

One of my best use of git

I know that normal people cut life & work.
I don't. Because I love coding too much.
So... here is how I use Git.

🏠	🚆	🏢
Code on my gaming computer
Push	Pull
	Work on my laptop with no internet
	Use 4G to push the last work
	Push	Pull
		Code on the office computer
	Pull	Push
	Work on the laptop
Pull	Push
Work on my gaming computer

Ok but how does git work ?

Let's take a project where 🦨 & 🦄 works together. They decided to store the project on the server 🛰 of a provider to works from remote distance. Damn virus 🦠.

🦨	🦄	🛰	GUI	CMD	Description

					Start with project set
🔴🟡					🦨 Created some files
🔴🟡	🟢				🦄 Created one file
🔴🟡	🟢		Stage	🦨 git add .	🦨 Add the modification to the next saveguard
🔴🟡🟣					🦨 Created a new file
🔴🟡🟣	🟢		Stage	🦨 git add "🟣"	🦨 Add the modification to the next saveguard
🔴🟡🟣	🟢		Commit	🦨 git commit -m "Nice work. I worked on 🔴🟡. 🟣 for the moment. 🟣 is not stable but I will correct it soon."	🦨 Decided to make a save call a 'commit' of the current project state with a description for the log explaining what he did.
🔴🟡🟣	🟢		Stage	🦄 git add .	🦄 Add last modification
🔴🟡🟣	🟢		Commit	🦄 git commit -m "dqfj"	🦄 Save on her computer, her work with the comment "dqfj"... 🚨That lazy, f**king licorn. Don't be lazy

					Start to push online
🔴🟡🟣	🟢		Pull	🦨 git pull	It is 16H,🦨Check if the team has push some new work
🔴🟡🟣	🟢	🔴🟡🟣	Push	🦨 git push	🦨 No update, so he can push his work.
🔴🟡🟣	🟢	🔴🟡🟣	Push	🦄 git push	It is 17H, 🦄 is in a hurry and push her save on the server. 🔥🚨🦄 Need to watch the tutorial because you must check first if some one push some update first. 🛰 Send a message:"Update your project first"

				Start to synch on college works
🔴🟡🟣	🔴🟡🟣🟢	🔴🟡🟣	Pull	🦄 git pull	🦄 Ask for the work of the team.
🔴🟡🟣	🔴🟡🟣🟢	🔴🟡🟣		🦄 👀	🦄 Take a look that there are not conflict and her work fit well with the work of 🦨
🔴🟡🟣	🔴🟡🟣⚫	🔴🟡🟣		🦄 👀	🦄 She realized that maybe green is not the best color for the project and change. 🦨
🔴🟡🟣	🔴🟡🟣⚫	🔴🟡🟣	Commit	🦄 git commit -a -m "Ok, I realize that green is not the best color, I switch to black."	🦄 Is in a hurry, so she used '-a -m' to write faster the commands to save her work localy.
🔴🟡🟣	🔴🟡🟣⚫	🔴🟡🟣	Pull	🦄 git pull	🦄 check that 🦨. Did not save on the server while he was correcting the color
🔴🟡🟣	🔴🟡🟣⚫	🔴🟡🟣⚫	Push	🦄 git push	🦄 save the project on the server and run to buy a 🍦 outside because it is 17h30

				Following day
🔴🟡🟣	🔴🟡🟣⚫	🔴🟡🟣⚫	Pull	🦄 git pull	It is 8h am, 🦄 arrive at work and start the project. She pull to check that 🦨. Did not spend the night creating new stuffs. 🛰 Send message: "You are up-to-date. Nice day to you"
🔴🟡🟣🟤🟤	🔴🟡🟣⚫	🔴🟡🟣⚫			It is 9h am,🦨 start to work in a hurry on the new idea he has.
🔴🟡🟣🟤🟤,⚫	🔴🟡🟣⚫	🔴🟡🟣⚫	Fetch	git fetch	It is 10h am, 🦨 want to know if 🦄 added cool color but don't want them now.
🔴🟡🟣🟤🟤⚫	🔴🟡🟣⚫	🔴🟡🟣⚫	Pull	git pull	🦨 like the ⚫ and want to be updated. So he pull the work of 🦄 on his computer

Ta da, that is the classic way to work with Git. There are plenty of scenario to learn:

What if 🦨 & 🦄 work on ⚫ at the same time ?
What if we don't like 🛰 and prefer 🚀 as provider?
What if the client don't like 🟤🟤, how to remove it?
...

But that basically all you need to know as a new user:

git add . to save you change in the project.
git commit -m "Description" to make a back-up point in your computer with description of what you did since last time. (🚨Don't be lazy)
git pull to download what you team did (🚨 Be sure to commit first)
git push to push what you did.
git status to display in console information.

If your team don't work on the same files. That all you need to know...
But it will happens. So you have to learn about Conflict

Con... what ?

Before we start with conflict

There are hundreds of commands you can use with hundreds of parameters. And I don't even talk about branch, reset, rebased... Sub-module... So when you are a new user of git. Just warn the Git 🧠 of the team that you are new. He will be 🌈 to know that you use it. He will helps you through your project.
He will also 👀 on you and consider your like a ☢ DANGER ☣ that need to be overwatch until you know a bit better Git 😅. But that good...

Conflict

What would happens if

🦨	🦄	🛰	GUI	CMD	Description
🔴🟡⚫	🔴🟡⚫	🔴🟡⚫
				Scenario of a conflict
🔴🟡⚫	🔴🟡⚫<🟢	🔴🟡⚫			🦄 Don't like black, it would be better in green.
🔴🟡⚫<🔵	🔴🟡⚫<🟢	🔴🟡⚫			🦨 Don't like black, it would be better in blue.
🔴🟡⚫<🔵	🔴🟡🟢	🔴🟡⚫	Commit	git commit -a -m "..."	🦄 Save black as green.
🔴🟡🔵	🔴🟡🟢	🔴🟡⚫	Commit	git commit -a -m "..."	🦨 Save black as blue

				The conflict is created who will carry the blame?
🔴🟡🔵	🔴🟡🟢	🔴🟡⚫	Pull	git pull	🦄 Check for team change. The project did not change since last time.
🔴🟡🔵	🔴🟡🟢	🔴🟡🟢	Push	git push	🦄 Push her change
🔴🟡 , 🔵⚠🟢	🔴🟡🟢	🔴🟡🟢	Pull	git pull	🦨 Check for team change

Ok, so that a conflict '⚠'.

🦄 & 🦨 both changed ⚫ on their computers.

When 🦄 put the change online she was the only one to change it. So 🦄:💻 and 🛰 dont care.
But when 🦨 Git pull 🛰 on the💻. His 💻 has to make a human choose: Is it 🔵 or 🟢?

It looks like this in the file of 🦨:💻

//Some file lines in front
<<<<<<< HEAD
🔴🟡🔵
=======
🔴🟡🟢
>>>>>>> 1fad089777108917bc99d8899ef70f9a93cc8825
//Some file lines in behind

So if he choose his work, he can replace by:

//Some file lines in front
🔴🟡🔵
//Some file lines in behind

So if he choose her work, he can replace by:

//Some file lines in front
🔴🟡🟢
//Some file lines in behind

So what next ? How does 🦨 will fix the conflict ?

🦨	🦄	🛰	GUI	CMD	Description

				🦨 Will have to fix it
🔴🟡 , 🔵⚠🟢	🔴🟡🟢	🔴🟡🟢	Pull	git pull	🦨 Check for team change
🔴🟡 , 🔵	🔴🟡🟢	🔴🟡🟢			🦨 Choose his color
🔴🟡 , 🔵	🔴🟡🟢	🔴🟡🟢	Stage	git add .	🦨 Add the modification to the next save/commit
🔴🟡🔵	🔴🟡🟢	🔴🟡🟢	Commit	git commit -m "Took 🔵 because reasons: ..."	🦨 Save and explain in a short sentence why he use his work on the last save. To solve a conflict.
				It is fixed, time to push & communicate
🔴🟡🔵	🔴🟡🟢	🔴🟡🟢	Pull	git pull	🦨 Check for update
🔴🟡🔵	🔴🟡🟢	🔴🟡🔵	Push	git push	🦨 Push the save on 🛰
🔴🟡🔵	🔴🟡🟢	🔴🟡🔵		✉🦄 "We had a conflict I change the color based on the specification of the project. Contact me if that a problem."	🦨 In case that important, he just notify 🦄 that he change a commun resource.
🔴🟡🔵	🔴🟡🟢	🔴🟡🔵	Fetch	🛰 Log 👀🦄	🦄 Did not check here mail, but she see that 🦨 push a modification on the server log.
🔴🟡🔵	🔴🟡🔵	🔴🟡🔵	Pull	git pull	🦄 Code is stable. And she agrees. So she decide to take the update.

Machine conflict(s)

Some time you will have conflict because of automatic machine tasks. For example in Unity, there is a folder name Library where the project create, modify delete all the files all the time. In would look like this with our current knowledge of git.

🦨	💻	:---:
🔴🟡	😂🤔😤🤨🚨🤢💀👉✂🙏🦨👷⏳💩→👷↑	9H30
🔴🟡	🤝⏳😴🤨🚀☢☢💤👊☢🌱🤝☣🍕☣🤝🌱	9H40
🔴🟡	⏳⛔⛔☢🙏🤢⛔☢🤝🚨📱🛎🚨✉🛎🚨💩📃	9H50
🔴🟡🔵	⏳⛔☠☠📒←👷📕☢💀👉🤢😴😐👊↑😠→⌛	12h00

So in your project you will have to add what we call: a .gitignore
That will request to ignore some file extention(s) or some folder(s).

As you don't know what to ignore, feel free to ask on google or to go on a website dedicated to that: https://www.gitignore.io/
For example, they propose this for Unity:
https://www.gitignore.io/api/unity

# ... PS '#' is use to comment
/[Ll]ibrary/
/[Tt]emp/
/[Ll]ogs/

*.csproj
*.unityproj
*.sln
*.userprefs
*.pidb
*.booproj
*.svd
*.pdb
*.mdb
*.opendb
# ...

Step: Git, the install !

It is cool to know how it works. But should we not pratice ?
So let's check how to install all that stuffs.

What do you need ?

The tool call 'git' that will communicate between you and the machine
You also don't want to use command lines for complexe situation. So you will need what we call a 💻Client application.
To save, host & synchronised your work you will need a 🖥 Server that run on a web site that is managed by a 🛰 Provider

So let's go.

Git

We are going to install on your computer an application without human interface to communicate with commmand lines between:

your computer
your files and folders
your git server/provider

Download it here:
https://git-scm.com/download/

For Window

Download the installer: https://git-scm.com/download/win
Next > Next > Next > You know the drill
You should now have C:\Program Files\Git\bin\git.exe
Do Win + R > Write & Validate cmd > cd C:\Program Files\Git\bin
Write and validate in the console: git --version
If that fail, check that you are in the folder where install it.
Now we have let's the computer know that he has a git install somewhere.
Look for in Window menu "Edit the system environment variables".
Go in "Environment Variable" in it
In "System" look for "Path" and edit it.
Add your "C:\Program Files\Git\bin" directory in it.
PS: you can maybe see the path of other git install by your clients app if you already have a client: "C:\Users\stree\AppData\Local\GitHubDesktop\bin" for example.
Now you may need to restart your computer to apply the effect
Congratulations, Git is now part of your life 😎 !

For Mac

I am not a mac owner, but I check on my 10 years old Mac recently. You have an application call Terminal where you can write instruction like on Window with command line. When I typed git --version my Mac OS did notify me that git was not installed and that he can do that for me... Cool 😇. If it don't for you: Youtube search: Git Install On Mac - One video about it

💻Client

You can find a long list of client here:
https://git-scm.com/downloads/guis

My favorit one is SourceTree as a developer. But you know the taste and colours...
I tip you to use GitHub App if you are a new and don't want to learn the command lines at all.

🚨If you plan to use it in your work life, note that you will have to study on day the command lines to understand what you are doing 😅

For the sake of your understanding, I will continue to use command line for the rest of the exercice. It is for your own good 😜.

If I am giving you are workshop. I will use SourceTree with developers & GitHub with artists. As am teaching mainly for the video game industry.

🖥 Server / 🛰 Provider

You have to know that a Git is an appliction running on a computer and with a connection to the outside world. So if you don't us a provider, you have to install a website, configure it and pay for every files transfert and requests to it.

So... you will have to find one provider to sell your soul to.

Provider	Comment
GitHub	Main provider by bought by Microsft
GitLab	Good but messy
BitBucket	Sell your soul to Atlassian
Azure Repos	Sell your soul to Microsoft pricing
...	Lot's of alternative

Wich one to choose is a long discussion with lot's of for/against.

Remember in this life, nothing is free.
They sell you a bit of drug until you become addict, you can't quite them.
Choose wisely 🧐 ...

But don't choose for this workshop. Because the show must go on.

GitHub because you will have to create one account on it at one point of time.
GitLab because it allows to store project with no cost and with large files >25Mo when you are alone or in small group.

#FunFact

After a long reflexion, Google decided that Google Play Store would be just one big Git project: millions of lines of code.

Step: Time to practice Git & Package Manager !

I suppose that you know what is Unity and that you know how to do a hello world application with the game engine.

The Package Manager only work with 2018.2+ or more.
If you are on an older version:
https://unity3d.com/get-unity/download

Create new project Quarantine

Unity Hub > New > Check that it is 2018+ > Validate
Go in the root folder of your project Unity.
You should have "Packages\manifest.json" near Assets - Library...
In Manifest.json, add this line"be.eloistree.jimmyscreamfps": "https://gitlab.com/EloiStree/2020_05_28_JimmyScreamFPS.git",

It should look like this

{
  "dependencies": {
    "be.eloistree.jimmyscreamfps":"https://gitlab.com/EloiStree/2020_05_28_JimmyScreamFPS.git",  
    "com.unity.collab-proxy": "1.2.16",
    "com.unity.ide.rider": "1.1.4",
    ...
    }
}

Come back to Unity ... 🤗
You have now imported your first Unity Package from the package manager. Congratulation.

What did you import ?! A Jimmy Screamer to check the FPS 😈 MOauahahah

What? How? Why 😑!?

Go in "Project">"Packages"> "Jimmy Scream FPS" > "Prefab"
Drop in your scene "Canvas Jimmy FPS"
Use the Right Click of your mouse to create Banana
As soon as you computer start to have FPS bellow 60 FPS in average. It starts to scream more and more !
You welcome 🎵.

What happens ?

Unity checks the manifest to update the code usable as side tool in your project. He saw that one of them is a Git repository. He download it and check a file name package.json. If the file and the structure is respected it associates it to your project.

Technicaly, Unity have a tool to create dependences, Example:

you import a car but to run a car need wheel and engine

so it importes wheel and engine but the engine need to import >some engineering tools

so it importes engineering tools.

#Nice
That call NPM but for the sake of simplicity I will pass on that one for the rest of the tutorial.

Create your own one piece-to-piece

Declare yourself

You installed git earlier. But Git still don't know who you are. Would be a shame to not present yourself:

Press Window + R > Type cmd and validate
Set your name git config --global user.name “lastname firstname”
Set your mail git config --global user.email “yourgithubmail”
Later on the workshop, the first time you are going to push to the server, Git is going to ask you your GitHub password to confirm that it is you. Us your mail.
If it you have problem with logging you need to do a task a bit unusual. #TheCredentialIssue

Create a git repository on GitHub

Create your GitHub Account online https://github.com/join and validate
- Or sign-in with your usual account.
Create a repository online with a ReadMe.md file in it.
1. Use the top right ❌ on the top of the screen > "new repository"
  - Set a name like "HelloPackage"
  - set description "My first unity package",
  - set as public (You don't want to start on a SSH private repository in a tutorial)
  - ReadMe file initialized.
2. Create the repository
Let's use that in your project.
1. In the create repository online click on "Clone or download"
2. Copy the given Link that start with "https" and finish with ".git"
3. Press in Window + R > Type CMD and validate
4. Type cd "[The path of your Assets folder of unity]"
  - Ex:"C:\Users\stree\Desktop\MyProject\Assets"
5. Type git clone https://...YourRepositoryName.git
6. It should start downloading your repository in your asset folder.

What is `Git clone` 🤡?

It is a git comment that allows you to say to your computer: this code online, can you duplicate it in this folder and keep a link with the server where I am hosting it.

Nice 👍 and simple, No ?

So now if you go back to your Unity project, you should have a new folder with the name of your respository.

Create a Package.json

Go in Project\Assets\YouRepo that you clone in the step before.
Copy past the following code in a new file that you name package.json:

{                                                                                
  "name":           "country.company.heymyfriendyoulikepatato",                              
  "displayName":    "Hey My Friend You Like Patato",                        
  "version":        "0.0.1",                         
  "unity":          "2018.1",                        
  "description":    "Hey my friend, do you like Patato ? https://youtu.be/hJgQCbRsq-I",                         
  "keywords":       ["Script","Tool"],                       
  "dependencies":{  },     
  "relatedPackages":{
        "ca.teteaclaques.williwaller2016": "0.0.1"
  }, 
  "author" : {
        "name":"Vodka French Fries",
        "mail":"lovepatato@gmail.com",
        "url":"https://youtu.be/5XRiGi1eofQ"
    },    
        "category": "Script"                   
}

What was that.. JSON stuff.. 🧐?
JSON is a meta language, that allow to humain to store in a format some information for the machines that developers will code for you.

So here is a non exhaustive list of what you need to give as information.

Tag	What write in it
name	What is the unique id of the tool country.company.yourtoolname
displayname	What name is displayed for human
version	What is the version of your tool major.minor.buildchange
unity	What min version of unity is required
description	What does the tool do. Or have.
keywords	What keywords to use on the asset store to define this tool
dependencies	What package are required for this tool
relatedpackages	What package are related but not needed for to this tool
author,name	What is your name
author,mail	How to contact you ?
author,url	How to know about you ?
category	What topic of the asset store should it be categorised

You can find more information on this file here:
"what is the full format of package.json possibility ?"

if you don't plan to code, you are almost done

Now that you have define a git in your quarantine project and define a package.json to describe the content of it.
You just need to put some contents in it. Have fun with that task. Be creative.

You can add: Texture, material, 3D models, Sound ... The usual assets.

When you are ready and want to push your work to the team or people using your tool.

It simple Add, Commit, Pull, Push.

Go in Asset\YourRepository
Copy the full path of the folder
Window + R > type cmd
Type: cd "FullPathOfTheFolder"
Type: git add .
Type: git commit -m "What you add since last time"
Type: git pull
Type: git push

To share it, you just need to send this line:

In 2018 & 2019: "com.company.toolname":"https://...yourgitrepolink.git"
- The user just need to past it in the manifest
In 2020+: Just share the "https://...yourgitrepolink.git"
- Past it in: Unity > "Window" > "Package Manager" > '+' > "Add package from git url..."

And what if I am a developer and need code in the package

Then this tutorial will become fastly complex.
So I friendly invite you to go here for a more specific and advance guide:
Hello Package: Advance guide for developers
Please, finish this step-by-step first.

What is a dependency ?

If you design two kitchens for games. I suppose that you want to use some 🔨🔪 utensils. Should they be hardly linked to your chickent:

Yes, then you will only use them in this kitchen
No, then you will be able to use in all your projects.

So that what we call a depenency, "kitchen" when to be dependent of "utensil".

How to do one ?

To do that, you can create two git projects and two package.json

https://github.com/.../Kitchen.git
/package.json

{
 "name":           "be.eloistree.kitchensforquest",                              
  "displayName":    "Ready to use Kitchen for Quest",                        
  "version":        "0.0.1",                         
  "unity":          "2018.1",                        
  "description":    "This package allow to use ready to use kitchen in your game for Oculus Quest",                         
  "keywords":       ["Script","Tool"],                       
  "dependencies":{ "be.eloistree.utensilsforquest":"0.0.1" },     
  "relatedPackages":{  }, 
  "author" : {
        "name":"Eloi Stree",
        "mail":"lovepatato@gmail.com",
        "url":"https://youtu.be/5XRiGi1eofQ"
    },    
        "category": "Script"                   
}

https://github.com/.../Utensils.git
/package.json

{
 "name":           "be.eloistree.utensilsforquest",                              
  "displayName":    "Ready to use utensils for Quest",                        
  "version":        "0.0.1",                         
  "unity":          "2018.1",                        
  "description":    "This package allow to use ready to use utensils in your game for Oculus Quest",                         
  "keywords":       ["Script","Tool"],                       
  "dependencies":{  },     
  "relatedPackages":{  }, 
  "author" : {
        "name":"Eloi Stree",
        "mail":"lovepatato@gmail.com",
        "url":"https://youtu.be/5XRiGi1eofQ"
    },    
        "category": "Script"                   
}

Weird, ... How does the package know how to download one an other 🤔?
They don't. Unity has a server NPM where they register every package they offer to the community. If it is registered, your package will download automaticaly.

If not on their server, you have to add in the manifest the "com.country.appname":"gitlink.git" like you did for "Jimmy Screamer FPS"

You can use "com.unity.my-local-package": "file:/<external_path>/com.unity.my-local-package" for local package on your computer.
You can't use "com.unity.my-local-package": "github..repo.git" for git package on your computer. (Yet) Without additional work on (or future update of Unity).

So for this demo, you should add your repo in the manifest.json :

"be.eloistree.kitchensforquest":"https://gitlab.com/eloistree/2020_05_31_kitchendemo.git",
"be.eloistree.utensilsforquest":"https://gitlab.com/eloistree/2020_05_31_utensilsdemo.git",

More on the subject here:
How to import recusrively package