-
Notifications
You must be signed in to change notification settings - Fork 32
Git Guide
To clone the repository, in the directory you want to place the project run:
git clone --recursive https://github.com/OpenVicProject/OpenVic.gitYou can name the directory something else with
git clone --recursive https://github.com/OpenVicProject/OpenVic.git <name>Tip
If you forked the repository, e.g. you don't have write access to the repository, replace https://github.com/OpenVicProject/OpenVic.git with https://github.com/[Your Username]/OpenVic.git and add the upstream project as an upstream remote by running:
git remote add upstream https://github.com/OpenVicProject/OpenVic.git
You can replace every use of origin with upstream when you wish to pull/fetch/checkout (or push) the upstream repository instead of your repository.
To update the current branch of your clone of the repository to the latest commit, inside the repository run:
git pullTo update the current branch to the latest commit of the master branch inside the repository run:
git pull origin masterImportant
If there have been any commits updating the submodules you must update the submodules.
Tip
If you see a merge conflict pulling from master, run git merge --abort and try rebasing from master instead.
To update all the repository's submodules, inside the repository run:
git submodule update --init --recursiveWarning
If any of your submodules contain any changes which have not been committed, Git will not warn you and will erase all of them. Be careful when updating submodules.
Branching can set the cloned repository to a different HEAD commit without modifying a previous sequence of commits.
Branches are used to organize and push requested changes to the repository.
To select a branch, inside the repository run:
git checkout <branch>for example to select the master branch you run:
git checkout masterImportant
Always update your clone's submodules when you checkout a branch.
Note
The master branch this refers to is the local clone's master, not the repository's master. See Pulling to retrieve the latest repository's master.
To create a new branch, inside the repository run:
git checkout -b <new-branch>Use this to create new branches to work on, especially for making Pull Requests.
Tip
Git comes with git gui which is an interactive tool handy for handling adding files, committing, pushing, and branching. If you prefer using a GUI it is recommended.
To commit changes to all tracked files, inside the repository run:
git commit -am "<Message>"where <Message> is the first line of the commit, also used as the title of the commit.
You can specify what specific files to add to the commit with git add <file> or use git add -A to add every file not referenced in .gitignore.
To commit in that case you then run:
git commit -m "<Message>"To write multiple lines you can keep adding -m "<Next Message>" to the git commit
Tip
Git comes with git gui which is an interactive tool handy for handling adding files, committing, pushing, and branching. If you prefer using a GUI it is recommended.
To push your commits to your origin remote on the branch you're currently using, inside the repository you run:
git push originorigin is optional, if you wish to push to another remote with the branch you're using, you can run:
git push <remote>with <remote> being the remote's name.
To push your commits to a specific branch, you run:
git push origin <branch>with <branch> being the origin's branch's name.
Tip
Git comes with git gui which is an interactive tool handy for handling adding files, committing, pushing, and branching. If you prefer using a GUI it is recommended.
To force push, which is necessary when you modify the commit history of a branch like when Rebasing or Squashing, in the repository you run:
git push -fAll options specified in Pushing apply also to force pushing.
Caution
Do not force push to a branch of a repository that other users are relying upon. This will cause merge conflicts for other users.
Rebasing is used when a branch is out of date from the master branch or of related branches.
To rebase, you must first fetch the origin to ensure its up to date
git fetch originthen you can rebase, in this case to the master branch
git rebase origin/masterNote
After a rebase, if you are modifying a repository's commits, see Force Pushing.
Squashing is shrinking down a list of commits into less commits, usually used for cleaner organization.
To squash into a single commit, as is generally expected workflow for OpenVic, run:
git fetch origin master
git rebase -i HEAD~masterif you're adding to the master branch and you're making a singular Pull Request for the master branch.
You can also run:
git rebase -i HEAD~<commit count>if you are squashing your branch down without reference to master, where commit count is the amounts of non-merge commits contained in your branch.
This will then run git rebase in interactive mode, which allows fine control over what to do with commits. You may see something like
pick 24a0751 Update README.md for Archlinux users
pick 0e408c8 Add Window Override
# Rebase 5c739f1..0e408c8 onto 5c739f1 (2 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
# f, fixup [-C | -c] <commit> = like "squash" but keep only the previous
# commit's log message, unless -C is used, in which case
# keep only this commit's message; -c is same as -C but
# opens the editor
# x, exec <command> = run command (the rest of the line) using shell
# b, break = stop here (continue rebase later with 'git rebase --continue')
# d, drop <commit> = remove commit
# l, label <label> = label current HEAD with a name
# t, reset <label> = reset HEAD to a label
# m, merge [-C <commit> | -c <commit>] <label> [# <oneline>]
# create a merge commit using the original merge commit's
# message (or the oneline, if no original merge commit was
# specified); use -c <commit> to reword the commit message
# u, update-ref <ref> = track a placeholder for the <ref> to be updated
# to this position in the new commits. The <ref> is
# updated at the end of the rebase
#
# These lines can be re-ordered; they are executed from top to bottom.
#
# If you remove a line here THAT COMMIT WILL BE LOST.
#
# However, if you remove everything, the rebase will be aborted.
#The comments explain interactive rebasing, but to squash down to one commit you can set all but the first commit to s instead of pick, like so.
pick 24a0751 Update README.md for Archlinux users
s 0e408c8 Add Window OverrideNote
After a squash, if you are modifying a repository's commits, see Force Pushing.
git bisect is a useful tool for project regressions. git bisect binary searches through the commit history between the good and bad commits to assist you in finding the issue. make sure you update the submodules
To begin using first checkout the commit or branch with the issue, for example say master has a regression, in the repository run:
git checkout origin masterthen run:
git bisect start
git bisect badThis marks the master as a bad commit.
Then get the last commit or tag where the issue was not found, for this example we'll use commit 0e408c8, run:
git bisect good 0e408c8This marks commit 0e408c8 as a good commit.
Git will checkout a middle commit between the good and bad commits which you can test for the issue. If the commit does not have the issue run:
git bisect goodelse if it does have the issue run:
git bisect badthen Git will checkout another commit for you to test, keep repeating this process marking commits as either good or bad until it says <sha> is the first bad commit in which you will have found the first commit with the issue.
Important
Always update your clone's submodules after each checkout.
To end a bisect early, run:
git bisect reset