diff options
Diffstat (limited to 'documentation/gitcheatsheet.mdwn')
| -rw-r--r-- | documentation/gitcheatsheet.mdwn | 278 |
1 files changed, 278 insertions, 0 deletions
diff --git a/documentation/gitcheatsheet.mdwn b/documentation/gitcheatsheet.mdwn new file mode 100644 index 0000000..4a0e462 --- /dev/null +++ b/documentation/gitcheatsheet.mdwn @@ -0,0 +1,278 @@ +[[!meta title="Documentation/GitCheatSheet"]] +[[!meta author="Chris"]] +[[!meta date="2016-04-28T18:32:38Z"]] + + +[[!toc]] + +Git cheat sheet +=============== + +This document is here to help NetSurf developers who are more used to +non-distributed revision control systems, or to DVCSs which are not +`git`. It also contains a few helpful hints for people used to `git` so +it's worth a skim even to those who think they know it all already. + +`Git` is one of the least obvious, least intuitive distributed revision +control systems out there. However it is also very powerful and very +fast. `Git` appears to have won the DVCS race for the most part, and as +such, NetSurf uses it. + +Identify yourself +================= + +Every commit you make with `git` contains an identity. (Actually you can +differentiate between the identity of the author of a patch and the +person committing it to the repository if you want.) As such, you must +teach `git` who you are. + +`git config --global user.name "My Name"` +`git config --global user.email whoever@domain.name` + +Note that if you don't specify `--global` the name/email address will +only be local to the `git` tree you are inside when you run the command. + +The first time you make a commit, if you have not configured your +identity, `git` will give you a reminder. + +Useful bits and bobs +==================== + +It's well worth running: + +`git config --global push.default current` + +Since it tells git to only push the branch you're on. + +Repositories, Trees and Branches +================================ + +Each `git` repository is a project. As such, NetSurf has many +repositories. NetSurf's repositories reside on the NetSurf +[Gitano](http://www.gitano.org.uk/) instance. We will refer to this as +the *server* from now on. + +You acquire a copy of a repository by asking `git` to *clone* it. + +`git clone `[`git://git.netsurf-browser.org/buildsystem.git`](git://git.netsurf-browser.org/buildsystem.git) + +By default, `git` will create a directory named after the repository and +clone all the branches in that repository into it. + +When you have a local clone of a repository, we refer to that as a +*tree*. `Git` may also refer to it as a *working tree* and it is where +changes are made and commits are done. + +Each repository may have many branches. `Git` keeps them tucked away, +showing you only one at a time in your tree. You can list your local +branches with: + +`git branch` + +By default, a fresh clone will only contain one branch called `master` +which is the equivalent of Subversion's *trunk*. + +You can switch between local branches with: + +`git checkout branchname` + +Different bits of `git` documentation may also refer to *refs*. In `git` +branches, tags, etc are all represented by their commits. To give those +commits useful-to-a-human names, `git` has the concept of a *ref* which +is simply a name given to a commit. Refs in the namespace `refs/heads/` +are referred to as branches. + +Revisions and commits +===================== + +There are no traditional revision numbers in `git`. Instead each commit +is given a unique identifier. It is a long (40 character) hexadecimal +string but it is also commonly shortened to its first 7 characters. For +example, at the time of writing, the tip of the `master` branch in the +`NetSurf` repository was `00f76b5`. + +Remotes +======= + +Because your `git` tree is also a full local copy of the repository, +`git` keeps track of the server's copy of the repository in a data +structure called a *remote*. The default name for a remote is `origin` +and you will see that crop up in various places as we continue. + +You can update your local view of the server with the command: + +`git remote update` + +Or, assuming you're on `master` you may find *pull* to be of more use: + +`git pull` + +If you *pull* then `git` first updates its view of the remote, and then +attempts to merge in changes from the remote into your local branch. If +you've not made changes locally then this will be done by +*fast-forwarding* you to the server's revision. + +You can see the branches available on any remotes you have registered in +your tree with: + +`git branch -r` + +Making a branch to work on +========================== + +We recommend that everyone work on branches, merging to `master` only +when work is ready for others. In the past we've all worked on `trunk` +because it was such a pain in Subversion to merge work. However one of +`git`'s strengths is its merge functionality so this habit should end. + +Before making a new branch, it's customary to ensure that you've got +everything up-to-date from the server: + +`git remote update` + +Then you can create a new branch, from the server's idea of `master` +with: + +`git checkout -b username/branch origin/master` + +You should put your own username in for *username* (note it should be +the username which the server has for you. You can find that out by +running `ssh nsgit@netsurf-browser.org whoami`). + +For the branch name, give it something reasonably descriptive but not +too long. For example `fandango-experiment` is good, where +`experiment-with-new-layout-engine-idea` is probably too long. + +The `origin/master` is where you tell `git` that you want to track the +`master` branch of the `origin` remote. This not only gives you a +starting point for your branch, but also informs `git` where to get +changes from if you run `git pull` while you have that branch checked +out. + +To then inform the server of your new branch, run: + +`git push origin username/branch` + +When you wish to inform the server of new commits on your branch, you +can subsequently just run: + +`git push` + +Deleting a branch +================= + +To delete a branch from the server when it is no longer required: + +`git push origin :username/branch` + +Making changes and committing them +================================== + +You can make any amount of local changes before you commit, although we +recommend each commit be a reasonable self-contained "patch". Obviously +it is better to commit early and often; and `git` does contain a variety +of tools for helping you to turn a long line of small commits into a +neater set of commits ready for merging. We're not too bothered about +that with NetSurf for now; but if you want further reading on the +subject, go and search the web for *git rebase*. + +You can ask `git` about your working tree any time you like with: + +`git status` + +You can see changes in your working tree which you've not told `git` +about yet, with: + +`git diff` + +When you have edited the code and you are ready to commit, you should +run: + +`git add filename another/filename etc/etc/etc` + +You can run `git add` as many times as you like. Each time you do, +you're saying to `git` *I want you to remember this file just like it is +right now*. + +If you need to remove files then run: + +`git rm filename` + +You can see the diff which `git` has prepared for committing, with + +`git diff --cached` + +Once you're happy you've told git about any edited, new or deleted +files, you can run: + +`git commit` + +This will pop up an editor, telling you what will be committed and +encouraging you to write a change comment. The first line of the change +comment should be short (60 or so chars or less) and pithy. It will be +shown on the IRC channel as the commit message and also forms what `git` +refers to as the *short log message*. The rest of the message (ideally +separated from the first line by a blank) should explain what you did +and why. Normal good commit message etiquette applies here. + +You can see the log with: + +`git log` + +Don't forget to `git push` your commits to the server if you want anyone +else to see them. + +Merging branches +================ + +Since we're encouraging work on branches, we also need to know how to +merge those into the `master` branch. In order to keep things neat and +tidy, we ask that branches be merged in the following way: + +`# Switch to the master branch` +`git checkout master` +`# Ensure we're up-to-date relative to the server` +`git pull` +`# Merge the local branch in` +`git merge --no-commit --no-ff username/branch` +`# Review the changes here (git diff --cached)` +`# Commit the changes` +`git commit` + +Note that the commit will default to a message about the merge. That is +sufficient, although obviously any more useful message would be +appreciated. If the branch is not a local one, but one retrieved from +the server, then simply insert `origin/` in front of the branch name (so +it becomes `origin/username/branch`) to tell `git` the location of the +branch. + +Once the commit is done on `master` you can `git push` it to the server. + +The options to `git merge` are important. The `--no-commit` causes `git` +to leave the tree at the point that it has done the merge but hasn't +committed it to the branch. By default, `git` will commit merges which +had no conflicts. Since our code base is complex this is not always +sufficient, hence the review step above. The `--no-ff` causes `git` to +prepare a merge commit. Without it, if the `master` has not moved on +from where the branch was created, `git` will instead simply shunt the +commits onto the `master` branch. While not a bad thing in and of +itself, this would mean that when you did `git push` the `CIA.vc` bot +would announce every single commit from the branch. + +Merging changes from a 3rd party's repo +======================================= + +To merge from the "foo" branch of Somebody's github clone of the NetSurf +repo we can do this: + +`git remote add somebody `[`git://github.com/Somebody/netsurf`](git://github.com/Somebody/netsurf) +`git remote update somebody` +`git merge --no-ff --no-commit somebody/foo` +`git diff --cached` + +Check that the diff shows what we want to merge. If so, commit it. + +If you don't want to keep the remote around: + +`git remote rm somebody` + |