GIT: Git Essentials at St. Thomas

By understanding how Git works, projects can be easily maintained, shared, and even integrated into automated deployment pipelines.

What is Git?

• Git is a tool that helps you keep track of changes in your code, work with others, and go back to earlier versions if something breaks. Think of it as a “save point” system for your projects. Every time you commit, you create a checkpoint you can return to later.
• Git is called “distributed” because every developer has a full copy of the project history on their own computer.
• A git repository can store scripts, application code, documentation, code examples, and more.
• At St. Thomas we utilize GitHub and AWS CodeCommit repositories depending on the intended use case, audience, and deployment methods.

10 Things to Get Started with Git:

1. Configure User Info:

Before you can clone, pull, or push code to and from a remote repository stored on GitHub or CodeCommit, you need to set up your git configuration. This is outlined in the St. Thomas Development Environment Configuration documentation. 

Before making commits, set your name and email so your work is properly credited:

• St. Thomas Development Environment: set directly in .gitconfig file as specified in the Development Environment Configuration documentation.
• If you are not using St. Thomas organization accounts and require just a simple set-up, you can set your git configuration from the command line.
  • Use your GitHub no-reply email if you want commits to show up on your GitHub profile.

  • git config --global user.name "Your Name"
    git config --global user.email "your@email.com"

2. Clone or Initialize a Repository:

• Existing Repository: Obtain the repository "https clone URL" and run the git clone command:

  git clone https://url-for-provider.com/repo.git

• New, Local Project: To start using Git in a new project locally on your machine (either for experimentation or training without a remote repository in CodeCommit or GitHub), open your project folder in the terminal and run:

  git init

While you can connect an initialized, local git project to a remote repository later, the preferred method at St. Thomas is to create the repository in CodeCommit or GitHub first, and then clone the empty repository.

When creating repositories in St. Thomas GitHub or CodeCommit accounts, please follow proper structure, categorization, and tagging policies to keep it organized.

An initialized or cloned repository creates a hidden .git folder that stores all your version history.

3. Staging and Committing Changes:

• Git uses a “staging area” to let you choose which changes to save. Add all changes:

  git add .
  # Or add a specific file
  git add filename.txt

• Save your staged changes as a commit (a checkpoint):

  git commit -m "Describe your changes"

• Commit Tips:
  • Write clear commit messages so you and your teammates know what changed.
  • Utilize codes such as wip (work in progress), fix (issue fix), feat (feature), or chore (regular maintenance such as documentation or package/library updates) to lead the message:
    • wip: adding new unit tests for phone validation
    • chore: new documentation for xyz configuration
  • Try to change a little at a time. Instead of adding five new features at once in one commit, do incremental changes. It will help when determining if some features need to go live before others, or if you need to go back to a previous commit.

Which brings us to...

4. Pushing and Pulling Changes:

After you add and commit changes, you will need to "push" your work to the remote repository for others to see (and for you to pull later if you move to a different machine). Pushing your changes ensures you don't loose your work if something happens to your machine!

It is always good practice to pull changes regularly, at the start of the work day, when you move to a different computer, or when working in repositories with frequent changes.

Push and Pull regularly to ensure you don't loose any work and that you have the latest changes!

• After one or more commits, push your changes to the remote repository:

  git push

• At the start of your work day, and at frequent intervals on busy repositories, pull changes:

  git pull

5. Branching for Environments:

• Branches are one of the most important features in Git. They let you work on different stages of your project without interfering with each other. In our workflow, we use three main branches:
  • main: This is the stable, production-ready branch. Only thoroughly tested code should be merged here. Think of it as the "live" version of your project.
  • dev: This is where all new development happens. You and your team write and test new code here. It's normal for this branch to be a bit messy as you experiment and build features.
  • test: This branch is for testing code before it goes to main. Once something is ready in dev, you merge it into test to make sure everything works as expected. Only after passing tests does code move to main.
• Why use this workflow?
  • Keeps the main branch clean and stable for releases.
  • Lets you experiment and develop freely in dev without breaking the main product.
  • Provides a dedicated place (test) to catch bugs before they reach users.
• How to create and switch between these branches:

  git branch dev      # create a dev branch (if it doesn't exist)
  git branch test     # create a test branch (if it doesn't exist)
  git switch dev    # switch to dev branch ('git checkout' is the older but still often used command)

• Typical workflow:
  1. Start on dev and make your changes.
  2. When ready, merge dev into test for testing:

     git switch test
     git merge dev

  3. After testing, merge test into main for release:

     git switch main
     git merge test

• If you no longer need a branch (such as a temporary feature or hotfix branch), you can delete it:

  git branch -d temp-test

6. Merging Branches:

• When your feature or fix is ready, merge it into the main branch:

  git switch main
  git pull origin main    # get the latest main branch from remote
  git merge dev          # merge dev branch into main
  git push origin main    # upload changes to GitHub

• Always pull the latest changes before merging to avoid conflicts.

7. Undoing Mistakes:

• Git makes it easy to fix mistakes:
  • Undo the last commit but keep your changes:

    git reset --soft HEAD~1

  • Undo the last commit and remove the changes (careful!):

    git reset --hard HEAD~1

  • Revert a specific commit (safe for shared branches):

    git revert 

  • If you committed to the wrong branch:

    git reset HEAD~1
    git switch correct-branch
    git cherry-pick 

• For more advanced fixes, see the “More Useful Commands” section in the docs.

8. Viewing History and Status:

• Check what’s changed and see your project’s history:

  git status    # see what files changed and what’s staged
  git log       # see all past commits
  git diff      # see what’s different between versions
  git log --oneline --graph --all --decorate  # pretty graph view

9. .gitignore:

• Use a .gitignore file to tell Git which files or folders to ignore (not track). This is useful for things like node_modules/, build folders, or secret files.
• Example .gitignore:

  # Ignore anything starting with dot (common)
  .*
  
  # Ignore zip and log file extensions
  *.zip
  *.log
  
  # Ignore directories
  node_modules/
  dist/
  build/
  
  # DON'T Ignore these
  !.gitignore
  !.nvmrc

• If you already committed a file, remove it from Git but keep it locally:

  git rm --cached filename.txt

10. Diagramming Branches in Markdown:

• You can draw simple diagrams in Markdown to show how branches relate:

  main
   |
   dev
   |\
   test beta

• Or use a code block for ASCII art:

  *--*--* main
        \
         *--* dev
            \
             * test
             * beta

• For more advanced diagrams, visit In-Depth Guide about features of GitHub Flavored Markdown