Insight Blog:
Git commands and tools to enhance your workflow — a practical guide
We all know that git is a version control tool that most, if not all, software developers should be using when collaborating on projects. However, when it comes to its learning process and applications, users face challenges that make this powerful tool seem more difficult than it actually is.
Common issues
So where to start? First of all, having so many options to choose from can be overwhelming, especially for beginners. When navigating online, we come across lists of the most used commands or we pay or subscribe to courses that focus mainly on memorization of code rather than on the situations it could be applied to. As a result, developers often find themselves wandering around or getting stuck trying to learn every single command before they even start writing an actual piece of code.
Additionally, there seems to be a lack of exposure to git at university level courses. That was my experience in Ecuador and the experience of many of my peers. So, the current educational system doesn’t help the situation.
A personal guide to git commands
The purpose of this blog is to help new developers, or anyone who is interested in the subject, become more familiar with git and learn some things that will make their development workflow easier and more productive.
This is not an absolute guide to follow. The knowledge I’m sharing here is based on my own experience regarding things that have worked for me and haven’t worked for me. Feel free to try out my recommendations and pick up the ones that work best for you.
These are the topics I’ll discuss:
- Interacting with your git repository
- Setting your project locally
- Configuring local credentials
- Project status and changes history
- Git branches
- Linking a remote branch locally
- Making changes to the code
- Practical tools
- Using VS Code GitLens extension
- VS Code as default git editor
Interacting with your git repository
I believe new developers should focus on learning basic commands that will allow them to get their job done. The conventions and processes will differ depending on your organization, but some common patterns can be found. Instead of simply giving you a list of commands, I’ll focus mainly on the specific tasks or actions that we usually take to collaborate with others.
Setting your project locally
The first thing to do when starting on a new project is to get it up and running on your local environment (i.e., your computer). In this regard, some organizations will require you to first create a fork of the project before you do anything else.
A fork is basically your own version of someone else’s repository or a copy of a repository that is saved in your account. Creating a fork will vary between different code hosting services (i.e., online spaces where you can store your code), but on GitHub you can easily create a fork by clicking on the button that is located on the top right corner.
Once you do this, the next step is to download or clone the project, which can be achieved by using the clone command.
git clone// Example:
git clone https://github.com/pablodavid97/git-guide-repo.git
Configuring Local Credentials
Now that you have downloaded your project locally, you need to configure your personal credentials. Trust me, this is a very important step because this information is going to be used when you interact with your project and it’s essential for creating and maintaining a good commit history (more on commits in the following sections).
By default, if you don’t set this up, git will automatically create new credentials for you based on your computer’s username and hostname. As a result, your commit messages will start with something like this:
Author: John Doe <john@Johns-Asus-Zenbook.local>
Again, trust me, this is not what you want, especially if you are working on an important project that demands formality. You should strive to configure these credentials before doing anything else, and make sure your email corresponds to your organization’s email and not your personal account. To accomplish this, you can use the following commands:
git config user.name “name”
git config user.email “email”// shows all configurations for current project
git config –list
Project Status and Changes History
After you have everything setup and are ready to start fulfilling your tasks, the following commands can be useful, not only for viewing the status of your project, but also for viewing and integrating the latest changes made by other members. Remember that when working on a project you usually work under branches, and the main or default branch for most projects is commonly named as “master.”
// and if it’s up to date with the most recent changes
git status// allows you to retrieve latest changes made to the current working branch
git pull// displays a history of commits made, as well as who made them, and when
git log
It’s important to note that, in certain situations, communication surrounding a project may not be frequent or ideal. People are busy, emergency situations arise, and fires may need to be put out, so your peers might not have the time to tell you everything they’ve done.
This is when the git log command comes in handy. If you suddenly see a new change made or the project is not behaving as you expected, a good rule of thumb would be to run the git log command and explore the recent changes that have been made. Chances are that changes have been made to the project recently. If you find that is the case, then you can reach out to the author directly for further explanation. Another thing that can alleviate this situation is to keep a good commit message history with helpful details.
If you are interested on how good commit messages and pull requests can help your organization, you can refer to this useful article by our own José Davalos.
Git branches
As mentioned before, whenever you are working on a project, you are usually working under some kind of branch. To be more precise, every time a new feature needs to be added or you are assigned a new task to complete, a new branch should be created.
In this context, we’re coming back to the idea of a main or default branch. The idea is simple. The main branch is the one that contains the final product and combines all features, tasks, and fixes made by all members of the project into one. So, it’s important to know why branches play such a critical role and what commands allow you to navigate through them.
When it comes to branches, the commands that I use most (if not all) of the time are the following:
git fetch// lists all of your local branches
git branch// list all your project related branches
// including all remote ones
git branch -a// creates a new branch
git branch <branch name>// lets you switch or change to another branch
git checkout <branch name>// delete branch locally
git branch -d <localBranchName>// delete branch remotely
git push origin –delete <remoteBranchName>
These commands are pretty self-explanatory, and what they allow you to do is to retrieve, view, create, delete, and move from one branch to another. Once again, these are not the only commands available. There are many more options out there. However, from a practical standpoint, these are the only ones you will need to navigate through the complexity of git branches.
Linking a remote branch locally
This is not a very common scenario and is not very intuitive to grasp when you first encounter it, at least it was not for me. Nonetheless, this situation can occur, and when it does, I hope you are more prepared than I was at the time.
Basically, for a specific task the organization’s policy indicated that a new branch needed to be created using an external tool before linking it to our local environment and making changes to it. This is just the way things worked internally. Now, to be honest, there is not much complexity with the idea behind it and once you learn the commands, it is pretty straight forward. But, the first time you encounter this situation, you realize there is a problem.
What happens is that because you are working with an external tool and probably using a fork to contribute to the original project, the branch that was newly created is not related to your local environment at all, and if you see a reference to this branch, you will probably find it under a remote repository listing. So, a simple git fetch or git pull won’t solve your issue.
This is the point where you start to feel blocked and ask yourself the question: How can I possibly link a branch from an external source to my local environment? But don’t worry, to solve this problem you can choose either one of the following options:
// creates a new branch and links it to remote repository
// Note: when command finishes running, you’ll move to the newly created branch
git checkout -b <local-branch> <remote-repository>/<remote-branch>
// links a local branch with one existing in remote repository
// Note: Local branch needs to be created beforehand for command to work
git branch <local-branch> <remote-repository>/<remote-branch>
My personal preference is to use the first one because it creates and links the two branches in a single line. Again, this is just my personal preference and you can choose the one that better suits your needs and the way you work. There are really no absolutes here.
I hope this will help you if and when you encounter this situation. Until that time comes, keep this information just as a reference since it probably won’t be that common and it won’t be part of your main workflow.
Making changes to the code
Now that you know how to collaborate with others through branches and integrate the project into your local environment, it’s time to learn about the commands that will be part of your main workflow. For this section I have created the list of commands that I use consistently, and I added some comments to explain specifics about them.
Likewise, a bit of background on git is expected, but other than that I think they are pretty self-explanatory.
git add <filename>// adds all files that have been modified
git add *// commits or saves current changes to staging area
git commit -m “<Commit message>”// pushes or sends out saved changes on branch to remote repo
git push// replaces an existing commit in remote repository with current changes
// NOTE: Use with caution since previous changes made will be lost
git push -f// needed for first time pushing a branch to remote repository
// creates a new remote branch and links it to your local environment
git push –set-upstream origin <branch name>// lets you push changes to a specific branch
git push origin <branch name>// lets you push your changes to master branch
git push origin master// removes specific file from staging area
git rm -f <filename>
Practical tools
Below are some amazing tools that will reduce your development time and make your life easier overall.
Using VS Code GitLens extension
Source: GitLens page on Visual Studio Marketplace
GitLens—Git supercharged extension for VS Code—is by far one of the most useful extensions I’ve found and it’s probably one of the first ones that I’ll suggest to other people given the list of benefits it provides. I simply love it and you can check more details about this extension in the VS Code Marketplace.
One of the least favorite things to do as a developer is interact directly with the terminal. Let’s be honest, the command line can be very intimidating, especially for new people. The extensive amount of information and the number of interactions and results you see happening in an instance is a very powerful thing to have, but it can be very overwhelming as well. Therefore, any help you can get to assimilate or manage this information is very much appreciated.
Source control view
One of the first things you notice when installing this extension is the source control tab that shows up on the left side bar.
Source: GitLens page on Visual Studio Marketplace
When you click on this tab, as you can see on the image above, there are many views available for you to choose from and you can explore each of those in your own time. The only one I use—and the one that really provides value to my workflow—is the first view that appears. I use it to perform four specific actions: adding or removing files to git staging, discarding changes made, and viewing any changes that were made to a file.
When it comes to adding or removing files from staging, simply click on the plus or minus icons that appear on the right side of the file when you hover over it.
When you want to discard any changes made to a file, you can click on the back arrow icon that shows up on the screen. Keep in mind that this icon will only show up before a file has been added to the staging area.
Last, but certainly not least, to view any changes I’ve made to a file before creating a commit, I just click on it.
As you can see on the image above, after clicking on a file, a working tree view shows up on the right side of the screen. This is a fantastic thing to have since I don’t have to memorize every change I’ve made. I can just write the code that I need to write and once everything is ready, I can come to this view and double check my work. It’s just a quick step to make sure everything is correct from my side.
In addition, you also have an option to write down a message and commit your changes within the same view just by clicking on the commit button, which is displayed as a checkmark.
Note: If you haven’t configured your local credentials for the project, GitLens will not let you commit your changes as a security measure, so it’s better to have those ready beforehand, as I mentioned previously.
I have been getting more comfortable using the terminal, so I mix these two options in my workflow. I first add/remove files and view their changes using the source control view. Then I create my commit and commit message using the terminal. This approach has been working well for me, but you can find your own style when using these tools.
Viewing other people’s work
The Source Control View is an amazing feature that you’ll use very often. Another very useful feature relates to the so-called git blame annotations. Imagine that you are starting on a new project. You have no idea what is going on around you, and you have been assigned your first task. Let’s say that this project has been on the market for several years and a huge line of contributors have joined and left the workplace.
Then you start to inspect the code and get stuck analyzing one particular function. You have been staring at this part of the code for several hours and you can’t seem to understand what it’s trying to do. Why did someone write it? What was the original request? And what were some of the reasons behind its implementation?
You wonder if you should reach out to someone else but, with so many contributors, who will be the best person to ask for help?
This is the type of situation when this git extension really shines. Every time you open a file, you’ll notice that GitLens displays the author of the most recent commit on top of the file, on each code block (optionally), and also for each line of code.
Source: GitLens page on Visual Studio Marketplace
Along with indicating which one of your peers made the change, it also indicates if this change was a recent one or not. This information is important.
Source: GitLens page on Visual Studio Marketplace
If you want to see more details, you can go even further by hovering over a line of code. When you do this, you’ll see a window popup that shows the author, the date, the commit message, some of the changes that were made, and even the commit hash.
Source: GitLens page on Visual Studio Marketplace
All these pieces of information can give you more insight on the situation of your code. In doing so, they will save you time and help you make better decisions. And if you still need to reach out to someone, you know who the best person to reach out to is.
VS Code as default git editor
By default, git uses the GNU nano text editor when it comes to things like amending your commits or when using the interactive rebase tool (more on these in a later post). This is not the best user experience because the terminal is not the most intuitive tool to use, and it can become tedious if you are constantly opening it to modify large texts.
To set up VS code as your default editor, you can use one of the following commands:
git config –global core.editor “code -w”// setting editor locally
git config –local core.editor “code -w”
git config core.editor “code -w”// reverting back changes
git config –global –unset core.editor
git config –local –unset core.editor
Once you have done so and encounter a situation where an external editor is needed, you’ll see a similar result like the gif below created in this article by Carl Saunders.
Source: Working example of VS Code by Carl Saunders
Summary
In this blog, I covered some important git features that will help you on your daily work. First, I discussed a list of situations and their respective commands to use, especially when interacting with a git repository and collaborating with other people. I also provided information on some of the practical tools that I’ve found through my own experience and the help of my peers.
I hope that after reading this blog you have a larger toolset to help you navigate the world of software development with more ease and efficiency. Know that learning git is a process that is refined with practice. So don’t overwhelm yourself trying to learn or memorize everything at once. Likewise, don’t worry if there is something that you don’t understand. Try to avoid getting stuck in tiny details. Just keep making progress, use the tool, and trust that eventually those things will become clearer in time.
If you have any feedback or new ideas, feel free to reach out.
Give us your feedback! Connect with us now.
