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