4 SimGrid developement tree is now managed with Git.
5 So, you need to use Git to:
7 - follow the last development of SimGrid;
8 - propose some new commit to SimGrid developpers.
11 Installing Git and finding documentation
12 ----------------------------------------
13 Refer to your OS documentation for installing Git.
15 On Debian/Unbuntu, you can install the following packages:
16 apt-get install git-core git-gui gitk git-email
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.
24 Setting up GIT on your computer
25 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
26 Be sure that git will use your right name and email for commits:
28 git config --global user.name "Firstname Lastname"
29 git config --global user.email Firstname.Lastname@example.com
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)
36 Getting a working copy of SimGrid developement tree
37 ------------------------------------------------
40 git clone git://scm.gforge.inria.fr/simgrid/simgrid.git
42 Read-write access (for people with account on the forge and in the SimGrid
44 git clone git+ssh://USER@scm.gforge.inria.fr/gitroot/simgrid/simgrid.git
45 (replace USER by your login name on the forge)
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).
53 A commit is a self-contained modification of the sources associated to
54 meta-data such as author, date, message, etc.
56 Several rules must be repected as much as possible:
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.
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.
72 [bugfix] commits will probably be considered to be also applied in the last
75 If you need to modify your commits (changeset) before publishing them (better
76 log message, splitting/merging of commits, ...), you can use:
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 ;-)
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/*
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.
96 To publish some commit, the easiest way is to create a "remote" config
98 git remote add inria-forge git+ssh://$forge_login@scm.gforge.inria.fr/gitroot/simgrid/simgrid.git
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
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.
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.
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
118 You can them push your commits with:
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.
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
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).
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.
151 There is mainly two reasons for which you might want to publish some of your
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.
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;
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;
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
176 You can probably do most of your work with the following commands:
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