# Getting started with Git and Github.

:::info
## Table of Contents:
[TOC]
:::

## Introduction

In this document, we aim to provide an introduction to Git and Github for users who have no prior knowledge of them.

Version control facilitates the collaboration of development teams in modifying and updating files in a project, while maintaining a record of changes made over time. Furthermore, this practice helps to avoid duplicate code and prevent conflicts that may arise between different developers working simultaneously on the same project. This way, the complete history of modifications made to each versioned file can be recorded. It is important to note that there are two main categories of version control systems: centralized and distributed.

## Installing Git

### Installing Git on Linux

**1.-** Open the OS terminal.

 ubuntu@Ubuntu:~$

Para actualizar el repositorio de paquetes disponibles en Ubuntu, se debe ejecutar el siguiente comando.

 $ sudo apt-get update

Then install Git

 $ sudo apt-get install git

If you want to ensure that Git installation was successful, you can check the installed version by entering the following command in the terminal.

 $ git -v

### Installing Git on Windows

To obtain Git on your Windows operating system computer, simply select the Windows option and download the installer that is compatible with your system specifications.

[Click here to install the latest version of Git for Windows](https://git-scm.com/download/win)

To install the software, you need to double-click on the installation file and grant permission to the operating system to run it.

**1.-** The initial window of the configuration wizard displays the Git license for informational purposes only. You can read it carefully or simply skip it by clicking on "Next".

**2.-** Please select the path where you prefer to save the Git configuration files and then click on the "Next" button.

**3.-** In the next window, you can see various customizable configurations, such as creating shortcuts on the desktop or enabling Git LFS to handle larger files. It's up to you whether you want to leave these predefined settings or modify them, and then proceed to click on the "Next" button.

**4.-** Please enter the name of the folder where you want to save the projects on your device, or simply keep the default name and select "Next".

**5.-** Please choose the editor you prefer to modify the files from the console and press the "Next" button.

**6.-** The next window has the default option to use Git as the command-line interface and enable the use of git bash to execute Git-specific commands. You can leave this setting by default and continue clicking on "Next".

**7.-** It's time to choose the security bridge to use with Git. Currently, the SSL protocol is preselected as the default option. If you consider it appropriate, you can leave it like that and proceed by clicking on "Next".

**8.-** At this point, the end-of-line conversion configuration will be displayed. Leave the settings as they are and click on "Next".

**9.-** To use Git, it is necessary to have access to a Linux command-line emulator, and to make it easier, you can use git bash. Simply select the default option and click on "Next".

**10.-** On the final screen of the configuration wizard, you will find some additional options, such as the ability to activate file system modification and Git credential manager. We recommend that you leave these options as they are and click on "Next".

**11.-** After finishing the configuration, select the "Install" button, and then choose the "Start Git Bash" option to complete the process.

**12.-** To conclude, choose the "Start Git Bash" alternative.

 $ git --version

### Installing Git on OS

1. Open the OS terminal.

 user:~$

You can check the version of the package manager installed on your computer by querying the version number of the package management software in use.

$ brew -v 

user:~$brew -v
 Homebrew 2.2.12
 Homebrew/homebrew-core (git revision deb5; last commit 2023-04-23)
user:~$

#### Install Homebrew

If you don't have **Homebrew** installed, follow these steps:

[Click here to install Homebrew and follow the corresponding steps](https://brew.sh/index_es)

#### Commands to Install Git on OS

Install Git using the following command:

$ brew install git

## Work Space

When working with GIT, there are three key areas to consider. The first one corresponds to the local workspace, where the developer makes their changes and adjustments. The second is the central repository, where all project versions are stored. Finally, there is the staging area, which acts as an intermediate space where changes are organized before being integrated into the central repository. It is important to keep these three areas in mind to maintain proper control of the project and avoid errors or conflicts in collaborative work.

### Creating a Repository

The process for creating a repository starts at the root directory where the project files are located. Here, the command **git init** is executed to initialize the Git repository. It is a simple and quick process that enables the user to start working on their project and version it effectively.

> cd <MyProyect root>
> git init

By executing this command, the repository is set up and the staging area is enabled. When setting up the repository, a hidden .git folder is generated in the project's root directory, which will be responsible for storing all versions and data of the repository.

> cd <MyProject root>
> git init

Se inicializó un repositorio Git vacío en ./MyProject/.git/

### Saving a Repository

To save a file in the repository, it is necessary to first pass it to the staging area. In this space, the files that you wish to send to the repository are registered, and to do so, the "add" command is used, which allows you to move the files from the local space to the staging area.

Observing this situation, it can be appreciated that the command used was to add the readme.txt file to the staging area.

> git add readme.txt

### Monitoring updates in our repository.

By running the command **git status**, it is possible to check the current status of the repository, which allows us to know if there are new or modified files. In this particular case, the readme.txt file is detected as a new file since it is the first time it is being added to the repository.

> git status
 On branch master
 
   Changes to be committed:
     (use "git rm --cached <file>..." to unstage)
     
                    new file: readme.txt
                    
Untracked files: 
  (use "git add <file>..." to include in what will be committed)
  
  
                    file1/

In addition, it can be noted the presence of files in my local system that have not yet been added to the staging area. In particular, the file named File1 is a folder that, for now, we do not wish to move to the repository.

### Transfer files from staging area to repository.

The **commit** command is used to send the changes made in the staging area to the repository. This command requires the inclusion of a message that describes the changes made. When this command is executed, a copy of the files in the current version is saved and the message is associated with the version. Each version is identified by a unique HASH that corresponds to the files contained in it. In this way, a historical record of the changes made to the code is maintained.

> git commit -m "Project readme file"

[master (root-commit) dc9fb48] Project readme file 
1 file changed, 1 insertion(+)
create mode 100644 readme.txt

When running the command, we are provided with information about the number of files that have been added and those that have been modified. Additionally, we can verify the current status of the repository to know of any changes that have occurred. In this case, it shows that there are no pending changes in the staging area and that folder1 has not yet been included in the staging area. The presence of a file in the repository is also recorded.

### Making modifications to a file already in the repository.

By modifying the readme.txt file, the current state of the repository indicates the presence of a modified file in the local space. However, folder1 has not yet been added to the staging area. To update the repository with the changes, we must repeat the previous steps of adding the folder to the staging area and then to the repository.

The **add** command allows adding new or modified files to the staging area. Later, upon checking the status of the file, it can be noticed that it is in the staging area ready to be sent to the repository through the **commit** command and its corresponding message. Thus, a new version of the repository is created with a different identifier. By following these steps, multiple versions can be maintained in the repository.

> git add readme.txt
> git commit -m "Project readme file"

### Review the log of previous modifications.

 $ git log

In addition to the basic information in the change log, it is feasible to recognize the branch in which the modifications were made and the individualized identifier of it. This unique code provides you with the ability to search for it in the future or revert the **commit** if necessary.

### Achieving synchronization between repositories.

#### Using the "pull" function

To keep repositories synchronized, it is essential to use the **pull** command. This will allow us to download the latest modifications made to the original repository or to its clone, ensuring that we work with the most up-to-date version of the code.

> git pull 

Git is an essential tool for managing version control in collaborative projects. Among its functions, the ability to download content from a remote repository and immediately update the local repository to reflect those changes stands out. This way, remote changes can be merged with the level of your local repository in a common task in collaborative Git-based workflows.

#### The Fork

In Git, a common task is to create a copy of an existing repository in the user's personal account, which is known as a **fork**. The following are the necessary steps to perform this operation on the base repository.

Navigate to the base repository that you created previously in the previous section through your web browser and select the **fork** button located in the top-right corner of the screen to continue.

When a **fork** is made on GitHub, an exact copy of the original repository is created on the GitHub domain, but with the forking user's username and the original repository name. In other words, the user will have a complete and separate copy of the original repository in their own GitHub account.

#### Using Git Push

This action allows transferring data from the local repository to a remote repository to ensure that both have the same version of the content.

### Using the Pull Request

A **pull request** is a request that allows for the integration of new proposals or code changes to an existing project. This request can be reviewed and evaluated by the development team before any necessary changes are made. In this way, it ensures that the project stays up to date and potential code errors are avoided.

To carry out this task, it is necessary to generate a pull request in order to merge the modifications made to the main repository.

An alternative way to express the same idea could be: "To incorporate the modifications made to the base repository, it is necessary to create a **pull request**."

By clicking on **Create Pull Request**, a window opens that allows you to review the differences between commits and view the files involved. At this stage, the user can add relevant comments and detail the changes made before creating the **pull request**.

It has been generated and provides the option to continue adding comments or close it at your discretion.

### Review and Reject Pull Requests

After creating the comment, you have the option to continue the discussion or close the conversation. If at any time you see a notification on your profile indicating a **Pull Request**, simply click on it to open the content and view detailed information, including the author of the pull request, the date, and your corresponding comment.

To view the affected or added files in a **Pull Request**, you can access the tab called **Files changed**. Once there, you will be able to see all the modified files and additions made to them during the **Pull Request** process.

After reviewing the **Pull Request**, a notification will be sent to the email associated with the **Github** account, providing a summary of the observations received during the review.

### Branch Merging

Let's say we want to make a change in the file named **HvGC.html** in the **New** branch. Once the change is made, it is added with the **add** command and committed to the local repository. Later, to merge both branches, for example with the **master** branch, we switch to it with the command **git checkout master**, and then proceed to integrate the two branches using the **merge** command followed by the name of the branch to be merged, in this case, the **New** branch.

Git is capable of merging changes made in two different branches into a single one. If there is any kind of conflict due to both branches being modified, Git will notify the user so they can effectively resolve the conflict and ensure that the merging process is successful. This way, conflicts can be visualized and necessary modifications can be made. Once we have finished merging the changes in the file, we can perform a commit in the main branch **master** and create a new version of it.

By using the **git log** command, it is possible to verify that modifications have been made in both the **New** branch and the **master** branch.

In the main branch called **master**, you can find the initial version, the error-corrected version, and the combination of the **New** branch. Meanwhile, in the **New** branch, you can only find the versions related to the design change. The latest version found in the **master** branch is the one that has been published on the website to update the resume.

### Remote Branches

In this example, we will show how to clone a Git repository and work with both remote and local branches. First, we will clone the repository that contains a folder of documents and a **readme.txt** file to our local space. Next, we will create a new branch in the remote repository and make changes on that branch. Then, we will update our local repository to synchronize it with the remote repository and see how remote branches relate to local branches. Finally, we will create a new branch in our local repository and push it to the remote repository.

Once we have cloned a repository, it is possible to review its log using the **log** command.

We observe that both the **local** repository and the **origin** repository have the **master** branch, and in both repositories the **HEAD** pointer points to this branch. Now, we will proceed to create a new branch called **Introduction** in the remote GitHub repository, and switch to that branch. Using the **git log --oneline** command, it is possible to see that both the local and remote repositories are pointing to the **HEAD** of the main branch, named **master**, and its respective copy on the server, known as **origin**. In the current repository, a modification is made to the **readme.txt** file. An additional line is added in the introduction section in order to improve the presented information. It is important to mention that the edit is made within the same repository to simplify the process and maintain consistency in the file versions.

### Bringing a remote branch to a local branch.

After making the modification, we proceed to perform the **commit**. Once this process is completed, we return to the local repository terminal and execute **pull**.
When the **pull** operation is performed, we are notified that a new **introduction** branch has been added to the remote repository. This means that we can download the latest version of that branch and merge it with our current branch, allowing us to keep our code up-to-date and work collaboratively with other developers.

If we run the command **git branch -a**, we can obtain a list of all the available branches in the current repository. We can observe that the branch named **introduction** is present in the remote repository, but not in the local repository we are currently using. We can list the local branches using the command **git branch -a** and see which branch each one is associated with. Currently, we only have the main branch called **master**. If we want to connect the remote branch of introduction with a local branch, it is necessary to perform a procedure called **checkout**. By performing this procedure, a connection is established between the local branch and the remote branch.

Let's review the branch list once again.

With the local branch **introduction** already created, let's check using the **-vv** option that the association with the remote branch has been established.
This way, the process of creating branches in remote repositories and the corresponding update of local repositories can be observed, maintaining an association between the branches of the local and remote repositories.

## Push a local branch to a remote repository.

Let's use the **checkout** command to switch to the collaborator branch we just created.

We observe that there is a newly created branch in our local repository that has not yet been integrated into the remote repository. At this moment, we will proceed to modify the **readme.txt** file in the corresponding version of this branch, including new collaborators to the file, and then save the changes made.

When you want to save the changes made in your code to the repository, it is necessary to use two essential commands: **add** and **commit**. These commands allow us to add the changes made and make a confirmation of them so that they are registered in the version history of the repository. In this way, changes made can be tracked and previous versions of the code can be reverted to if necessary.

To send our changes to the remote repository, we will use the command **git push --set-upstream origin Collaborators**. This is necessary because we will be creating a new branch in the remote repository. We must specify the name of the remote repository and the name we want to give to our new branch.
When sending the changes, it notifies the creation of a new collaborators branch in the remote repository, which is linked to the branch of the local repository to maintain constant synchronization between both.

Let's take a look at our new branch on GitHub. In this case, we are in the contributors branch, where we can find the file that contains the changes we have made.
Now, let's review the list of branches in our local repository to make sure everything is in order. We can see that we have a branch called "contributors" in our local repository and another one in the remote repository.
To conclude, we will check how the local and remote branches are linked using the **-vv** option.
Now we can verify that the **contributors** branch has been correctly associated with the branch of the same name in the remote repository.

### Git Cheat Sheet

A Cheat Sheet that can be used when putting what you have learned into practice, and increase your skill in using the commands.

$ git init # Create a new Git repository

$ git add # Add files to the staging area

$ git status # Check the status of the repository

$ git commit -m # Move files from the staging area to the local repository

$ git log # View the versions of files in the repository

$ git clone # Clone a remote repository

$ git push # Update the remote repository with your changes

$ git pull # Update your local repository with the latest changes from the remote

$ git add # Add all modified files to the staging area

## Referencias

> Coursera, Git in Spanish, University of the Andes, [Git course in Spanish](https://www.coursera.org/learn/git-espanol)

## LICENSE

Copyright (C) 2023 DECENTRALIZED CLIMATE FOUNDATION A.C.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3
or any later version published by the Free Software Foundation;
with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
A copy of the license is included in the section entitled "GNU
Free Documentation License". 

## Author y Reviewer
> Work developed in collaboration with the [Decentralized Climate Foundation](https://decentralizedclimate.org).

Author:
- [Gustavo Bermudez](mailto:[e-mail])

Reviewer:
- [Omar Octavio Huerta Valdez](mailto:[e-mail])