*You can directly get Web access to git repositories: http://git.eclipse.org/

+

+

After installation of EGit in Eclipse, you can look up "Git for Eclipse Users" in the EGit Documentation.

+

+

== Installations on your computer ==

+

+

* command line tool (not necessary but convenient)

+

**download git: http://git-scm.com/download

+

***e.g. for Windows: Git-1.7.3.1-preview20101002.exe

+

*EGit is already contained in the Kepler modeling package

+

**Line Endings for EGit in Eclipse: Be aware that the global settings of the command line version of git might be different from the global EGit settings: (Perspective Git Repository Exploring -&gt; &lt;Context Menu on Repo Location&gt; Open Properties View -&gt; Global Configuration -&gt; Edit ):

***create a new entry '''remote.bypass.push''' with value '''HEAD:refs/heads/master'''

+

**note&nbsp;:- for juno entry remote.review.push should have value HEAD:refs/for/juno (Only if you are working on juno branch)

+

**set the property gerrit.createchangeid to true either in your repository or globally (details can be found [[EGit/User Guide#Commit_Message|here]])

+

***Note: the Change-Id will be 0 and only be set to the real value on submit

+

+

Now you can commit your changes as usual to your local Git repository.

+

+

When everything is ready to push you can use EGit to push to the reviewing system (use the review remote). Gerrit will create a new change which can be reviewed and verified by a committer. Gerrit allows the committer to leave comments in the source code diff which will help to improve the code.

+

+

When everything is alright the committer may submit the changes to the eTrice Git repository.

+

+

=== Use branches when working with Gerrit ===

+

+

*switch to a newly created (local) branch in your Git repository with an appropriate name, say 'mywork. (It is recommended to turn off any auto merge/rebase function on pull)

+

*as long as you work on your local branch you are shielded against changes on the remote master branch.<br>

+

*when you are ready to push you push your branch to Gerrit with ref HEAD:refs/for/master/mywork (this will create a so called topic branch in Gerrit)

+

+

=== Proper handling of Gerrit's Change Id ===

+

+

*Create a new change

+

**If this is the first time it has seen the Change-Id mentioned in the commit message, Gerrit will create a new change for review.

+

*Update an existing change

+

**If Gerrit has seen this Change-Id before, but has not yet seen this new commit object, Gerrit will add the new commit as a new patch set on the existing change.

+

+

=== Squashing Changes ===

+

+

Here is an article how Git can merge several commits into one using (interactive) rebase: (cannot be done in EGit (version 2.1) yet)<br>

#Amend commit to save changes from the m-1 commits and to edit the commit message

+

+

Note: The m commits have to be (a) continous, (b) lastest in repository and if you want to push to Gerrit (c) local

+

+

=== Integrating a contribution ===

+

+

The patch has to be IP clean and it should be checked if a CQ is necessary!

+

+

If Gerrit isn't able to merge the patch (e.g. if prerequisites lead to conflicts) a committer can merge the patch locally to his master branch (make sure to have branch.master.rebase=true) and check that in. The history will show all the commits of the contributor. Since also the bypass uses Gerrit's interface Gerrit will mark the corresponding patches as merged.

**as IDs use the parent ID as first and the parent ID as second ID of the range

+

+

=== Gerrit workflow ===

+

+

The typical workflow is illustrated in the flow chart on the right side. Further details:<br>

+

+

[[Image:Etrice gerrit workflow.png|thumb|Gerrit workflow]]

+

+

*Use branches when working with Gerrit ([http://wiki.eclipse.org/ETrice/Development/Repository#Use_branches_when_working_with_Gerrit see how])<br> Consider to create a new branch for each independent piece of work.<br>

+

*Reduce the number of reviews <br> Remember, that each commit with a new change-id spawns a new review/change. Before pushing to Gerrit, you should squash your local commits into 1 commit ([http://wiki.eclipse.org/ETrice/Development/Repository#Squashing_Changes see how]). The first time it gets a new change-id, otherwise amend this commit. If you want to push a new change, consider that it will be difficult to alter previous changes (see below).<br>

+

*Push on HEAD only <br> If you push a commit on a previous change, you have to rebase all succeeding changes. This often goes with a great deal of work. Therefore it is recommended to continue the lastest change only.<br>

+

*Rebase on final submit <br> In case Gerrit's auto merges fails, you have to rebase your change(s) on master.&nbsp;

+

**If there is only 1 commit to submit, rebase it and just amend this modifications.

+

**else you have to walk through your commit history and resolve the conflicts using interactive rebase (but do not alter the history of your commits). In EGit see [http://wiki.eclipse.org/EGit/User_Guide#Starting_Rebase EGit/User_Guide#Starting_Rebase] and [http://wiki.eclipse.org/EGit/User_Guide#Rebase_Conflicts EGit/User_Guide#Rebase_Conflicts] (choose only: Action to perform -&gt; "Start Merge Tool to resolve conflicts", then resolve conflicts and continue with next commit)<br>

+

+

=== Create a new patch for a change on Gerrit ===

+

+

Assume some contributor provided a patch using Gerrit. You checked out this into your local clone (Fetch from Gerrit > Create and checkout a local branch). Then you modified the code. Now you want to provide your changes as new patch for the existing change.

+

* commit your work and check 'amend'

+

* if the commit message doesn't contain a ChangeId then copy it from Gerrit and paste it into the message

*in the context menu of the Package Explorer go to Team &gt; Apply patch...

+

*in the wizard select File and locate the patch file

+

*select 'Apply the patch to the workspace root'

+

*set leading path segments to 2

+

*check the result and Finish

+

+

== Checkout a previous revision ==

+

+

Inspect the log and determine the commit id you want to change to. Then <code>git checkout</code> this:

$ git checkout 2eb90f4643fd425f77de2b88753a86416cda0166

$ git checkout 2eb90f4643fd425f77de2b88753a86416cda0166

−

Note: checking out '2eb90f4643fd425f77de2b88753a86416cda0166'.

+

Note: checking out '2eb90f4643fd425f77de2b88753a86416cda0166'.

−

<br>

+

−

You are in 'detached HEAD' state. You can look around, make experimental

+

−

changes and commit them, and you can discard any commits you make in this

+

You are in 'detached HEAD' state. You can look around, make experimental

−

state without impacting any branches by performing another checkout.

+

changes and commit them, and you can discard any commits you make in this

−

<br>

+

state without impacting any branches by performing another checkout.

−

If you want to create a new branch to retain commits you create, you may

+

−

do so (now or later) by using -b with the checkout command again. Example:

+

−

<br>

+

If you want to create a new branch to retain commits you create, you may

−

git checkout -b new_branch_name

+

do so (now or later) by using -b with the checkout command again. Example:

−

<br>

+

−

HEAD is now at 2eb90f4... ui.structure: during creation take position as midpoint of new interface item. Adjusted PopulateDiagramCommand accordingly.

+

+

git checkout -b new_branch_name

+

+

+

HEAD is now at 2eb90f4... ui.structure: during creation take position as midpoint of new interface item. Adjusted PopulateDiagramCommand accordingly.

−

== working with branches ==

+

== working with branches ==

−

=== creating a local branch ===

+

−

=== pushing a local branch ===

+

−

=== creating a remote tracking branch ===

+

−

=== pulling for remote tracking branches ===

+

−

If you often merge with the same branch, you may want to

+

=== creating a local branch ===

−

use something like the following in your configuration file:

+

+

=== pushing a local branch ===

+

+

=== creating a remote tracking branch ===

+

+

=== pulling for remote tracking branches ===

+

+

If you often merge with the same branch, you may want to use something like the following in your configuration file:

[branch "before_indigo"]

[branch "before_indigo"]

−

remote = <nickname>

+

remote = &lt;nickname&gt;

−

merge = <remote-ref>

+

merge = &lt;remote-ref&gt;

−

[remote "<nickname>"]

+

[remote "&lt;nickname&gt;"]

−

url = <url>

+

url = &lt;url&gt;

−

fetch = <refspec>

+

fetch = &lt;refspec&gt;

−

With EGit the configuration can be accesses from the Git Repositories View context menu > Open Properties View

+

With EGit the configuration can be accesses from the Git Repositories View context menu &gt; Open Properties View The Properties View displays the current configuration and offers an Edit button in the upper left corner.

−

The Properties View displays the current configuration and offers an Edit button in the upper left corner.

+

−

Here is an example of a pull configuration for a remote tracking branch:<br>

+

Here is an example of a pull configuration for a remote tracking branch:<br> [[Image:GitConfig.jpg]]

−

[[Image:GitConfig.jpg]]

+

−

== Using the eTrice github clone ==

+

== Using the eTrice github clone ==

−

According to https://bugs.eclipse.org/bugs/show_bug.cgi?id=332970 Eclipse projects with git repositories (and correct metadata set) are mirrored to github.

+

According to https://bugs.eclipse.org/bugs/show_bug.cgi?id=332970 Eclipse projects with git repositories (and correct metadata set) are mirrored to github.

−

And so is eTrice: https://github.com/eclipse/etrice

+

And so is eTrice: https://github.com/eclipse/etrice

−

Here are some slides explaining how github is accessed using EGit: http://www.slideshare.net/loianeg/using-the-egit-eclipse-plugin-with-git-hub-2578587

+

Here are some slides explaining how github is accessed using EGit: http://www.slideshare.net/loianeg/using-the-egit-eclipse-plugin-with-git-hub-2578587

−

Any github user can fork an existing github repository. This facilitates collaborating with contributors which have no commit rights.

+

Any github user can fork an existing github repository. This facilitates collaborating with contributors which have no commit rights.

−

See also the [http://wiki.eclipse.org/Development_Resources/Handling_Git_Contributions Wiki page on Git contributions].

+

See also the [http://wiki.eclipse.org/Development_Resources/Handling_Git_Contributions Wiki page on Git contributions].

−

TODO: typical workflow...

+

TODO: typical workflow...

−

[[Category:ETrice]]

+

== Some hints to create Documentation ==

−

[[Category:modeling]]

+

−

== Some hints to create Documentation ==

+

=== Location of Documentation ===

−

=== Location of Documentation ===

+

−

- ETrice Documentation will be put to org.eclipse.etrice.doc

+

−

- numbering of chapters is 000-xxx, 005-yyy, 010-zzz, 015... to have room for inject some chapters

+

- ETrice Documentation will be put to org.eclipse.etrice.doc

−

- images (put to the folder images) should have the same numbering according to the chapters

+

- numbering of chapters is 000-xxx, 005-yyy, 010-zzz, 015... to have room for inject some chapters

−

- within the etrice-index.txt document the ordering of the chapters will be done. This file will be used from the build prozess to collect all single .textile files to produce the complete Doku.

+

- images (put to the folder images) should have the same numbering according to the chapters

−

- build prozess will be started from the external tool menu => "build-etrice-doc". (you must have internet access during production of the docu)

+

- within the etrice-index.txt document the ordering of the chapters will be done. This file will be used from the build prozess to collect all single .textile files to produce the complete Doku.

+

- build prozess will be started from the external tool menu =&gt; "build-etrice-doc". (you must have internet access during production of the docu)

−

=== Within the .textile file ===

+

<br>

−

- with F1 you can get a list of the formating strings

+

−

- some formating options does not work well for all document types e.g. __italic__ does not work

+

=== Within the .textile file ===

−

in the pdf file if the string contains "_". => therefore, for names which reference a concrete model name (shown in a picture or code block) use: "??This_is_my_name??" == citation

+

+

- with F1 you can get a list of the formating strings

+

+

- some formating options does not work well for all document types e.g. __italic__ does not work in the pdf file if the string contains "_". =&gt; therefore, for names which reference a concrete model name (shown in a picture or code block) use: "??This_is_my_name??" == citation

+

+

=== Images ===

−

=== Images ===

- use IrfanView to create screen shots (everything on board what you need)

- use IrfanView to create screen shots (everything on board what you need)

−

- use the png format to save pictures (i had never problems with that)

+

- use the png format to save pictures (i had never problems with that)

+

+

- pictures should not be larger than 640*480 pixels. Otherwise they will cause problems in the PDF file. IrfanView: Ctrl+r =&gt; resize image

+

+

- to sharpen the images, use IrfanView: Image=&gt;sharpen to create perfect screen shots.

+

+

<br>

+

+

= Steps to change to Indigo =

+

+

*download and install eclipse Modeling for Win32

−

- pictures should not be larger than 640*480 pixels. Otherwise they will cause problems in the PDF file. IrfanView: Ctrl+r => resize image

Installations on your computer

Line Endings for EGit in Eclipse: Be aware that the global settings of the command line version of git might be different from the global EGit settings: (Perspective Git Repository Exploring -> <Context Menu on Repo Location> Open Properties View -> Global Configuration -> Edit ):

create a new entry remote.bypass.push with value HEAD:refs/heads/master

note :- for juno entry remote.review.push should have value HEAD:refs/for/juno (Only if you are working on juno branch)

set the property gerrit.createchangeid to true either in your repository or globally (details can be found here)

Note: the Change-Id will be 0 and only be set to the real value on submit

Now you can commit your changes as usual to your local Git repository.

When everything is ready to push you can use EGit to push to the reviewing system (use the review remote). Gerrit will create a new change which can be reviewed and verified by a committer. Gerrit allows the committer to leave comments in the source code diff which will help to improve the code.

When everything is alright the committer may submit the changes to the eTrice Git repository.

Use branches when working with Gerrit

switch to a newly created (local) branch in your Git repository with an appropriate name, say 'mywork. (It is recommended to turn off any auto merge/rebase function on pull)

as long as you work on your local branch you are shielded against changes on the remote master branch.

when you are ready to push you push your branch to Gerrit with ref HEAD:refs/for/master/mywork (this will create a so called topic branch in Gerrit)

Proper handling of Gerrit's Change Id

Create a new change

If this is the first time it has seen the Change-Id mentioned in the commit message, Gerrit will create a new change for review.

Update an existing change

If Gerrit has seen this Change-Id before, but has not yet seen this new commit object, Gerrit will add the new commit as a new patch set on the existing change.

Squashing Changes

Here is an article how Git can merge several commits into one using (interactive) rebase: (cannot be done in EGit (version 2.1) yet)

If you want to squash your lastest local commits with EGit (e.g. before pushing to Gerrit), you can use following method:

In Git Repository Exploring: Right click on repository -> Show In -> History

In History view: To squash your lastest m commits into m (which is first in chronological order), right click on m -> Reset -> Soft (HEAD Only)

Amend commit to save changes from the m-1 commits and to edit the commit message

Note: The m commits have to be (a) continous, (b) lastest in repository and if you want to push to Gerrit (c) local

Integrating a contribution

The patch has to be IP clean and it should be checked if a CQ is necessary!

If Gerrit isn't able to merge the patch (e.g. if prerequisites lead to conflicts) a committer can merge the patch locally to his master branch (make sure to have branch.master.rebase=true) and check that in. The history will show all the commits of the contributor. Since also the bypass uses Gerrit's interface Gerrit will mark the corresponding patches as merged.

Create a patch

For the CQ diff files of the patches have to be created and attached.

This can be done as follows:

git log --author=.*contributor_name.* --parents --oneline

creates a compact list of the contributor's commits with two IDs (commit+parent) for regular commits or three IDs (commit+2 parents) for merges

git format-patch --stdout 28fda9c..537d59a > patch_1.txt

as IDs use the parent ID as first and the parent ID as second ID of the range

Gerrit workflow

The typical workflow is illustrated in the flow chart on the right side. Further details:

Gerrit workflow

Use branches when working with Gerrit (see how) Consider to create a new branch for each independent piece of work.

Reduce the number of reviews Remember, that each commit with a new change-id spawns a new review/change. Before pushing to Gerrit, you should squash your local commits into 1 commit (see how). The first time it gets a new change-id, otherwise amend this commit. If you want to push a new change, consider that it will be difficult to alter previous changes (see below).

Push on HEAD only If you push a commit on a previous change, you have to rebase all succeeding changes. This often goes with a great deal of work. Therefore it is recommended to continue the lastest change only.

Rebase on final submit In case Gerrit's auto merges fails, you have to rebase your change(s) on master.

If there is only 1 commit to submit, rebase it and just amend this modifications.

else you have to walk through your commit history and resolve the conflicts using interactive rebase (but do not alter the history of your commits). In EGit see EGit/User_Guide#Starting_Rebase and EGit/User_Guide#Rebase_Conflicts (choose only: Action to perform -> "Start Merge Tool to resolve conflicts", then resolve conflicts and continue with next commit)

Create a new patch for a change on Gerrit

Assume some contributor provided a patch using Gerrit. You checked out this into your local clone (Fetch from Gerrit > Create and checkout a local branch). Then you modified the code. Now you want to provide your changes as new patch for the existing change.

commit your work and check 'amend'

if the commit message doesn't contain a ChangeId then copy it from Gerrit and paste it into the message

Apply a Patch

in the context menu of the Package Explorer go to Team > Apply patch...

in the wizard select File and locate the patch file

select 'Apply the patch to the workspace root'

set leading path segments to 2

check the result and Finish

Checkout a previous revision

Inspect the log and determine the commit id you want to change to. Then git checkout this:

$ git checkout 2eb90f4643fd425f77de2b88753a86416cda0166
Note: checking out '2eb90f4643fd425f77de2b88753a86416cda0166'.
You are in 'detached HEAD' state. You can look around, make experimental
changes and commit them, and you can discard any commits you make in this
state without impacting any branches by performing another checkout.
If you want to create a new branch to retain commits you create, you may
do so (now or later) by using -b with the checkout command again. Example:
git checkout -b new_branch_name
HEAD is now at 2eb90f4... ui.structure: during creation take position as midpoint of new interface item. Adjusted PopulateDiagramCommand accordingly.

working with branches

creating a local branch

pushing a local branch

creating a remote tracking branch

pulling for remote tracking branches

If you often merge with the same branch, you may want to use something like the following in your configuration file:

[branch "before_indigo"]
remote = <nickname>
merge = <remote-ref>

[remote "<nickname>"]
url = <url>
fetch = <refspec>

With EGit the configuration can be accesses from the Git Repositories View context menu > Open Properties View The Properties View displays the current configuration and offers an Edit button in the upper left corner.

Here is an example of a pull configuration for a remote tracking branch:

Some hints to create Documentation

Location of Documentation

- numbering of chapters is 000-xxx, 005-yyy, 010-zzz, 015... to have room for inject some chapters

- images (put to the folder images) should have the same numbering according to the chapters

- within the etrice-index.txt document the ordering of the chapters will be done. This file will be used from the build prozess to collect all single .textile files to produce the complete Doku.

- build prozess will be started from the external tool menu => "build-etrice-doc". (you must have internet access during production of the docu)

Within the .textile file

- with F1 you can get a list of the formating strings

- some formating options does not work well for all document types e.g. __italic__ does not work in the pdf file if the string contains "_". => therefore, for names which reference a concrete model name (shown in a picture or code block) use: "??This_is_my_name??" == citation

Images

- use IrfanView to create screen shots (everything on board what you need)

- use the png format to save pictures (i had never problems with that)

- pictures should not be larger than 640*480 pixels. Otherwise they will cause problems in the PDF file. IrfanView: Ctrl+r => resize image

- to sharpen the images, use IrfanView: Image=>sharpen to create perfect screen shots.