Git tips

If you are beginner who just got started with a first big project, you might not understand git and be confused with all the convolutions behind it. The target of this document is to help you get familiar with git and lay out the best workflow for the project.

Note: I recommend to be familiar with the most basic git commands, such as status, add, commit, push, pull, branch, checkout, remote.

Also we need some terminology:

• origin - your fork of the game's main repository on Github (YourAccountName/Community-Game)
• upstream - game's main repository (Hopson97/Community-Game)

What is bad

• merge commits to your master

The thing in a screenshot above is called a merge commit. It happens when you pull from a remote and you have changes that remote doesn't have. Merge commit is just a commit that informs that one branch was merged into the other branch (most commonly fork branch into the main repository branch). Of course it's very useful to know what and when was merged, but the merging we're talking about is done to the main repository.

Unfortunately merge commits also appear in forks of the main repository when someone is working on a feature and has at least one commit that is not in the main repository. Why is this bad? Imagine ~20 people working at the same time. If they are constantly making new commits and sending pull requests, the rest of them will need to pull the changes. If they don't care about this, they'll end up with a lot merge commits. All these commits say that main repository master branch was merged into someone's local branch, which is absolutely irrelevant. It's just like spam. That's why you need to avoid this.

Working on a feature

If you are working on a feature, create a separate branch for it. This way all your work will be separated from the everyone else's work and you'll keep your repository clean, avoiding unnecessary conflicts.

For example: you're implementing an inventory system.

1. First, you need to create a branch for it and work there.

   $ git branch inventory
   $ git checkout inventory
   

   or do both in one step.

   $ git checkout -b inventory
   

2. You create some files and commit them.

   $ git add .
   $ git commit -m "Implemented an inventory system"
   

3. Meanwhile, other guys fixed a crucial bug with world generator and merged it into master. It's always good to keep your branch up to date when making a pull request, so you need to get these changes.

   The best way of doing that is to update the master branch, which is only for the code on the upstream and then rebase changes from master into the inventory branch.

   On branch inventory:

   $ git checkout master # change the branch to master
   $ git pull upstream master # pull the changes
   $ git checkout inventory # go to inventory branch
   $ git rebase master # move all the new commits from the master branch before your current work
   

   Or, if you don't need new changes in your master right now and don't want to type so much, then you can pull changes with the rebase instead of merge.

   On branch inventory:

   $ git pull upstream master -r # -r stands for rebase
   

4. Then you need to push your changes to your fork and then make a pull request.

   $ git push origin inventory
   

   And now you just make a pull request from origin/inventory to upstream/master. When your PR is merged you can safely delete the inventory branch, or, if you want to continue working on the inventory system, just pull the merge as described in point 3.

If you have any other questions regarding git, please PM to Bravo555 on the Discord server.