Working With a Team— git-flow

Photo by Priscilla Du Preez on Unsplash

Quick links to topics:

Initializing your project; local repo

Initializing your project; remote repo

Collaborating

Working on your local repo

Syncing the remote repo with the local repo

You’ve created a few projects, and when imposter syndrome isn’t in overdrive you feel your skills can contribute to a team. But how DO you work with a team?

Enter git, a version control system(VCS) that does exactly that; gives you and the rest of the team control over different versions of the code for a particular project. A version of code being, code that has some changes on it.

git is not the only VCS but it is far and away the most popular. Even if the team you’ll eventually work with does not use git(again, highly unlikely) by learn the git flow you will grasp concepts that will make a transition to another VCS much more smooth and intuitive.

There are many nuances that I won’t be able to cover in this post. Feel free to reach out to me with questions or suggestions. However, the following will walk you through the setup and daily git-flow of working with a partner or team.

I will add that the walk-through assumes that you and your team have equal permissions when contributing to the remote repo. There are many idiosyncrasies that exist in any team’s work flow but the following git commands can be useful in any team as they are a necessary part of sharing your code.

I am covering this for mac users but all “git” commands are the same for any OS.

Step 0

— create an account on github. As the name might suggest this domain is specifically setup to work with your git project. Before going further take the time to familiarize yourself with the site. There is a lot of new terminology there if this is your first time on the site. Moving forward with this post I’ll assume you have a basic sense of direction on the site and can navigate to your profile to find your repositories.

Make git commands available from your terminal

All you need to do is run:

git --version

This will either show you the version of git you are currently using or it will prompt you to install it. Here is the documentation on getting git to work in your command line.

Note: From here on I will use italics to signal words when they first appear that you should become familiar with in order to move more smoothly while using git.

1. INITIALIZING YOUR PROJECT local repo

A repo is short for repository a you’ll need a local repository as well as a remote repository in order to work with others. There are a couple of ways to go about this but as I said before I won’t be able to cover all the nuances in a single post, we will take one approach that is common and very straight forward.

First: Let’s set up your local repo. Let’s check to see if this directory has already been initialized as a repo. If the file directory has been initialized then it will have a “.git” sub-directory. We can see all files and directories(even the hidden ones) with this command:

ls -a

Aside: Why we would need to check this when you know you haven’t initialized this directory before? Some frameworks, including the popular rails, for ruby, will automatically initialize a new project as a repo without you ever explicitly telling it to do so.

If you see a “.git” directory skip ahead to here.

No “.git” directory, so now let’s run:

git init

Great, you’re halfway there! The code now has it’s own repository on your local machine. We can see that it knows which files have been committed and which files are either untracked or staged to be committed by running:

git status

Both untracked and staged are terms you need to be familiar with but I will not be covering in this post. Here is a great post for more information on those commands, checkout the third paragraph.

Now, let’s setup the remote repo. Again, let’s check that a remote repo does not already exist by running:

git remote -v

This would normally return a list of all the remote repos tracking your local repo. Ours should return nothing because there are no remotes yet. For more information on this command and how to remove a remote, check out the github docs.

1.5 INITIALIZING YOUR PROJECT remote repo

Now let’s head over to github and create a new repository for this project. I strongly advise you give your remote repo the same name as your project or something very similar, but having different names won’t bother git in the slightest.

After you create your new repo you should a list of git commands under “…or push an existing repository from the command line”. We want the first command:

git remote add origin your-specific-url

From the top level directory of your project, run that command. Now your local repo and your remote repo are linked. If we run

git remote -v

again we can see this url path listed!

2. COLLABORATING

A. Giving team members access

You’ll need to decide how much power to give your team members. This is an important decision so check out this full list of privileges in the github documentation.

a. Full Permissions as a Collaborator

Start by having the other team members clone the remote repository to their local machine. Be careful that they do not fork the repository first, but if they do here is an article to walk you through steps to remedy that mistake. In the act of cloning, a local repo will be created on their machine.

To add someone as a collaborator go to your repository on github and follow this path:

Settings > Manage access > Invite a Collaborator

Then find their account and send an invite, don’t forget to have them accept the invite.

