Appling the Solution

Setting up the Project Structure

For setting up the project let's have a quick review of our main problem and what was the possible solution that we are going to work with.

Our goal is to host on Github a fully fledged project, connecting the individual repositories that are related to it, so we can keep everything nicely organized and with this organization strucutre preventing for example problems such as overwriting unwanted files.

Caution

Keep in mind that errors may occur if while working with Git if you do not pay attention to the actions you are taking on your repostiory!

Do not take this solution as THE definitive guideline for your work. You are responsible for maintaining your repository and any problems that you encounter when using Git for now understanding the basic principles of source control with Git it's your own resposability to try fixing them.

This is why the Git documentation exists!

Let then begin refreshing what we know about our folder structure and the role of each folder on the source control context:

Folder Name	Local Role	"Online" Role
Project	Root folder of the project (parent folder to all the other folders in the project)	Main Repository (stores the referenes of indivudal repositories)
Assets	Children folder of Project	Individual Repository
Backend	Children folder of Project	Individual Repository
Fronend	Children folder of Project	Individual Repository

From this table we can already get to simple conclusion - we are going to need (for the study case presented on the previous section at least four repositories) in our Github.

So, this is where we are going to start working. The first step is then to create the required repositories on Github.

---

Creating the repositories on Github

Tip

Depending on your knowledge with Git you can skip this part and go to the next step - here we are ust covering the basis of repository creation and creating the number of repositories required for the project based on the rule: createdRepositories= expectedSubfolders + 1

Note

Depending on when you are reading this, Github interface may have changed and any images you may find related to the Github interface may be outdated. It's then adviced that you look for the related options with the same functionalities described by this document.

There are many ways of creating a repository and connecting it to Github, but here we are going to work with the easiest way.

Assuming that you have already a Github account, to create a new repository proceed as the steps below:

1. Go to your github dashboard

2. Right-Click on the green button

   

   and select the option Open in new tab

3. This will open a new tab where you'll be able create a brand new repository

   

4. Fill in the fields as indicated

   1. Repository name: this name MUST BE UNIQUE while also matching the project and children folders names
   2. Description: this is an optional field, but it's advised to fill this in with a short phrase that represents what is the repository for
   3. Adjust the visibility to either public of private - this can be changed later (public repositories are visible to everyone, while private repositories are visible just to you and your colaborators) - I won't enter on this subject here, since this is not why I'm creating this document
   4. Check the box add a README file
   5. The other fields can be ignored

5. Click on the button Create new Repository and DO NOT close this tab, you'll need it later!

6. Repeat the steps from 2 to 5 until all required repositories are created

On my case, because my main project is named project and in there I have the folders described on the table above, I'll create 4 new repositories with the following names:

• Project
• Project-Assets
• Project-Backend
• Project-Frontend

Tip

Guidelines for naming files, folders and repositories:

