GIT_MANUAL

GIT manual

Please do not TLDR this file, only do so if you know everything about each section.

This manual is written to help contributors do operations on their fork.

add the main repository as a remote

This operation will add the main repository as a remote and allow you to keep in sync with the main repository.

It is particularly useful when a maintainer asks you to rebase your work.

git remote add phpmyadmin https://git@github.com/phpmyadmin/phpmyadmin.git git fetch --all --prune

keep in sync with the main repository

I assume you did follow the operation above or it will not work.

Find the branch to sync. I will assume it is QA_5_0 for this tutorial.

I will also assume origin is the name for your fork. See git remote -v to find out.

And then run:

git fetch --all --prune
git checkout -b QA_5_0
git reset --hard phpmyadmin/QA_5_0
git push origin --force

This operation will reset your branch to the last commit of the main repository.

signoff explanations and instructions

The sign-off line is here to be sure that you agree with the policy. And basically the policy is to be sure your work is yours.

We require that you use your real name for legal reasons. Do not try to use pseudonyms, this will only waste everyone's time and add some additional ping pongs between maintainers and contributors.

adding a mising sign-off line

You have only one commit

git commit --amend --no-edit --signoff and then git push --force

You have multiple commits

Follow Find the base commit steps below to find commitOrBranchNameHere

So you can run git rebase commitOrBranchNameHere --exec 'git commit --amend --no-edit --signoff'

And then git push --force

Find the base commit

To find your base commit. The command git log --graph will show you the local/remote repository.

williamdes@williamdes:/mnt/Dev/phpmyadmintest$ git log  --graph
* commit eceb8c70aaf0a903f515e9cced353b0aa32feeb0 (HEAD -> git-manual)
| Author: William Desportes <williamdes@wdes.fr>
| Date:   Sun Feb 9 21:39:05 2020 +0100
|
|     Add git manual
|
|     [ci skip]
|
|     Signed-off-by: William Desportes <williamdes@wdes.fr>
|
* commit ee1300442a56c14ef7750a84bfe78dee5b31d048 (phpmyadmin/QA_5_0, origin/QA_5_0, QA_5_0)
| Author: William Desportes <williamdes@wdes.fr>
| Date:   Mon Feb 10 09:06:13 2020 +0100
|
|     Add ChangeLog entry for #15187
|
|     Signed-off-by: William Desportes <williamdes@wdes.fr>
|

The base for this example is phpmyadmin/QA_5_0 aka commit ee1300442a56c14ef7750a84bfe78dee5b31d048

Keeping a forked repository healthy

Never use branches from the main repository to make your changes, always create a new branch from it

Why

because you can only create one PR per branch
because you will not be able to keep the fork in sync with main repo
because nobody will understand why a fix or a commit is there
because it will be hard for maintainers to do the git operations needed to merge the PR

Solution

# This will create a branch ready for your fix using the QA_5_0 as base
git checkout -b fix-issue-xyx-i-try-to-describe-the-issue-shortly QA_5_0
# You are on the new branch
# Happy coding !

What PR branch is not for contributors

QA_* branches
master branch
MAINT_* branches
gsoc* branches

You can take any other branch name to make fixes.

Rebase operations and file cleanup

removing a file from a PR

Follow Find the base commit steps above to find commitOrBranchNameHere

# Let's say you want to remove package-lock.json
git reset --soft commitOrBranchNameHere
rm package-lock.json
# Do your commit
git push --force

rebasing up

Nothing more to say. Basically git will hard reset on the given commit or branch and then will cherry-pick each commit and stop when conflicts are present. Please resolve the conflicts and git rebase --continue

git rebase commitOrBranchNameHere

rebasing down

This needs to be followed when you did use master branch instead of QA_5_0 branch for example. Because master branch is in advance onto master branch you can no do a classic rebase operation. You will need to copy commits one by one and fix conflicts.

Very easy and less risky way (squash approach)