This page is (partially) outdated
Currently the project is in the process to migrate to GitHub. Some of the contents still refers to the migration of CVS to git and Gerrit, which was finished a long time ago. The relevant content of this page should be merged into Platform/How to Contribute.

We'd like to capture some common CVS workflows used by the Eclipse Project and spell out the git/EGit equivalent. Please read this page even if you don't use EGit. It contains important instructions on how to setup your repository.

Please read some of Pro Git to get a feel for how git repositories work. Refer to the EGit/User Guide for more detailed instructions and pictures.

1 Getting EGit
2 Configure the workspace
3 Configure the project properties
4 Clone a repo
5 Start working in HEAD
6 Start working in a new branch
7 Create a patch
8 Apply a patch
9 Gerrit workflow for a committer
10 Contributing to a build
- 10.1 Changing what branch is built
- 10.2 Creating an integration branch
11 Manual tagging
12 Branches in our Platform Repos
13 Commit changes to the main repo
14 Update to pull in the latest changes to HEAD
15 Making the same change in two branches
16 Merge conflicting changes
17 Dealing with line terminators
18 Pruning corrupt repository branches
19 References

Getting EGit

You can install EGit 2.0.0 or later from [1].

If you would like to keep up with their current bug fixes, install EGit/JGit from their nightly build site http://download.eclipse.org/egit/updates-nightly.

Configure the workspace

Open the Team > Git > Configuration preference page and select the User Settings tab.

Add entries for user.name and user.email. If you don't want to share your e-mail you can also use your committer account ID. Note that you will not be able to push changes to the repository if the latter property is not matching with your records at the Eclipse Foundation.
Add entry core.autocrlf = false
Add entry branch.autosetuprebase = always
Optionally add entry rebase.autoStash = true (this allows you to rebase even if you have dirty files)
On a platform that creates garbage files like macOS' .DS_Store, you should globally exclude those files:
```
mkdir -p ~/.config/git; echo .DS_Store >> ~/.config/git/ignore
```
- Workaround for EGit bug 436127: Add entry core.excludesfile = ~/.config/git/ignore

On the General > Workspace preference page, set New text file line delimiter to Unix.

Configure the project properties

It is recommended to set New text file line delimiter to Unix in all your projects, so that they don't depend on the workspace setting. Set Text file encoding to UTF-8.

Clone a repo

The first step is to clone the one or more repos you need to work on. The repos should not be stored directly in your workspace. Either clone them to <workspace>/git/ or to a location outside your workspace. Then use the EGit Import Projects option to import the projects.

Refer to the EGit/User Guide for more detailed instructions and pictures.

Switch to the Git Repository Exploring Perspective
Use Clone a Git repository
you can paste in your connection URL and it should do the right thing. Some URLs (not all of them contain content right now in the testing phase). The repos that have been migrated are in bold text (Some projects use gerrit code review system so their URL's may look different):
Next
Select all branches to clone
Next
Confirm the location that it will clone the repository into.
an initial branch of master and a remote name of origin are standard.
Finish - Now just sit back while git copies the entire repo to your harddrive :-)

Configuring the repo

Make sure that you set core.autocrlf = false and on Windows core.filemode = false. The former should already be configured in the workspace, but it doesn't hurt to be explicit.

Unless you are working on topic branches, we work in a fairly linear history. Please make sure branch.branchname.rebase = true is set. If you've set branch.autosetuprebase = always as explained in #Configure_the_workspace, then this is done automatically.

Otherwise, once you've cloned a repository, you can go to the Preferences > Team > Git > Configuration page. Select your repository, select the branch you picked when you cloned the repository, and click New Entry.... Append "rebase" to the text in the 'Key' field and enter "true" as value.

Importing the projects

We need to get the projects from the repo into our workspace:

right click on your newly cloned repo and select Import Projects
you want Import existing projects from the Working Directory
Next
Select the projects that you want to import from the repository
Finish

Now you can start working.

A note on deleting projects

