--- title: "Git/Github tips specific to Frappe" space: "Handbook" url: "https://frappe.io/handbook/frappe-git-tips" updated: "2026-05-07" --- 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](/handbook/mac-dev-setup). 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: ![Git magic](https://imgs.xkcd.com/comics/git.png) 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](https://missing.csail.mit.edu/2020/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](https://docs.mergify.io/commands/#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](https://www.atlassian.com/git/tutorials/rewriting-history/git-rebase) ) - `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](https://github.com/ankush/dots2/blob/master/.gitconfig). 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](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](https://www.atlassian.com/git)