-
Notifications
You must be signed in to change notification settings - Fork 19
Develop:UsingGit
This should be updated to better reflect github's fork and pull-request workflow, but its a nice introduction to git in any case. -apoc
The initial checkout of the current rbot development code is done with
git clone git://github.com/ruby-rbot/rbot.git
which will create a new rbot directory containing the latest rbot source code.
git (as opposed to e.g. cvs or svn) also retrieves the entire project source code history, storing it (and all the other metadata) in the hidden rbot/.git directory. This means that, after the initial clone, you can check out any previous version of rbot with
git checkout <ref>
where is a commit id, a tag name or a branch name.
There are two possible ways to update your working tree to the latest upstream release. If you don't have any local changes, or if your local changes are exported, the best (and easiest) thing you can do is
git pull
which pulls any changes which have been made upstream into your local copy, merging them (and committing the merge) if necessary. If you have local changes in your tree and you don't export your tree, you can use the following two commands:
git fetch
git rebase origin
git fetch simply retrieves the remote changes, without applying them to the tree. git rebase origin rolls back your local changes, brings the local tree up to date with upstream, and then reapplies your changes on top: this effectively rewrites the history of your changes, but it provides a linear, cleaner overall history.
One of the upsides of using a distributed source control management (DSCM) software such as git is that it's possible to version control local changes without much troubles.
When changes are committed, the author name and email is recorded. Although git can try to retrieve this information by using your username and hostname, it's usually just easier to set them in the appropriate configuration files.
git has three configuration files: a system one (defaults to /etc/gitconfig), a global (user-specific) one (defaults to ~/.gitconfig) and a local (project-specific) one (defaults to rbot/.git/config).
If you want to set your identity, you can do it either by modifying the appropriate configuration file (usually the global one, unless you want to use a project-specific identity), or by using the git config command.
The configuration file can be modified by adding a section
[user]
name = Your Name
email = [email protected]
You can achieve the same effects by running the commands
git config --global user.name "Your Name"
git config --global user.email [email protected]
(don't use the --global option if you only want to set them for this particular project)
As a general rule, changes to rbot should be committed as small, self-contained and coherent changes with a descriptive commit message.
The same commit should not contain unrelated code changes and/or comment editing. Try not to have multiple bug fixes or new features implemented in a single commit. It's fine to have a bug fix or feature implementation span multiple commits, but try to make sure that no commit breaks the bot (i.e. it should be possible to run the bot by checking out any intermediate commit in a patch series).
The preferred commit message format is something along the lines:
topic: one-line commit description
Optional long, detailed, even multi-paragraph description of the feature or of the fix and the
associated problem
unless you prefer jsn-style commit messages, in which case you'll probably use something like
* (topic) description
where the * is a character that indicates a bugfix (*), a feature addition (+) or removal (-).
For simple changes, the easiest thing to do is to modify the files, check if the changes work as expected, and then commit them with
git commit -m "some commit message" -a
which commits a changeset including all the modified files. If you created some new files too, you have to add them with
git add path/to/file.new
before committing.
If you don't want to commit all the modified files, you must first do
git add filename1 filename2 ...
and then use
git commit -m "some commit message"
(notice the missing -a option) which will only commit the added files (so git add is used both to add new files and to select which modified files should be included in a commit).
If you want to correct a commit you just made, make the changes you want to make and then rerun the git commit command with the --amend option (after running git add, or using the -a option as appropriate).
You can omit the -m option when committing, in which case git will load your preferred (or set) editor, in which you can type the commit message (this is more convenient to use when the commit message includes the long, multi-paragraph description). Alternatively, you can use the -F filename option which will load the commit message from the given filename.
If you want to develop a more complex feature, you might want to switch your tree to a development branch. This can be made by either using the commands
git branch <branchname>
git checkout <branchname>
or the simpler
git checkout -b <branchname>
You can then make changes and commit as usual, and the commits will be stored on instead of the master branch.
Anybody can publish their git tree (or selected branches) to make their changes accessible easily accessible to anyone. However, the details on how to do this will not be discussed here. If have troubles setting up your git tree for public access, consider forking our Gitorious mirror or our github mirror.
If you want to propose your patches for inclusion in the official rbot distribution, you can open tickets with a description of the proposed enhancement/bug fix, and attach the git patches to the ticket.
A diff between two commits can be obtained by
git diff <oldcommit>..<newcommit>
where defaults to the current HEAD (last checked out or committed revision), and defaults to the current tree state. You can use specifications such as HEAD^ (commit before current HEAD) or HEAD~3 (three commits before current HEAD), or tag or branch names, or commit ids. For example, a diff between the upstream revision and your current tree is obtained with
git diff origin..
However, if you want to submit a patch or patch series to be applied to rbot, you can have git export all the commits you've created, each as a separate patch including your name, email address, commit time and commit message. To do this, use
git format-patch <oldcommit>..<newcommit>
which will create a number of files with a name such as 0001-some-commit-message.patch containing all the commit information. These patches can then be attached to the relevant ticket, allowing developers to commit them easily if approved.
Conversely, when applying a git patch to your working tree, you can use
git apply somefile ...
to apply the results of a git diff command, and
git am somefile ...
to apply the results of a git format-patch command
TODO: git cherry-pick, git rebase