Git/Github tips specific to Frappe

This guide will help you to use git effectively at Frappe.

Prerequisites

1. Basic understanding of git and github. You should be at least familiar with following commands:

git add | commit | pull | push | clone | log | diff 2. A working git setup with your preferred way of authentication with github already setup (ssh keys). Follow Mac setup guide. 3. Some willingness to get hands dirty with command line. No git GUI tools are feature-complete and to fix some mess you'll need to use CLI.

Understanding git in depth

Git has reputation of being magical:

Only way to solve git problems is to first understand how it works underneath. Spend ~1 hour of your time on understanding the git data model and how commands you enter affect data model of git: MIT Missing semester of your CS Education - Version Control

Branching guideline at Frappe

All our development happens on develop branch of repositories. So any changes you want to get merged should be sent to develop branch first.

Follow these basic steps to ensure you're not stuck with git issues due to poor branching:

1. After installing Frappe apps through bench change origin to your fork, upstream is already set to Frappe's respositories.

e.g. git remote add origin git@github.com:your-user-name/erpnext.git 2. When proposing a change, however small or big always create a new branch with a sensible name. This branch should be created from the branch you want to merge against:

e.g. git checkout -b fix_a_bug develop or if you are back-porting a fix git checkout -b fix_a_bug_bp_v12 version-12-hotfix 3. Do your changes to files and create commits as usual. Avoid cosmetic changes in same commit. Use git add -p to selectively stage desired changes only.

Backporting changes to other branches

We maintain separate branches for stable versions of ERPNext and Frappe framework. If any fixes you've made affect old version then you need to backport the commits to previous version.

Auto Backporting

• Frappe framework and ERPNext repos use mergify to automatically backport pull requests. Request mergify bot to do the backports by adding comment @Mergifyio backport branchname

Auto Backporting - ERPNext [deprecated] (Squashed PRs only)

This bot is deprecated in favour of mergify.

• ERPNext uses a github action to backport squashed PRs.
• Add a label backport branchname where branchname could be a branch where PR has to be backported. E.g. backport version-13-hotfix

Manual backporting

1. As usual create a new branch from branch you want to merge against: git checkout -b bug_fix_backport_v12 version-12-hotfix
2. Cherry pick the changes one-by-one from oldest to newest commit from your other branch.

git cherry-pick commit-sha1-hash OR this single command can move all commits: git cherry-pick your_first_commit^..your_last_commit, if you're feeling brave. 3. If cherry-pick happened cleanly then verify the diff, test the behaviour manually, run unit tests for the affected module and send new PR for hotfix branch. 4. If cherry-pick caused a conflict then you need to resolve it manually and after resolving do git add changed-files and git cherry-pick --continue.

Tips for acting on suggested changes

• You can add more changes to PR by making new commits on the branch and pushing it:

git checkout your_pr_branch

• If changes are minor and should go with previous commit itself then you can stage commit and amend the previous commit.

git commit --amend

• If there are merge conflicts and you want to ensure that PR gets merged cleanly then fetch latest branch e.g. develop and rebase your branch with it. E.g. git fetch upstream develop and git rebase upstream/develop This will update your branch as if you checked it out right now. Any conflicts are there between develop and your changes can be resolved and pushed.
• If you do any changes that modifies history on your branch then you will have to force push using git push -f. However, never do force push on develop or any other stable branches as changed history will affect EVERYONE's forks. Force-push is only acceptable on your own branch.

Syncing forks

• When using Frappe apps, bench update will handle this for you. You can occassionaly push your local develop to your fork to sync it, but there's no harm if you don't do it.

Some commands to learn and master to survive everyday git tasks.

• git merge branch-name merge a branch with current branch using merge commit
• git rebase branch-name change history as if current branch was checked out from target branch.
• git add -p selective staging of changes and git checkout -p selective unstaging of changes.
• git rebase -i HEAD~n (n= last n number of commits to rebase, Interactive rebasing is very powerful, it lets you move, rename, squash, edit commits and MORE )
• git cherry-pick commit-hash cherry-pick a commit from any branch to current branch using commit id.
• git reset [--soft | --hard] commit-hash for moving HEAD to a commit. Useful for resetting local branches to upstream branches. E.g. git reset --hard upstream/develop will make your local branch identical to upstream develop branch. This command wipes out all local changes.
• git revert commit-hash cleanly revert changes for changes that are already merged.
• git reflog git maintains history of all actions, so most dangerous acts are reversible as long as you've checked them in. (lost untracked changes are not retrievable using this.)

Lastly, learn to configure git to change behaviour to your liking:

You can check a sample sample .gitconfig here. Git config can set template for commit message, show diff while writing commit message and many more things!

Resources

• "Pro Git" is comprehensive and "official" book to learn everything about git. Read chapter 1-5 and 7. Available for free: https://git-scm.com/book/en/v2
• Atlassian git tutorials are very easy to follow but often don't go in depth: https://www.atlassian.com/git