When giving...	Do...	Don't...
... file names	... if your file names are supposed to have multiple words, link the words with an underscore _, for example my_file.txt, also known as snake-case ... alternatively you can make use of pascal-case (MyFile.txt), camel-case (myFile.txt) or kabab-case (my-file.txt) ... check the convetions for file names if you are creating files with code to a specific programming language when giving names to those files	... add spaces words on file names ... give long names - there is a limit on how many characters the absolute path of a file can have ... ignore the coding language specific conventions when naming your files ... use special encoded characters when naming files, like ç, à, á, and similars (note that a few expections apply to this don't, but they are related to language specific convetions, so when not following any convention this should take place)
... folder names	... follow the same rules described above	(The same dont's apply here)
... repository names	... name them using one of the cases described above	(The same dont's apply here)

---

Creating the first local folder

Tip

Depending on your knowledge with Git you can skip this part and go to the next step - here we are just covering the use of clone proccess for the Main repository - and this will be the ONLY one we'll clone.

Now that we have created the required repositories following bot the naming guidelines AND the steps specified above, it's time to start working on our local environment.

HERE, I'll will assume that you followed all the instructions provided and you still have all the tabs with your newly created repositories still opend, so we can progress on the easiset way as possible!

Open the terminal of your preference and navigate to your work folder - if you don't have one, it's then advised that you create a folder anywhere you like to.

Just keep in mind that:

1. Projects folder shouldn't be created on the Desktop - this workspace should just contain shortcuts for installed applications, so it can provide smooth and faster operational system start ups

   I am totally aware that many users like to have the Desktop as the main work directory, but my overall experience pointed for this not being a good practice!

2. Get a folder that you know it's mot limited by your Operational System or your type of account - we never know how much space a project will take from our drive and some operational systems have limited space for pre-defined account folders like "Documents", for example

So with the terminal opened it's time for our first use of the CLI because here we will clone the main repository to that the selected work space. On my case, I selected the folder Tutorials to work with.

On the terminal we are going to clone the main repository, on my case Project with the command below:

git clone https://github.com/vonschappler/Project.git Project_Structure_Tutorial

This command will create the folder Project_Structure_Tutorial inside my Tutorials folder.

On your case the command would be something similar to:

# Replace <your_project_name> by the name of your project at the end of the command
# <your_account_name> and <your_repository_name> will come from copying the link of your repository as described below
# which can easily be pasted on the terminal pressing Ctrl + v on Windows terminals
git clone https://github.com/<your_account_name>/<your_repository_name>.git <your_project_name>

Tip

Remember that I suggested to have the tabs opened? Here is the explanation for this: to get the link of a given repository, go to the repository tab, click on the button code and on the pop up that shows up, click on the button Copy url to clipboard - the icon next to the repository url on the image below

After the clonning process has finished, use the commands below to enter on the recently created folder and start VsCode:

# using the single-command alternative
cd <your_project_name>
code .

# using the multi-command alternative
cd <your_project_name>; code .

# on my case the commands are:
cd Project_Structure_Tutorial; code .

If up to this point you have followed the instructions provided, you should see something similar to the image below on your code editor:

and then it's time for us to include the other repositories to our project as submodules.

---

Adding the subfolders to our project

Now that we have cloned our Project folder to our local repository and we are with our code editor opened, the we can continue implementing this method by adding the individual repositories created as work folders in our project.

The way this will be done at this point is by "cloning a repository inside another", which in more technical terms means that we are going to add submodules our master repostory.

Git has a command that can be excecuted on our integrated terminal (in this part if your code editor does not have this feature you should still be using the previously opened terminal).

The command is listed below and must be executed for all the individual repositories which are related to the project you are working.

On my case i have three other repositories to add, Project-Assets, Project-Backend and Project-Frontend, so this means that I would have to run the following commands on my integrated terminal:

# to create the Assets folder from the diagram
git submodule add https://github.com/vonschappler/Project-Assets.git Assets

# to create the Backend folder from the diagram
git submodule add https://github.com/vonschappler/Project-Backend.git Backend

# to create the Frontend folder from the diagram
git submodule add https://github.com/vonschappler/Project-Frontend.git Frontend

Note

On your project, the links and folder names will change, so remember to copy the repository URL as it was done on before when creating the main project folder, while using the command git submodule add and providing after the URL a meaningful name to the folder where the repository will be saved!

Important

For this to work correctly, be sure to run the command git submodule add while inside the the main project folder. If you are unsure about which folder your are, use the command pwd on your terminal - this will show the full path for the current folder you are on it

After executing the command to add the indivual repositories as submodules of your main project as folders to your loal machine you should see on your terminal a message similar to this:

This message is just telling you that the an individual repository was successfuly added to your project as a submodule and that the special file .gitmodules was created / or edited with success.

On the other hand you'll see on your file explorer of the code editor that something that should look like the image below:

The next step here is now to follow the usual source control flow, which is commiting changes and pushing the changes, on the same terminal that was used to run all the other commands we have ran so far:

# commiting the aggregation of the submodules to your project
git commit -m "Update .gitmodules"

# pushing the changes to Github
git push

# or alternatively
git commit -m "Update .gitmodules"; git push

Assuming the commands were executed correctly, the file explorer will now indicate that you have submodules on your repository, by indicating the folders like displayed below:

while if we inspect the .git folder for your project root folder you'll have access to something similar to this:

Important

Pay the maximum attention to the image above, because this part here will be important for the next section of this document! The folder modules just stores a "copy" of the .git folder of each submodule and this is how it creates and link our main repository to our individual repository!

and on your main github repository you should see something like this:

If you are used to work with Github, you may have noticed that the icon for those folders inside your main project are also a bit different from the usual, as well as their names which have an @ symbol followed by a set of alpha numeric characteres.

What is the meaning of that? Well, this means, for example, that on my case, the main project now have as part of it the a reference to the repository Assets at the commit c236cbe (which is the last commit pushed for this repository) at this time and if we click on that link created, it will move us directly to that repository on that specific commit, just like displayed below:

---

What to do next?

Just proceed to the next section of this document where I'll explain how to work with this structure and how to remove unwanted submodules from your project!