Using Git for SimGrid ===================== SimGrid developement tree is now managed with Git. So, you need to use Git to: - follow the last development of SimGrid; - propose some new commit to SimGrid developpers. Installing Git and finding documentation ---------------------------------------- Refer to your OS documentation for installing Git. On Debian/Unbuntu, you can install the following packages: apt-get install git-core git-gui gitk git-email Git website is http://git.or.cz/ . A **lot** of documentation is available on this website. You can read for example the link:http://www.kernel.org/pub/software/scm/git/docs/gittutorial.html[Tutorial Introduction to Git] to begin with Git. Setting up GIT on your computer ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Be sure that git will use your right name and email for commits: git config --global user.name "Firstname Lastname" git config --global user.email Firstname.Lastname@example.com Note: the "--global" switch ensure that these setups will be used for all git projects. You can change these settings per project without this flags (see "git help config" for more information) Getting a working copy of SimGrid developement tree ------------------------------------------------ Read-only access: git clone git://scm.gforge.inria.fr/simgrid/simgrid.git Read-write access (for people with account on the forge and in the SimGrid project): git clone git+ssh://USER@scm.gforge.inria.fr/gitroot/simgrid/simgrid.git (replace USER by your login name on the forge) Note: due to the distributed nature of Git, it is probably better to checkout with a read-only access and later push in the official repo with another "remote" setup (see later). Creating a commit ~~~~~~~~~~~~~~~~~ A commit is a self-contained modification of the sources associated to meta-data such as author, date, message, etc. Several rules must be repected as much as possible: - all commits in public branches should lead to a state where "make" works (required in order git-bisect to be useful); - all commits in public branches must never be rebased (use "git revert" if you need to revert a public commit); - each commit should contain only one logical modification; - this modification must be described in the log message. The first line of the log is a summary, the second line should be empty, the next lines can describe more precisely the modifications. Your first line of commit message can begin with a [flag] telling which global part of SimGrid you are changing. It can be for example [doc], [network], [build system], [bugfix], etc. [bugfix] commits will probably be considered to be also applied in the last stable branch. If you need to modify your commits (changeset) before publishing them (better log message, splitting/merging of commits, ...), you can use: - "git gui" to modify (ammend) the last commit (check the good box); - "gitk" to cherry pick interresting commits (right-clic on interesting commits) and (re)create a linear branch; - "git rebase -i" to merge/split/reorder commits in a linear branch; - "git commit --amend" in the simple case; - your email or your feet to go ask for help ;-) Writing in the official repo ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ People with an account on the forge (and in the SimGrid group) are allowed to publish their changes in the main repo. However, they can only create/modify/remove heads under refs/heads/$forge_login/* Global branches $global such as 'master', 'stable-*', ... are only writable if they are a subset of a refs/heads/$forge_login/official/$global . Restrictions to push to these global branches can be added if required. To publish some commit, the easiest way is to create a "remote" config such as: git remote add inria-forge git+ssh://$forge_login@scm.gforge.inria.fr/gitroot/simgrid/simgrid.git And then, you should add to the configuration (in the [remote "inria-forge"] section of .git/config) some lines such as (replace $forge_login by your login on the forge): push = refs/heads/master:refs/heads/$forge_login/wip/master push = refs/heads/public/*:refs/heads/$forge_login/* push = +refs/heads/wip/*:refs/heads/$forge_login/wip/* The idea here is to establish a correspondance between local heads and remote heads. As said before, remote heads **must** match refs/heads/$forge_login/* in order the push to succeed. Note: you can also add the previous config directly into the [remote "origin"] section if your clone has been done with the ssh protocol. You can create one-to-one correspondances (lines 1) or global correspondances (lines 2 and 3) as you wish. If you add a '+' in front of the line (line 3), then non fast-forward updates will be allowed. See 'man git-push' for more information. You can them push your commits with: git push inria-forge To summary, with this setup: - local branch named master is pushed to '$forge_login/wip/master'; - local branches named 'public/*' are pushed to '$forge_login/*'; - local branches named 'wip/*' are pushed to '$forge_login/wip/*'; - other local branches are not pushed. Putting something in the 'master', 'stable-*', ... branches ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Just create a branch that merge the current 'master', 'stable-*', ... branch (called $global in this text) you want to update, push it first as $forge_login/official/$global and then push it as $global. With the previous example setup, if you want to update 'master' to include your current commit, you have to type something like: git merge inria-forge/master git push inria-forge HEAD:$forge_login/official/master git push inria-forge HEAD:master You can also add some config in .git/config such as push = refs/heads/user-master:refs/heads/$forge_login/official/master push = refs/heads/global-master:refs/heads/master You can also ask one official maintainer of this branch to pull from your one (ie publish your branch and give its name to the official maintainers). Note: take care to ask to push only well commented, well formed changeset. Use 'git-rebase' to cleanup your branch if needed. Do not hesitate to ask for help if you do not know how to do it. Publishing branches ~~~~~~~~~~~~~~~~~~~ There is mainly two reasons for which you might want to publish some of your commits: - to merge your work into the main (master) developement branch. You must then ensure that the branch you want to publish is ready to be merged (well commented, well formed, bug free changeset) and then ask for a merge (see previous paragraph). If 'make' does not produce a working binary, you should reconsider seriously your request. Even if your work is not merged immediately, you should never rebase this branch (i.e. only fast-forward commits should be done). SimGrid developers should use public/* heads to track these kind of works; - to allow you/other people to test some experimental features. Rebase can occurs here, so other developers must never merge from theses branches unless they really know what they do. SimGrid developers should use wip/* heads to track these kind of works; To summary: commits in public/* heads (and 'master', 'stable-*' heads) must never be rebased as they can be used by other people. Take care before pushing such heads! Essential commands ------------------ You can probably do most of your work with the following commands: - git clone: get a new repo - git gui: commit some changes (graphical program) You can very easily modify your last commit with this program - gitk: look at commits and manage branches (graphical program) - git rebase: rewrite/reorganize your (not yet public) commits - git fetch: get upstream changes - git merge: merge commits present on other branches - git pull: do a fetch and a merge - git push: publish your changes