FujiNet is a fun project with many repositories and developers. However, that can at times lead to a turbulent git history, and lead to difficulties later down the line when someone needs to bisect the repository to find when a particular change affected some element of the project.

The following is an attempt to give people some simple instructions on how to develop in a consistent manner with git, which will lead to cleaner history, and an easier time for everyone on the project viewing and understanding changes.

Throughout this guide, I will use the fujinet-apps repo as an example, but it applies to any other repo in the project.

Some follow up reading after this page are the sub-pages of this guide:

• Git Aliases to ease your life
• Git History Examples
• Upstream.sh - script that does it all

If you have not already done so, set up your GitHub account and log into it.

Then, if you have not done this for GitHub before, create a new ssh key pair, as described here: Connecting to GitHub With SSH - Generating a New SSH Key and Adding it to the SSH Agent

Finally, add the public key just generated to GitHub, which can be done following these steps: Conneting to GitHub With SSH - Adding a New SSH Key to Your GitHub Account

You should first fork the repository on github through your personal account, then clone it locally:

git clone [email protected]:markjfisher/fujinet-apps.git

This will allow you to easily fetch changes from other developers, and combine them with any changes you are also in the process of making.

You should only do one of the following:

# If you are going to create Pull Requests in GitHub (the norm for most developers)
git remote add upstream https://github.com/FujiNetWIFI/fujinet-apps.git

# If you have direct push access, then use:
git remote add upstream [email protected]:FujiNetWIFI/fujinet-apps.git

$ git fetch upstream master
$ git merge upstream/master --ff-only

Updating a853c6a7..dc641090
Fast-forward
 apod/CHANGES.txt                 |  3 +++
 ... other changes here
 9 files changed, 85 insertions(+), 16 deletions(-)

The above should be done at the start of all new development, so you are working off the latest changes in master.

