README.git

   1 Using Git for SimGrid
   2 =====================
   3
   4 SimGrid developement tree is now managed with Git.
   5 So, you need to use Git to:
   6
   7 - follow the last development of SimGrid;
   8 - propose some new commit to SimGrid developpers.
   9
  10
  11 Installing Git and finding documentation
  12 ----------------------------------------
  13 Refer to your OS documentation for installing Git.
  14
  15 On Debian/Unbuntu, you can install the following packages:
  16   apt-get install git-core git-gui gitk git-email
  17
  18 Git website is http://git.or.cz/ . A **lot** of documentation is available on
  19 this website. You can read for example the
  20 link:http://www.kernel.org/pub/software/scm/git/docs/gittutorial.html[Tutorial
  21 Introduction to Git] to begin with Git.
  22
  23
  24 Setting up GIT on your computer
  25 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  26 Be sure that git will use your right name and email for commits:
  27
  28   git config --global user.name "Firstname Lastname"
  29   git config --global user.email Firstname.Lastname@example.com
  30
  31 Note: the "--global" switch ensure that these setups will be used for all
  32 git projects. You can change these settings per project without this flags
  33 (see "git help config" for more information)
  34
  35
  36 Getting a working copy of SimGrid developement tree
  37 ------------------------------------------------
  38
  39 Read-only access:
  40   git clone git://scm.gforge.inria.fr/simgrid/simgrid.git
  41
  42 Read-write access (for people with account on the forge and in the SimGrid
  43 project):
  44   git clone git+ssh://USER@scm.gforge.inria.fr/gitroot/simgrid/simgrid.git
  45 (replace USER by your login name on the forge)
  46
  47 Note: due to the distributed nature of Git, it is probably better to checkout
  48 with a read-only access and later push in the official repo with another
  49 "remote" setup (see later).
  50
  51 Creating a commit
  52 ~~~~~~~~~~~~~~~~~
  53 A commit is a self-contained modification of the sources associated to
  54 meta-data such as author, date, message, etc.
  55
  56 Several rules must be repected as much as possible:
  57
  58 - all commits in public branches should lead to a state where "make"
  59   works (required in order git-bisect to be useful);
  60 - all commits in public branches must never be rebased (use "git revert" if you
  61   need to revert a public commit);
  62 - each commit should contain only one logical modification;
  63 - this modification must be described in the log message. The first line of the
  64   log is a summary, the second line should be empty, the next lines can
  65   describe more precisely the modifications.
  66
  67
  68 Your first line of commit message can begin with a [flag] telling which global
  69 part of SimGrid you are changing. It can be for example [doc], [network], [build
  70 system], [bugfix], etc.
  71
  72 [bugfix] commits will probably be considered to be also applied in the last
  73 stable branch.
  74
  75 If you need to modify your commits (changeset) before publishing them (better
  76 log message, splitting/merging of commits, ...), you can use:
  77
  78 - "git gui" to modify (ammend) the last commit (check the good box);
  79 - "gitk" to cherry pick interresting commits (right-clic on interesting
  80   commits) and (re)create a linear branch;
  81 - "git rebase -i" to merge/split/reorder commits in a linear branch;
  82 - "git commit --amend" in the simple case;
  83 - your email or your feet to go ask for help ;-)
  84
  85
  86 Writing in the official repo
  87 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  88 People with an account on the forge (and in the SimGrid group) are allowed
  89 to publish their changes in the main repo. However, they can only
  90 create/modify/remove heads under refs/heads/$forge_login/*
  91
  92 Global branches $global such as 'master', 'stable-*', ... are only writable
  93 if they are a subset of a refs/heads/$forge_login/official/$global .
  94 Restrictions to push to these global branches can be added if required.
  95
  96 To publish some commit, the easiest way is to create a "remote" config
  97 such as:
  98   git remote add inria-forge git+ssh://$forge_login@scm.gforge.inria.fr/gitroot/simgrid/simgrid.git
  99
 100 And then, you should add to the configuration (in the [remote "inria-forge"]
 101 section of .git/config) some lines such as (replace $forge_login by your
 102 login on the forge):
 103   push = refs/heads/master:refs/heads/$forge_login/wip/master
 104   push = refs/heads/public/*:refs/heads/$forge_login/*
 105   push = +refs/heads/wip/*:refs/heads/$forge_login/wip/*
 106 The idea here is to establish a correspondance between local heads and remote
 107 heads. As said before, remote heads **must** match refs/heads/$forge_login/*
 108 in order the push to succeed.
 109
 110 Note: you can also add the previous config directly into the [remote "origin"]
 111 section if your clone has been done with the ssh protocol.
 112
 113 You can create one-to-one correspondances (lines 1) or global correspondances
 114 (lines 2 and 3) as you wish. If you add a '+' in front of the line (line 3),
 115 then non fast-forward updates will be allowed. See 'man git-push' for more
 116 information.
 117
 118 You can them push your commits with:
 119   git push inria-forge
 120
 121
 122 To summary, with this setup:
 123 - local branch named master is pushed to '$forge_login/wip/master';
 124 - local branches named 'public/*' are pushed to '$forge_login/*';
 125 - local branches named 'wip/*' are pushed to '$forge_login/wip/*';
 126 - other local branches are not pushed.
 127
 128 Putting something in the 'master', 'stable-*', ... branches
 129 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 130 Just create a branch that merge the current 'master', 'stable-*', ... branch
 131 (called $global in this text) you want to update, push it first as
 132 $forge_login/official/$global and then push it as $global.
 133   With the previous example setup, if you want to update 'master' to include
 134 your current commit, you have to type something like:
 135   git merge inria-forge/master
 136   git push inria-forge HEAD:$forge_login/official/master
 137   git push inria-forge HEAD:master
 138 You can also add some config in .git/config such as
 139   push = refs/heads/user-master:refs/heads/$forge_login/official/master
 140   push = refs/heads/global-master:refs/heads/master
 141
 142   You can also ask one official maintainer of this branch to pull from your one
 143 (ie publish your branch and give its name to the official maintainers).
 144
 145 Note: take care to ask to push only well commented, well formed changeset.
 146 Use 'git-rebase' to cleanup your branch if needed. Do not hesitate to ask for
 147 help if you do not know how to do it.
 148
 149 Publishing branches
 150 ~~~~~~~~~~~~~~~~~~~
 151 There is mainly two reasons for which you might want to publish some of your
 152 commits:
 153
 154 - to merge your work into the main (master) developement branch. You must then
 155 ensure that the branch you want to publish is ready to be merged (well
 156 commented, well formed, bug free changeset) and then ask for a merge (see
 157 previous paragraph). If 'make' does not produce a working binary, you should
 158 reconsider seriously your request.
 159
 160 Even if your work is not merged immediately, you should never rebase this
 161 branch (i.e. only fast-forward commits should be done). SimGrid developers
 162 should use public/* heads to track these kind of works;
 163
 164 - to allow you/other people to test some experimental features. Rebase can
 165 occurs here, so other developers must never merge from theses branches unless
 166 they really know what they do. SimGrid developers should use wip/* heads to
 167 track these kind of works;
 168
 169 To summary: commits in public/* heads (and 'master', 'stable-*' heads) must
 170 never be rebased as they can be used by other people. Take care before
 171 pushing such heads!
 172
 173 Essential commands
 174 ------------------
 175
 176 You can probably do most of your work with the following commands:
 177
 178 - git clone: get a new repo
 179 - git gui: commit some changes (graphical program)
 180   You can very easily modify your last commit with this program
 181 - gitk: look at commits and manage branches (graphical program)
 182 - git rebase: rewrite/reorganize your (not yet public) commits
 183 - git fetch: get upstream changes
 184 - git merge: merge commits present on other branches
 185 - git pull: do a fetch and a merge
 186 - git push: publish your changes