Typically you will only want to have a subset of the projects from a given repository in your workspace. When you are no longer interested in a project, you can delete it from your workspace. However, NEVER select 'Delete project contents on disk' for a project in a git repository. If you do, Git will consider this an outgoing deletion to be committed to the remote branch. Later while working on a completely unrelated project you may accidentally commit this deletion (and you wouldn't be the first to do so).

Start working in HEAD

To start working in HEAD you must clone your repository and checkout a working copy. By default, cloning the repo checks out the master branch, which is the same as HEAD in CVS.

See #Clone_a_repo.

Refer to the EGit/User Guide for more detailed instructions and pictures.

The constant HEAD is used in GIT as well, but has a completely different meaning. In GIT HEAD means the pointer to the latest commit in your currently checked-out branch (more or less).

Start working in a new branch

For example, create the R3_7_maintenance branch for your repo. This example is for the case that your branch doesn't already exist as refs/remotes/origin/R3_7_maintenance.

Refer to the EGit/User Guide for more detailed instructions and pictures.

right click on one of your projects and choose Team>Switch To>New Branch
you need to pick a source ref.
1. HEAD == current checked out commit
2. refs/heads/master means your master branch.
3. refs/remotes/origin/R3_7_maintenance - the existing remote branch. If you pick this one and name your local branch the same, EGit will automatically create a tracked branch.
4. refs/tags/R3_7 is the tags to branch from
name the branch R3_7_maintenance
select the Rebase merge option
leave "Check out the new branch" selected.

This will create a new branch for you to work on. Once you've made your initial commits, you need #Commit_changes_to_the_main_repo. Pushing up to the repo will push any new branches you've created as well.

Create a patch

We have 2 options for accepting contributions from the community. See Development Resources/Handling Git Contributions (prefered) and Git#IP_process_implications_of_DVCS. Refer to the EGit/User Guide for more detailed instructions and pictures.

To create a patch:

You need to show the commits in the history view.
1. Either right-click on a file you just committed and Show in history
2. or right-click on the project and Show In>History, then find the commit you want
right click on the commit in the History view, and select Create Patch
use Next if you'd like the patch in the standard git mbox format

Apply a patch

A normal workspace patch will apply in the same fashion it does for CVS. Simply copy the file to the clipboard and paste it into the Package Explorer or use Team>Apply Patch.

Refer to the EGit/User Guide for more detailed instructions and pictures.

Patches created with git/EGit have a different pattern. They are diff statements that look like:

 diff --git a/bundles/org.eclipse.some/src/org/eclipse/some/File.java b/bundles/org.eclipse.some/src/org/eclipse/some/File.java
index 99d339f..37bcf68 100644
--- a/bundles/org.eclipse.some/src/org/eclipse/some/File.java
+++ b/bundles/org.eclipse.some/src/org/eclipse/some/File.java

To apply a patch like this, you should:

copy and paste the patch into the Package Explorer
Select Apply patch to the workspace root
Next
under Patch Options set Ignore leading path name segments to 2
now you can examine the patch and apply is normally.

Gerrit workflow for a committer

Some suggested workflows for a committer working with Gerrit. There's more information at Gerrit#Gerrit_Code_Review_Cheatsheet.

Setting up your repo

Committers usually have existing repos, and they can be modified to work with Gerrit.

1) Visit Gerrit settings and check the following pages

Profile - will list your username to use in push urls
Watched Projects - can email you about new and commented changes
SSH Public Keys - you need to upload a public key for your machine, Gerrit doesn't access the regular dev ssh keys
HTTP Password - set up a password to access the repository without using SSH

2) Clone the repository and set up the origin remote if not done already, committers can still push to origin, bypassing Gerrit

ssh://git.eclipse.org/gitroot/platform/eclipse.platform.ui.git

3) Add another remote to your git repo called review mapping to the Gerrit ssh or https url (similar to repo url, but with port 29418 and no .git at the end)

https://username@git.eclipse.org/r/platform/eclipse.platform.ui

ssh://username@git.eclipse.org:29418/platform/eclipse.platform.ui

4) Add remote.review.url and remote.review.push properties to configure Gerrit via command line or from EGit - Preferences>Team>Git>Configuration in the Repository Settings tab (pick the correct repo from the combo box).

git config remote.review.url ssh://username@git.eclipse.org:29418/platform/eclipse.platform.ui

git config remote.review.push HEAD:refs/for/master

5) If you use EGit, when creating a commit for Gerrit you will need to add a Change-Id (a button in the Git Staging view). If you are using the command line, you'll need to install the commit-msg hook (Gerrit#Install_the_commit-msg_hook_in_your_repository). The commit-msg hook will add the Change-Id to all of your commits, which will have no effect if you don't push your commit to Gerrit. In eGit, an empty change id will show up in the commit message text box. This will be computed and filled in when pushing