b. Some Permissions as a Contributer

Otherwise, make sure your interaction limits allow for others to send pull requests. You can check this by following this path from your repo page:

Settings > Interaction limits

B. Working on Your Local Repo

Make it a rule now and avoid tediously and egregious errors later; NEVER do work on the master branch. The idea is that your master branch will always contain a working copy of your project. Your other branches will be for working on features and should stay as a branch until they are running smoothly, no bugs. So let’s go through how that process will play out.

Inside of your top level directory of your project make a new directory and name it after the changes your implementing with this command:

git checkout -b name-of-your-branch

You’ll see that you have created a new branch and you are now on that branch. Any changes you make will only effect the branch you are currently on, not the master.

We can switch to another, already created, branch at any time by using the command:

git checkout branch-name

We can take a look at all of our branches with the command:

git branch

You’ll notice this shows you all the branches as well as indicating which branch you are currently working on by displaying an asterisk(*) next to your current branch. Go ahead and make sure you are on your new branch.

If you’re following along then go ahead and make a small change on that new branch. Perhaps add a comment in a file, nothing serious. For fun, remember where that change is so we can check it in a few steps. Let’s see what files have been changed by running the command:

git status

Okay, now lets add these changes to the staging area with:

git add filename

or I usually prefer:

git add .

the “.” — dot notation, will add all the files that have been changed to the staging area; usually, but not always, what we want to do anyways. Here is some more information on the “.” along with it’s close relative the “*”.

Next we need to commit those changes to the branch of our local repository that we are currently working in, with the command:

git commit -m "Your message here"

Note that your commit message should describe what and not how you made your changes. Your team members can see the how in the code. The message is a brief overview of what changes were made for future reference. Also try to keep your messages brief. 80 characters or less is a good rule of thumb. If you are having trouble keeping your messages brief then you are probably trying to do too much in one commit; commit more often.

Now all your changes are saved to this branch! Let’s keep three key points in mind before moving forward:

1. Your local master branch has not changed since you last switched to this branch.

2. All of your changes have been committed to your branch that we created a few steps ago, not your master.

3. Your new branch is fully functional. Meaning there are no bugs in your branch code.

Now let’s switch back to the master branch with the command:

git checkout master

Okay let’s look at where we made our change. It’s gone! The master branch doesn’t know about it yet. That’s good because we don’t want it to know about it yet.

C. Syncing the Remote Repo with the Local Repo

This is where the permission level of your teammates will come into play. If they have the ability to push code onto your remote master branch then you’ll first want to get your local master branch up to speed with your remote master branch.

I want to make a quick point that often trips developers up. Your local repo and your remote repo are two separate repos. They are only thinly linked by the url you see when you run the command:git remote -vand they are only kept in sync with each other when you explicitly tell them to sync up; as we are going to do in this next step.

So, from our local master branch we are going to run the command:

git fetch

This makes your local master branch aware of all, if any, changes that have occurred on the remote master branch since the last time you pulled the code down(synced the branches).

We next need to bring our local master branch up to speed with the remote master branch by running the command:

git pull

If there were any changes on the remote master branch, they are now included in your local master branch.

It is important in this step that you are currently on your local master branch. Next we will merge the local branch that has changes on it into the local master branch with the command:

git merge branch-name-with-changes-on-it

You can check to see that the changes exist on your local master branch.

This step and the one before it can result in merge conflicts if the incoming changes happened where your changes also took place. Handling merge conflicts would be too involved to cover properly in this post. However, here is a post that can get you started in the right direction for handling merge conflicts. I promise, like all things, once you get the hang of handling merge conflicts they will become second nature.

Finally, let’s push our local repo’s master branch up to the remote repo’s master branch with the command:

git push -u origin master

Every push after this you can shorten the command to:

git push

but it is best practice to run the first version of this command on your first push to the remote repo.

I hope you found what you came here to find. A git flow vary greatly between teams and so it would be illogical, if not impossible to include everything in one post. That’s why we have the official documentation for using git. But often, as you might already know, the official documentation can be less than intuitive. As I said at the beginning of this post, I am open for questions and suggestions. Just leave a comment below or find me on github.