summaryrefslogtreecommitdiff
path: root/documentation/gitcheatsheet.mdwn
diff options
context:
space:
mode:
authorDaniel Silverstone <dsilvers@digital-scurf.org>2017-02-04 09:41:13 +0000
committerDaniel Silverstone <dsilvers@digital-scurf.org>2017-02-04 09:41:13 +0000
commite7366bf41f68cfe07e9ea03fc4a398baecbae651 (patch)
tree5bb9c3cbe7eab7e70ff1ebd65d9de59a694762df /documentation/gitcheatsheet.mdwn
downloadnetsurf-wiki-e7366bf41f68cfe07e9ea03fc4a398baecbae651.tar.gz
netsurf-wiki-e7366bf41f68cfe07e9ea03fc4a398baecbae651.tar.bz2
Initial conversion from MediaWiki, 20170204
Diffstat (limited to 'documentation/gitcheatsheet.mdwn')
-rw-r--r--documentation/gitcheatsheet.mdwn278
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`
+