November 2, 2021

Working with different git branches

This is more of a note to my future self.

I was working on an wiki, hosted on MkDocs, that you contribute via making changes and pushing to GitLab. The process to submit a change is:

  • fork the repo on gitlab
  • clone the repo locally: git clone ...
  • Create a branch: git checkout -b improv/new-demo
  • Make your changes
  • Add and commit local changes
  • git add docs/
  • git commit -m "improv: Add new demo"
  • Push the changes to GitLab: git push -u origin improv/add-demo-X
  • Create a new merge request from GitLab

Thats fairly straight-forward. However, I was making two separate changes at the same time, each on different branches, and kinda messed up switching between the different branches. I also had to pull a fresh copy from the origin before making the second branch, to ensure I was working on the latest. This is how I set myself straight.

Some concepts first

There is a git server, perhaps using Github, GitLab, AWS CodeCommit, etc, hosting a project want to contribute to. This is the called the remoterepository. If you were the owner, you could simply make the change directly. E.g in GitHub, you could click the 'Edit this file button', but probably you would:

  • clone the repo locally (on your laptop, or a cloud IDE), using the SSH or HTTPS links: git clone [email protected]:jojo786/TelegramTasweerBot.git. In this case, you cloned the default branch (main or master) branch.
  • make the change, and commit: git commit -am "My Change".  Usually you would make a new branch, which is a pointer to your changes.
  • push it back: git push. The git push command is used to upload local repository content to a remote repository. Pushing is how you transfer commits from your local repository to a remote repo. You did'nt create another branch first, so you have pushed straight to master. The full command is actually git push origin main, which origin is the name of the remote repo, and main is the branch.

However, if you wanted to make a change to another repo, owned by someone else, you cant just push back to it. Rather, you fork the repo, then go through a process called a Pull Request or Merge Request (usually shortened to PR), in which you submit your changes, and they can merge it in.  They are the same thing: a means of pulling changes from another branch or fork into your branch and merging the changes with your existing code. So the process would be:

  • Fork the repo
  • clone your fork  locally
  • create a branch: git branch crazy-experiment or git switch -c crazy-experiment
  • Make changes, then git commit -am "message..."
  • push to the new branch on the remote: git push -u origin crazy-experiment. This creates crazy-experiment branch on the remote
  • Then make a Pull Request to ask the owners of the repo to merge your code in.
  • Once the PR is approved, the crazy-experiment branch is deleted both locally and on the remote, and just the main branch is left.

But there are now three different copies of the data:

  • the upstream (GitLab, GitHub, etc)
  • my fork on the remote - which is now my remote origin
  • and my local clone on my laptop

But at any time, the upstream maybe be including other changes, that my fork and local clone is not aware of.

So back to my situation. I have cloned the remote, made a new branch, pushed my changes, and submitted a PR. I then needed to submit another separate/independent change, so I needed to create a new branch. However, my clone of the repo locally, which is from my fork, might have been stale, as changes could have happened to the upstream since I cloned it. I could have simply deleted my local folder, forked and cloned again, to get the freshest copy. But I wanted to see what it takes to get my local repo, fork and upstream in sync. There are different ways to sync a fork, but I preferred this one:

  • After you fork and clone, add the original origin as another repo called upstream: git remote add upstream
  • Make your changes, push, and create a PR
  • After your pull request has been accepted into the upstream repo: Switch to your local main branch: git checkout main
  • Pull changes that occurred in the upstream repo: git fetch upstream
  • Merge the upstream main branch with your local main branch: git merge upstream/main main
  • Push changes from you local repo to the remote origin repo: git push origin main

Hope you enjoyed it|!