Did you start with some teammates a project but you are not synced due you are editing the same files and are overlapping the changes? This is something common at school or at college. Also if you are an entrepreneur, you might face the same problem. A hint: git could be your solution.
What is git? It’s a fantastic collaboration tool among people who work with the same electronic files and folders. It’s the most powerful tool I’ve ever learnt during my short life in the IT business.
I heard of git for the first time in the final year of my degree program, in Distributed Systems classes. Unfortunately, the content in the class was not enough to provide a full picture of the strength of git. And I think this under utilisation of git is a problem that needs to be solved. Students and junior developers must learn git during the first year of studies, maybe before, at school.
Using git you will have some key benefits such as collaboration between the team, version control and organised workflow.
Even if you are not going to develop, even if you are a manager or the owner of an IT company, you need to know the basics of git.
Git is a free and open source distributed version control system designed to handle projects.
- Free: everyone can use it.
- Open source: the documentation about it is enormous in the internet.
- Distributed: different people are able to work at the same time with the same files.
- Version control system: it’s possible to get the previous state of any file, and also it’s valid to come back or go forward from that state.
- Handle projects: any app, documentation, draft or plan can be managed with the help of git.
Git Web Services
Some web services use git to provide users the ability to extend the power of git without responsibility for server maintenance. So you as a git user don’t need to create a web server to host all the infrastructure that git requires. This web services are in the cloud, so everyone can make an account and start using it. There are a few different cloud services providing git, but personally I prefer GitHub because it has some benefits:
- Most of the people use GitHub. So people will be familiar with the interface when you look into internet for a solution to a code problem or a discussion about software.
- It was acquired by Microsoft recently and the new features grew a lot in recent months as they are integrating GitHub with other tools such as npm.
- Third party applications and integrations are numerous and the community is growing each day.
- Reliability is very high; my short experience tells me other services are down more frequently.
Regardless of your choice of service, all the main concepts of git are equal for all git cloud providers. Bitbucket and GitLab are the more common rivals, but there are other open source services such as Gitea, Gogs and many more.
GitHub is free, but there are some purchase options for companies to manage users and special privacy settings.
It’s common to extend git from the command line with a tool that helps the user trigger actions by clicking buttons instead of running commands on the terminal.
Some of these tools are Fork, Sourcetree or GitKraken. Anyway, before using any tool to improve your speed using git, it’s really important to first learn the command line options, to understand each step. So in this article we are just going to run git commands in the terminal.
Follow these steps to start learning git.
- Instal git from its official site.
- After installation, verify you have installed it correctly running in a terminal:
- Create a GitHub account. You should fill out the entire form to create an account.
Let’s start with a basic exercise:
- Create a new repository.
- Write hello-world as repository name.
- Click on Create repository button.
- Open the terminal and run the following commands:
mkdir -p ~/Documents/GitHub/hello-world
echo "# hello-world" > README.md
git add README.md
git commit -m "First commit"
git remote add origin https://github.com/<USERNAME>/hello-world.git
git push -u origin master
At this point you should be prompted for a username and a password. The username is the one you chose when you created the GitHub account. The password is NOT the password you use for your account. Instead of using the password, you should use an auth token created in GitHub.
You are not authorised to perform the
push to the remote repository in the GitHub cloud without this username and password (auth token). This is because your computer needs to store the GitHub credentials and use this credentials to perform secured calls to the GitHub API. If you previously stored the credentials in your computer, the
push should work without problems.
- Open the tokens page in GitHub.
- Click Generate new token.
- Type a name and select all scopes. The name doesn’t matter at all. You can create infinite different tokens with different scopes and names.
- Copy and keep safe the generated token; you won’t see it again.
- Come back to the terminal and fill the username with your GitHub username and for the password enter the auth token you have just created.
6. Check the repository:
https://github.com/<USERNAME>/hello-world (remember to change the USERNAME for yours).
You should see a file uploaded, the README.md file.
The .git folder is a hidden folder which contains the configuration and credentials for the repository and is kept in your local computer; it’s not uploaded to the cloud repository. If you remove this folder, you will need to set up the repository and its configuration again from scratch, so don’t change or remove anything unless you really know what you are doing.
What if you don’t want to upload some files from your local computer to the cloud, such as credential files, dependencies from third party libraries or system files? The answer to this question is a .gitignore file.
This file should be added to the repository folder at the root level; everyone who is working on the same repository needs the file to avoid uploading “trash” files. The file may include entire folders or just files.
Let’s play with an example:
echo "This is an ignored file" >> ignoredFile.txt
echo "This is a file will NOT be ignored" >> notIgnoredFile.txt
echo "ignoredFile.txt" >> .gitignore
git add *
git commit -m "Adding .gitignore"
git push origin master
In the example we’ve created three new files with the echo command:
Then we just added all the files as candidates to be committed to GitHub. You can run git add followed by one, more than one or * referencing to all the files which are different from the remote repository (the repository hosted in GitHub).
After that, the files can be committed using git commit -m “<MESSAGE>”. The message should be something clear and short. Explaining exactly the purpose of the changes made. This is one of the most important parts of git. As git is a collaborative tool, in most cases you are going to work with a team in the same repo. If a commit message doesn’t offer good context, the shared work becomes really useless.
Once the commit is done, you can create more commits with different changes and different messages for each one.
When you are ready to share your changes with the team, you need to push the changes to the cloud repository in GitHub. The git push origin master command uploads the changes.
After the push in the example, you could check that the ignoredFile.txt is not uploaded while the notIgnoredFile.txt is uploaded to the repository:
Commonly all the repos contains a README.md file. This file is written in markdown syntax. All the instructions and information for the repository should be explained in this file. If you are going to check an existing repository or you are going to start working in any existing repository you should read this file in depth.
The markdown syntax is really easy to learn and very useful too. One of the powerful features which markdown provides is that you can write HTML code inside it and GitHub can render it.
All repositories should have a .gitignore file and a README.md file. If not, your repo doesn’t follow best practice.
Sometimes you don’t want to start a project from scratch. Sometimes there are existing repositories which are valuable for you and you are not able to work directly on these repositories because you don’t have permissions to do it. In this scenario, you can fork the repository, creating a copy of the origin repository to your account. Then you can start working on the copy without changing or even notifying the original.
Let’s check an example:
- Open this link.
- Click the Fork button on the right-top.
- The repository is copied from empathyco organization to your user.
- Check your new repository copied:
You have forked a repository and you may start working from the copy without changing anything in the original repository.
Once you have created a new repository, or after forking any repository, to start working on that repository locally you will need to clone it. Let’s clone the forked repository:
git clone https://github.com/<USERNAME>/ops-whoiam.git(remember to change the USERNAME for yours)
https://github.com/<USERNAME>/ops-whoiam/new/master(remember to change the USERNAME for yours again)
- Write <USERNAME>.txt as name for the file
- Write <USERNAME> as content of the file
- Click on the Commit new file button.
You committed the new file and now there are differences between the remote repository and your local repository.
To get latest changes from the remote repository you can use git pull command.
git pull origin master
Now all the changes are up to date and both remote and local repositories are the same content.
Another important feature of git is the branching model. Until now all the changes were made in the default branch of a repository, the master branch. When a repository is created, all the files are located in the master branch. But the power of git lets us create different branches to work in parallel, test changes without modifying the master branch state or create different workflows. We will talk about git workflows in upcoming sections.
Let’s create a new branch and play with different branches in the same repository:
git checkout -b develop
echo "\n ## hello-moon" >> README.md
git add README.md
git commit -m "Change in develop branch”
git push origin develop
At this point the branches differ. The develop branch has one commit more than the master branch. We can create different branches now, but we are not losing the state of the other branches.
Pull request (PR)
When you or your team is working with different branches, you probably want to merge both branches into one; your development has some new features in the develop branch and you don’t yet have those changes in master branch, the branch which points to the production environment. So after testing your new changes in the develop branch, you may merge it to master and deploy the changes to your production environment.
https://github.com/<USERNAME>/hello-world(remember to change the USERNAME for yours).
- Click on Compare & pull request button.
- You can see the changes between master and develop branches.
- Click on Create pull request button.
- Comments, reviewers, labels and many other options can be added but we can let this as it is now.
- Click on Merge pull request button.
- Click on Confirm merge button.
- Both branches are equal again. Delete the branch as you are not going to make another pull request. Click on Delete branch button.
After these steps, your local master branch is not at the same point as the remote master branch. Run the following commands to pull the last changes onto master branch:
git checkout master
git pull origin master
Now you are up to date.
Tag & Release
When your project is ready to be published or your development has ended, you should create a tag pointing to the last commit. In case you need to add a new feature or you need to fix any bug, the tag still points to that historical commit.
You can create a tag whenever you want, but typically you should create it when you are going to release the code. GitHub provides some features and applications to create release notes from a tag.
Let’s create a tag:
git tag v1.0.0
git push origin v1.0.0
Depending on your team size or the purpose of your project, you should keep in mind the most famous existing workflows:
If your team is very small or you are working alone in a repository, this is the most simple and effective workflow.
For medium-size teams, where team members may work in different features at the same time, in parallel. Any pull request applied to master branch can be releasable to the production environment.
Sometimes you need to work in more than one environment. A medium or large team should work in parallel in a non-prod environment. All the changes applied after the merge of any pull request over develop branch are deployed in a non-prod environment. Commonly after scheduling a date for a release, a merge is applied from develop branch to master branch in order to release a production version.
Sometimes your code needs to be applied and validated through all environments. There is a branch for each environment, so you work in the master branch or a feature branch as a basic workflow. When you need to apply the changes, first you make a pull request against develop branch to deploy the changes in dev environment. If everything goes well, you apply the changes to the next environment. Repeat these until you apply the same changes to production. Using this approach you are validating the changes with a minimum impact across environments.
Open source repositories are owned by a person or an organisation. If you want to contribute, improve or test the open source project, you should follow this workflow. The reason is that you are not able to change anything in the original repository because you don’t have permissions to do it. So you must create a pull request from your forked repository to the original repository. The owner of the repository will review your pull request and decide if the changes are good. If this happens, your changes are now part of an open source project. Congratulations!
Extra ball: GitHub Pages + GitHub Actions
An incredible feature that you can use in GitHub is GitHub Pages. You can render the README.md file in a GitHub domain but you can also deploy your static web app there.
Let’s do it:
https://github.com/<USERNAME>/ops-whoiam/settings(remember to change the USERNAME for yours).
- Under GitHub Pages section, select source as master branch.
- After some minutes, the README.md file will be rendered as single page application under:
- Change or delete any of the following variables for your personal page in src/app/app.component.ts file. You should also add images under src/assets/img if you want to change it to your personal images:
Right now you are able to set GitHub Actions and deploy your custom app to GitHub Pages.
git add *
git commit -m "Customizing my page"
git push origin master
https://github.com/<USERNAME>/ops-whoiam/settings/secrets(remember to change the USERNAME for yours).
- Click New secret button and add “EMAIL” as Name and your email as Value.
- Click New secret button again and add “USERNAME” as Name and your username as Value.
https://github.com/<USERNAME>/ops-whoiam/actionsand enable actions. After that a pipeline should be running to deploy the app. Click the event to see the pipeline details.
- After some minutes, you will see something like this or like this under
Git has so many commands, you’ve just learnt a few of the basic ones. You can check the entire list here.
I made my own list, with the most common commands that I use everyday.
Git is a powerful tool for collaboration, and GitHub helps to use all its power easily. We’ve practiced the basic usage, but this should be the starting point for any student or IT beginner. Commit your life!