If you pulled any changes down (maybe your repo hasn't been updated in a while), you can now push these latest changes to your own fork:

git push

Let's say I'm adding a new example application called "ipify" to the apps repo. It's going to be cross-platform, so I'm going to call the branch xp-ipify and commit my work into the branch.

$ git checkout -b xp-ipify
Switched to a new branch 'xp-ipify'

I'm now ready to make my changes, adding files and creating local commits as I need. Finally I want to push my work up to github, and get it into the main codebase.

We first want to ensure we've only created a single commit, if possible, to represent the change. Changes work best if they are small and specific to some higher goal. In this example, I created 5 commits for all the changes, including "WIP" work in progress, and some fixes, etc.

So anyway, we don't want to expose all those changes to everyone else, and we're going to first "squash" the changes into a single commit using git's "rebase" functionality.

(If in your case, you only created 1 commit with a decent subject, then excellent, you can skip down to the section Preparing to push your changes back to GitHub below.)

$ git log --pretty=format:"%h %ad | %s%d [%an]" --graph --date=short -10
* c76e4daa 2023-12-30 | Working ipify (HEAD -> xp-ipify) [Mark Fisher]
* 95e52497 2023-12-30 | oops [Mark Fisher]
* 79b7d432 2023-12-30 | WIP - makefile changes [Mark Fisher]
* 3f89ff22 2023-12-30 | Initial Makefile [Mark Fisher]
* 8c919098 2023-12-30 | Added README [Mark Fisher]
* ... other changes from before we started

We have 5 commits, and to "squash" them into a single commit we issue an "interactive rebase" git command:

git rebase -i HEAD~5

Note the number at the end is because we're going to squash 5 commits in this example, and must come after the ~ character. Change this to the number of commits you are squashing into one.

You will then see a git window for squashing the commits. There is information on what to do in comments in the page it shows. For example:

pick 8c919098 Added README
pick 3f89ff22 Initial Makefile
pick 79b7d432 WIP - makefile changes
pick 95e52497 oops
pick c76e4daa Working ipify

# Rebase dc641090..c76e4daa onto dc641090 (5 commands)
#
# Commands:
# p, pick <commit> = use commit
# r, reword <commit> = use commit, but edit the commit message
# e, edit <commit> = use commit, but stop for amending
# s, squash <commit> = use commit, but meld into previous commit
# ... other information

First notice the 5 commits are in reverse order, the oldest being at the top. Down the left side is currently the word "pick", we need to change all but the first into a "squash".

So, edit the file to look like the following (you can ignore the comment and blank lines):

pick 8c919098 Added README
squash 3f89ff22 Initial Makefile
squash 79b7d432 WIP - makefile changes
squash 95e52497 oops
squash c76e4daa Working ipify

It's always "leave the first as pick, change everything else to squash". You can use just the letter "s" instead of "squash" if you're feeling particularly lazy.

Save the file, and git will work its magic, and then ask you to change the commit message of the overall single commit you're creating.

# This is a combination of 5 commits.
# This is the 1st commit message:

Added README

# This is the commit message #2:

Initial Makefile

# This is the commit message #3:

WIP - makefile changes

# This is the commit message #4:

oops

# This is the commit message #5:

Working ipify

# Please enter the commit message for your changes. Lines starting
# with '#' will be ignored, and an empty message aborts the commit.

You can now craft your final commit message for the single change you're making, e.g.

Add cross-platform ipify app to test network-lib json functions

# Please enter the commit message for your changes. Lines starting
# with '#' will be ignored, and an empty message aborts the commit.

Save and exit your editor, and it will show git's output for the operation.

...
[detached HEAD a10c5625] Add cross-platform ipify app to test network-lib json functions
 Date: Sat Dec 30 18:02:29 2023 +0000
 4 files changed, 4 insertions(+)
 create mode 100644 ipify/Makefile
 create mode 100644 ipify/README.md
 create mode 100644 ipify/ipify.c
 create mode 100644 ipify/ipify.h
Successfully rebased and updated refs/heads/xp-ipify.

Doing another git history will show you now have 1 commit.

$ git log --pretty=format:"%h %ad | %s%d [%an]" --graph --date=short -10
* a10c5625 2023-12-30 | Add cross-platform ipify app to test network-lib json functions (HEAD -> xp-ipify) [Mark Fisher]
* ... other commits from older work here

When you're finally happy with your changes, and have crafted the single commit, you will want to push it back to GitHub.

However, someone else may have already made changes since we started our own work, so we will want to put our changes on top of those before we push our changes back.

THIS IS AN IMPORTANT STEP.

Part of keeping a clean history, and to ensure your changes are not going to conflict with other developers changes, means doing a check to see if anyone else has made a change before you push.

$ git checkout master
$ git fetch upstream master
$ git merge upstream/master --ff-only
$ git checkout xp-ipify
$ git rebase master

If successful, you have put your changes on top of the latest changes.

If git reports an error in the last stage, you will have a merge-conflict. Something in your change conflicted with changes someone else made. You will need to fix the changes, add them to your commit, and finish the rebase.

This is slightly more advanced than this page will go into, and should not happen unless you're making sweeping changes, which would probably mean you already know what you're doing. If not, and you do get a conflict, a quick google search for "git merge conflict" will guide you through what is needed, but it essentially boils down to fixing the issue in your editor, adding the changes to git, then continuing the rebase until git is happy it was able to take the changes. Your IDE of choice usually has ways to help here.

As you get used to git workflows, you will quickly recognise when there are no upstream changes, and so you will not need to rebase your changes, as there's nothing to put them on top of. However, the above is a good working example of how to switch branches, pull changes, then switch back to your own branch and move your work on top of the latest remote changes.

If you're working on your own fork, and do not have direct push access to the main repository (the norm for most developers), you can push your changes to your fork, and then create a Merge Request in github.

Start by pushing your changes:

# If this is the first time you've pushed your branch to github
# use the following to tell it the branch name, but remember to set the branch name to what you are using instead of xp-ipify.
$ git push --set-upstream origin xp-ipify

Enumerating objects: 8, done.
Counting objects: 100% (8/8), done.
Delta compression using up to 24 threads
Compressing objects: 100% (3/3), done.
Writing objects: 100% (7/7), 534 bytes | 267.00 KiB/s, done.
Total 7 (delta 1), reused 0 (delta 0), pack-reused 0
remote: Resolving deltas: 100% (1/1), completed with 1 local object.
remote: 
remote: Create a pull request for 'xp-ipify' on GitHub by visiting:
remote:      https://github.com/markjfisher/fujinet-apps/pull/new/xp-ipify
remote:
To github.com:markjfisher/fujinet-apps.git
 * [new branch]        xp-ipify -> xp-ipify
branch 'xp-ipify' set up to track 'origin/xp-ipify'.

As you can see from the output, github has shown you how you can make a Pull Request, by clicking on the link.

Click the link, and edit the details of the page, and generate a Pull Request. You can mention your work in Discord, and someone will be along to look at your change and check it's in a good shape to merge into the main repo.

Congratulations, you just merged code into the main repository!

Afterwards, you can clean up your branch, by deleting it if you no longer need it.

When the code has been merged, you can go back to the start of this document, and pull the latest changes from upstream to see your changes in the main code line.

If you have appropriate access, you can directly push your changes to the upstream repository.

To do this, if you were developing on a branch, then first rebase your branch onto master

git checkout master             # change to master
git merge xp-ipify --ff-only    # fetch the changes from your branch
git push                        # push changes to master branch of your own fork
git push upstream               # push changes to main repo

As you should have already pulled the latest changes from master and rebased your code (as described in the previous sections), the reverse of pulling your changes into master should just be a matter of moving the master branch pointer to the same commit, and not actually having to do a merge.

There is considerable debate over what makes a good commit message. In the previous examples I deliberately gave some bad ones (like "oops" and "WIP") before squashing them into a single commit with a better message.

Many companies have started using commit messages to contain additional information that helps the build process generate automated change logs, and do automatic version bumping based on the message itself. That's way too much for a project like this one, and requires considerable discipline.

Instead, we should be strive for a few simple goals when writing commit messages, detailed below.

A good read that already covers a lot of this can be found at https://gist.github.com/robertpainsi/b632364184e70900af4ab688decf6f53

The git commit has a specific format. There's a subject line, (which should be kept as short as possible), followed by a blank line to separate the title from the body of the commit message, then the body of the commit message itself, if required.

In most situations, the subject line should be enough, but if you need to add more detail then move it into the body section.

Add ipify app to test network-lib

ipify is a simple cross-platform application that exercises the network-lib
functionality.

Here you can see a short title, the blank line, and the body explanation.

The blank line is actually important, git itself requires it to separate the title from the body, and without it, your body will appear in the summary on the same line as the title, so it's not good enough to start the body text on the line after the subject, there has to be a full blank line.

The git subject line should be able to fulfil the following statement:

If applied, this commit will <your subject line here>

So instead of past tense (e.g. "Added foo to bar"), it should be imperative, or present tense ("Add foo to bar").

Read back the above statement in your head for both examples ("If applied, this commit will..."), and you'll see why Add is better than Added.

As mentioned previously the body should be a full blank line after the title. It can contain additional information that will help maintainers and other developers understand what the change is doing if the subject line isn't enough.

It's very rare that I use this feature, but it can be useful if you want to include things like Issue Numbers in Github, for example

Add ipify app to test json network-lib

This completes issue #1234

where 1234 is the GitHub issue number the change is related to, if you're working on fixing a reported bug for example.

This isn't a place to wax lyrical about your change either. Tests are usually the best way to document your change, but that isn't something we have the luxury of at the moment in this project.

So keep your body short, you can mention platforms here, mention issue numbers, but things like "Used a loop to count the foo so it would be faster to process the bar" does not make for a good body.

A quick way to edit the text of the commit message on your most recent commit you have locally (that hasn't been pushed to a remote server!) is to use:

git commit --amend

This is great if you notice spelling mistakes (and have huge OCD like me), or the message doesn't reflect the change anymore.

So, if you're still crafting your commit, the above command will present you with an editor that you can use to change the title, and even add or change the body. Save that file and exit your editor, and git will update the commit with the new message.

If you want to change the commit message of a change from several commits ago (again, that you have not pushed upstream), then if you look back at the "commands" available when doing the interactive rebase earlier, one of them is "reword". You can use this to change just the git commit message of a particular commit. In that case, keep everything as "pick" except the commit you want to change the message for, and change that to "reword". Save the "commands", and git will then offer you a chance to edit your message on the commit you wanted to change.

I have never done this. Instead, I will squash all commits into a single commit, and so I don't need to change the commit message of something several commits ago. And I would never do this to commits from other people, as you cannot amend commits that have come from the upstream repo, without breaking everyone else's git repo.