Resetting your current branch

If you have a private local branch and you push a commit up to Gerrit for review, you don't have to do anything else but switch back to master to move to the next task. If you created the commit for Gerrit while in master, you'll have to reset master in order to continue your work (you don't want your Gerrit commit poluting master). Once you've confirmed you have no extra changes lying around, you can get back to master using:

git reset --hard origin/master
git pull

Pushing a commit to Gerrit for review

A commit for review is the same as a regular commit except it has a Change-Id in the footer, and is pushed to a special refspec - HEAD:refs/for/master

Once you have a commit ready, in EGit add the Change-Id placeholder to the bottom of the commit message using the Change-Id button. From the command line make sure the Change-Id commit message hook is set up. Then commit. A unique Change-Id footer is created. If you've already committed you can just amend the commit to add the Change-Id.

Then you push the commit to Gerrit. In EGit right click on your repo in the Git Repositories view and select Push to Gerrit.... Select your review remote URI and fill in the Gerrit branch next to the refs/for combo: master, R4_2_maintenance, etc.

If you are pushing a new commit for review, the popup status dialog will display the URL to the new change that was created.

From the command line, you can use:

git push review

Updating a change during the review cycle.

You can update the patch set (commit) for a change for a number of reasons. Reviewed and you want to make the changes suggested, rebase on top of your branch tip to keep the change fresh, etc. Any commit that contains an existing Change-Id and is pushed to refs/for/<branch> will replace the existing patch set on that change.

Updating a Gerrit change that was pushed with no Change-Id

If you accidentally push to refs/for/master with no Change-Id, Gerrit will create a change for you and it will have a Change-Id. The commit message will not contain it, however.

If you need to push up a second patch set, just include the Change-Id footer with the ID from the Gerrit change webpage, and Gerrit will correctly add the new commit as a patch set on the existing change.

Pulling a change down from Gerrit for review

When you want to review a change that's in Gerrit you just pull the change down into your workspace. The patch set on the Gerrit change web page has a list of command lines you can use.

Note: before you start your review, make sure that the change set has been rebased on the appropriate branch, as many Gerrit projects will only submit Fast Forward commits to master.

For example, from https://git.eclipse.org/r/#/c/11192/

git fetch ssh://pwebster@git.eclipse.org:29418/platform/eclipse.platform.ui refs/changes/92/11192/1 && git checkout FETCH_HEAD
git checkout -b change/11192/1
git rebase origin/master #optionally rebase

I usually add the second checkout-with-branch command, so that I'm not in detached HEAD state.

In EGit, right click on the repo in the Git Repositories view, pick Fetch from Gerrit... and select your review remote URI. Then you can type in the change number and use content assist to pick the correct patch set, or use the full ref (as listed in the Gerrit patch set), like refs/changes/92/11192/1. Then select Create and checkout a local branch. I leave the default it inserts there.

Then you can use EGit to rebase the change on origin/master

Reviewing a change in Gerrit

You can walk through the files on the Gerrit change page and add your comments inline against the various lines. When you save them individually they're considered drafts. After you've finished commenting the code, you can click the Review button.

If you are sending the patch back to be updated, usually you select in Code Review: -1 I would prefer that you didn't submit this, add a general comment if appropriate, and then choose the Publish Comments button.

If you are approving the change, you select +1 in the Verified and IP Clean categories, and +2 in the Code Review category. Then choose Publish and Submit.

You can also give a change a +1 Looks good to me, but someone else must approve Code Review and use Publish Comments. A second reviewer will then have to add their +1 or +2 and Publish and Submit.

Contributing to a build

Daily development occurs in the master branch, but weekly integration builds are done out of a branch called integration. The builder takes care of tagging the build inputs and updating bundle qualifiers for those bundles that have changed. To contribute a repository to the build, do the following:

Make sure you do a fetch on your repository
Ensure all desired changes for the build are in branch master
In the Git Repositories view, expand Branches > Local, and select integration. Right click and select checkout. (Note: the very first time, you will need to first "create a branch" for integration.)
Select branch master and select merge
Right-click on the repository and select Push to Upstream
Remember to switch back to master to continue more new development.

To contribute to a build from the git command line, first ensure your local master stream contains the contents you want to contribute to the build. Then, do the following:

 git pull
 git checkout integration
 git merge master
 git push origin integration

This will cause a fast-forward merge, so that both master and integration refer to the same commit. Past commits that were involved in builds will be identifiable by the build tag on that commit.

Changing what branch is built

The builder automatically takes a branch of each repository and contributes the latest branch contents to the build. The branch used for each repository is configured in the following file:

http://git.eclipse.org/c/platform/eclipse.platform.releng.maps.git/tree/org.eclipse.releng/tagging/repositories.txt

To build a different branch, edit this file and enter the branch name to be built on the line next to your repository. Commit and push the change. Use branch master for current development stream builds, and Rx_y_maintenance for maintenance builds.

Creating an integration branch

If your repository does not yet have a branch called integration, it will need to be created and pushed. This is done as follows:

Open the Git Repositories view, and expand Branches > Local.
Right-click on master, and select Create Branch...
For the branch name, enter integration. Leave the pull strategy as "None".
Click Finish
Right-click on the repository, and select Push...
In the Push dialog, ensure the correct remote is selected and click Next
In the Source ref field, select integration in the drop-down list. The destination spec will be filled in automatically. Click Add Spec to include this specification in the push operation.
Click Finish to complete the push operation

For command line users, do the following:

  git checkout master
  git branch integration
  git push origin integration

Manual tagging

Tagging for weekly integration builds is not needed, but sometimes you still need to tag. For example, tagging with a Rx_y tag when a release is done. To create a tag, use git tag mynewtag from the command line or the EGit Tag Dialog. Once a tag has been added, you must push the tag to the repository.

To push a specific tag, use git push origin mynewtag from the command line or use the following steps in EGit:

Team > Remote > Push...
Click Next to get to the Specifications Page
In the Source ref box, enter in refs/tags/mynewtag (content assist is available to quickly find a tag)
Click Add Spec
Click Next
Assuming the dry run is successful, click Finish

You can push all tags using git push --tags from the command line or pressing the Add All Tags Spec on the Specifications Page in EGit. However, this is risky as you will push all local tags and you will replace any tags that have been deleted from the remote repository.

The e4 Git page has some helpful scripts and additional information on tagging

Branches in our Platform Repos

We use a pre-receive hook in our repositories to enforce our branching/deleting policy.

committers can create, push anything, and delete their own topic branches on the remote repositories. Topic branches must have the form committerId/branchName. For example, pwebster/bug372119
committers can only push Fast Forward merges to the other branches, like origin/master or origin/R3_7_maintenance, or someone else's topic branch
committers cannot create or delete non-topic branches
committers can only delete tags with the same pattern as topic branches, committerId/tagName

Functionality can be re-enabled by setting certain config properties on the remote repository:

hooks.allownonffpush = true: Allow a non-FF push to any branch
hooks.allowdeletebranch = true: Allow any branch to be deleted
hooks.allowcreatenottopicbranch = true: Allow any branch to be created, like origin/R3_8_maintenance
hooks.allowdeletetag = true: Allow any tag to be deleted

To temporarily set a property, a committer with shell access executes

$ git config hooks.<property> true

To disable all properties, execute

$ git config --remove-section hooks

Commit changes to the main repo

Committing a change to the main repo is a 2-step process in git. In git, a commit creates a commit with the changed files in your local clone repository. A push will put that commit in our main repo. Committing and pushing are distinct operations in git.

Refer to the EGit/User Guide for more detailed instructions and pictures.

To get your changes to the main repo in EGit:

Do a pull or a fetch and a merge into your working branch
right-click on your project and use Team>Commit
Your commit message should include the bug number you are using for your fix/work.
check the files that should be included in the commit in the Files section
Commit

Then you need to push your changes to make sure they're visible to everyone else

right-click on your project and use Team>Push to Upstream
it should provide a status dialog with the refs that were updated, or a failure if the main repo has commits that you haven't either merged or rebased on.
if there's a failure, you need to #Update_to_pull_in_the_latest_changes_to_HEAD or the relevant branch.

Common commit message:

 Bug 349177 - [releng] stitch ui.workbench fork back into main
Updating some code to reflect the real change

The eGit Staging View provides a way to see all changed code in your workspace. You can select a subset of the changed files to commit.

Update to pull in the latest changes to HEAD

To make changes visible from our main repo is a 2 step process in git:

fetch which updates your cloned repo with all of the objects and remote branches from the main repo.
merge which updates your local branch to point to the correct commit
1. the most common case is called the "fast forward merge". That's where your repo has no local changes, and git can simply update your local master to the commit pointed to by origin/master
2. if you have a local commit that has not yet been pushed, you might have to deal with merge conflicts:
  1. you will either have to merge the new origin/master into your master (which will lead to a merge commit with 2 parent commits)
  2. or rebase your local commit onto that last commit coming from origin/master. This leaves the history of the main repo as a simple line, and is prefered ... I think.

Refer to the EGit/User Guide for more detailed instructions and pictures.

Git can do both fetch and merge for the current branch at once:

right click on your project and select Team>Pull

Making the same change in two branches

The easiest way to make the same change in two branches is by using the git "cherry-pick" command. The workflow is as follows:

Make the change and commit in branch 1
Check git log and copy the hash of the commit you just made to clipboard/etc
Checkout branch 2
Run "git cherry-pick <commit>" using the commit hash from step 2
If you run git log, you will now see a new commit in branch 2 with the same contents and author as the commit on branch 1
Push your changes in both branches

Merge conflicting changes

Refer to the EGit/User Guide for more detailed instructions and pictures.

If you pull changes for your branch and there are conflicts, you must merge them before you can commit your changes.

By default EGit merges conflicts into the local files using the old merge syntax Text Merge Markers. To switch to a compare editor merge, use the Team>Merge Tool menu item. See EGit/User Guide#Resolving_a_merge_conflict

Dealing with line terminators

Git has various options for normalizing line terminators between Windows (which uses CR/LF), and other platforms that use only LF. After trying various approaches, the Eclipse project has settled on the following approach:

Set core.autocrlf=false.
In your workspaces set General > Workspace > 'New text file line delimiter' to 'Unix'.
In the current dev branches (do not do this in maintenance branches) set 'New text file line delimiter' to 'Unix' on the 'Resource' property page of your projects.
If you don't work with EGit then it is your responsibility to avoid committing wrong line delimiters to the repository.
If using Windows, set core.fileMode=false. If you use EGit to clone the repository then this is done automatically for you.

References:

Pruning corrupt repository branches

Sometimes a branch in your repository might get corrupted and you may see errors such as "Could not read an object while parsing commit ...." in Egit or "Branch .... does not point to a valid object". The following command comes handy in such scenarios: git remote prune origin

(Always prefix a --dry-run to see what this command is going to do before you go ahead and execute it.)

References

For background reading on Git, see Git#Resources.

Notice: This Wiki is now read only and edits are no longer possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Platform-releng/Git Workflows

Contents

Getting EGit

Configure the workspace

Configure the project properties

Clone a repo

Configuring the repo

Importing the projects

A note on deleting projects

Start working in HEAD

Start working in a new branch

Create a patch

Apply a patch

Gerrit workflow for a committer

Setting up your repo

Resetting your current branch

Pushing a commit to Gerrit for review

Updating a change during the review cycle.

Updating a Gerrit change that was pushed with no Change-Id

Pulling a change down from Gerrit for review

Reviewing a change in Gerrit

Contributing to a build

Changing what branch is built

Creating an integration branch

Manual tagging

Branches in our Platform Repos

Commit changes to the main repo

Update to pull in the latest changes to HEAD

Making the same change in two branches

Merge conflicting changes

Dealing with line terminators

Pruning corrupt repository branches

References

Breadcrumbs

Notice: This Wiki is now read only and edits are no longer possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Platform-releng/Git Workflows

Contents

Getting EGit

Configure the workspace

Configure the project properties

Clone a repo

Configuring the repo

Importing the projects

A note on deleting projects

Start working in HEAD

Start working in a new branch

Create a patch

Apply a patch

Gerrit workflow for a committer

Setting up your repo

Resetting your current branch

Pushing a commit to Gerrit for review

Updating a change during the review cycle.

Updating a Gerrit change that was pushed with no Change-Id

Pulling a change down from Gerrit for review

Reviewing a change in Gerrit

Contributing to a build

Changing what branch is built

Creating an integration branch

Manual tagging

Branches in our Platform Repos

Commit changes to the main repo

Update to pull in the latest changes to HEAD

Making the same change in two branches

Merge conflicting changes

Dealing with line terminators

Pruning corrupt repository branches

References