How to make and commit changes in a project from GitHub

First, make sure you have installed the required dependencies and can run the project locally. Check out parts one and two of this series if you need help with either of these.

Create a new branch

If we run git status in the terminal, we can see the current branch, likely main or develop. We don’t want to make our changes directly on the main branch. This is where the magic of Git comes in. We can create a new branch to serve as our separate space to work and make changes.

You can create a new branch with:

git checkout -b <branch-name>

This will also automatically check out or switch to the new branch.

Consider best practices when naming your branch. Branches are meant to be short-lived and single-purpose. You do not, for example, want to have a branch called cecelia-changes that you reuse for all your work.

There are likely branch name requirements at your organization or for the project. If not, you’ll want to use a convention similar to this format:

<issue-number>-<category>-<description or name>

like:

714-hotfix-broken-login-button

This article from the Microsoft documentation has some great guidelines for branching, and this Gist contains some additional conventions.

Make and save changes

Now on the new branch, you can make and save your changes to the code.

If you are using VS code, you can type code . to open the current directory in the IDE. Otherwise open the project in the code editor of your choice.

To practice, you can make a small change to your README.md file. Save the changes in your code editor.

Review changes

After saving your changes, it’s a good idea to run git status and confirm which files were updated.

The git status command will confirm our current branch and show which files have been modified. You should review the changed files and ensure there are no unintended changes. Sometimes we may inadvertently alter our package.json and need to correct it or we may need to add files to .gitignore.

Once you’ve confirmed the changes are correct, you will record the changes to the repository.

Checking in your changes is a three-step process. We can think of our changes like a letter we want to mail to a friend. At this point, we have a completed letter. We still need to:

1. Put our letter in an envelope (add changes)
2. Label and seal the envelope (commit changes)
3. Drop the envelope in the mailbox (push changes)

These are represented in the next three steps. For a detailed breakdown of recording changes to a repository and the available options through the process, check out this guide from the Git documentation.

Add changes

When we ran the git status command, we saw the modified files ready to be staged. We can either add these files individually or all together.

git add <file-name>

git add .

This step is like putting the letter inside an envelope. At this point, we could add more files to be staged, just like we could add more pages to our letter because we have not yet sealed the envelope.

Commit changes

We then commit our changes using the command:

git commit -m "commit message here"

By using the -m flag we can pass a message via the command line. If you prefer to use a text editor to write a longer commit message, you can just run git commit and it will prompt a text editor to open.

Just like with our branch name, it’s important to ensure our commit messages are helpful. Your organization will likely have a standard for messages, particularly if they use a tool like semantic-release, which automatically manages which commits are associated with releases. Commit messages may also be automatically associated with issues or other tools as well. For example, here is the commit message format used by Angular.

fix($compile): couple of unit tests for IE9

Older IEs serialize html uppercased, but IE9 does not...

Would be better to expect case insensitive, unfortunately jasmine does

not allow to user regexps for throw expectations.

Closes #392

Breaks foo.bar api, foo.baz should be used instead

After executing our command, we can confirm with git status that there are no changes in the working directory. This means we have sealed the envelope. We can either drop it in the mailbox (AKA, push our changes) or wait until we have more envelopes and deliver them all at once! The next and final part of this series will cover pushing changes and submitting a pull request, so keep an eye out for that next week.