Skip to main content
Jump to: navigation, search

Difference between revisions of "Platform-releng/Git Workflows"

m (Clone a repo)
m (Clone a repo)
Line 1: Line 1:
We'd like to capture some common CVS workflows used by the Eclipse Project and spell out the git/EGit equivalent.
+
We'd like to capture some common CVS workflows used by the Eclipse Project and spell out the git/EGit equivalent.  
  
Please read some of [http://progit.org/book/ Pro Git] to get a feel for how git repositories work. Refer to the [[EGit/User Guide]] for more detailed instructions and pictures.
+
Please read some of [http://progit.org/book/ Pro Git] to get a feel for how git repositories work. Refer to the [[EGit/User Guide]] for more detailed instructions and pictures.  
  
= Getting EGit =
+
= Getting EGit =
  
You can install EGit 1.0.0 from [http://download.eclipse.org/releases/indigo Indigo], it's already available.
+
You can install EGit 1.0.0 from [http://download.eclipse.org/releases/indigo Indigo], it's already available.  
  
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 http://download.eclipse.org/egit/updates-nightly]. You might have to use the site suggested in {{bug|331301}}'' - Updating from nightly build fails with MD5 error'' until that bug is fixed.
+
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 http://download.eclipse.org/egit/updates-nightly]. You might have to use the site suggested in {{bug|331301}}''- Updating from nightly build fails with MD5 error'' until that bug is fixed.  
  
= Clone a repo =
+
= Clone a repo =
  
The first step is to clone the one or more repos you need to work on. You want to clone the repo to a location ''outside'' your workspace. Then use the '''EGit Import Projects''' option to import the projects.
+
The first step is to clone the one or more repos you need to work on. You want to clone the repo 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.
+
Refer to the [[EGit/User Guide]] for more detailed instructions and pictures.  
  
# Switch to the '''Git Repository Exploring''' Perspective
+
#Switch to the '''Git Repository Exploring''' Perspective  
# Use '''Clone a Git repository''' [[Image:CloneGit.gif|Clone a git repository]]
+
#Use '''Clone a Git repository''' [[Image:CloneGit.gif|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), Those repos that have been migrated are bolded:
+
#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), Those repos that have been migrated are bolded:  
## ssh://userid@git.eclipse.org/gitroot/equinox/rt.equinox.bundles.git  
+
##'''ssh://userid@git.eclipse.org/gitroot/equinox/rt.equinox.bundles.git'''
## ssh://userid@git.eclipse.org/gitroot/equinox/rt.equinox.binaries.git  
+
##'''ssh://userid@git.eclipse.org/gitroot/equinox/rt.equinox.binaries.git'''
## ssh://userid@git.eclipse.org/gitroot/equinox/rt.equinox.framework.git
+
##'''ssh://userid@git.eclipse.org/gitroot/equinox/rt.equinox.framework.git'''
## ssh://userid@git.eclipse.org/gitroot/equinox/rt.equinox.incubator.git
+
##ssh://userid@git.eclipse.org/gitroot/equinox/rt.equinox.incubator.git  
## ssh://userid@git.eclipse.org/gitroot/equinox/rt.equinox.p2.git  
+
##'''ssh://userid@git.eclipse.org/gitroot/equinox/rt.equinox.p2.git'''
## ssh://userid@git.eclipse.org/gitroot/equinox/rt.equinox.security.git
+
##ssh://userid@git.eclipse.org/gitroot/equinox/rt.equinox.security.git  
## ssh://userid@git.eclipse.org/gitroot/jdt/eclipse.jdt.core.git
+
##ssh://userid@git.eclipse.org/gitroot/jdt/eclipse.jdt.core.git  
## ssh://userid@git.eclipse.org/gitroot/jdt/eclipse.jdt.debug.git
+
##ssh://userid@git.eclipse.org/gitroot/jdt/eclipse.jdt.debug.git  
## ssh://userid@git.eclipse.org/gitroot/jdt/eclipse.jdt.git
+
##ssh://userid@git.eclipse.org/gitroot/jdt/eclipse.jdt.git  
## ssh://userid@git.eclipse.org/gitroot/jdt/eclipse.jdt.ui.git
+
##ssh://userid@git.eclipse.org/gitroot/jdt/eclipse.jdt.ui.git  
## ssh://userid@git.eclipse.org/gitroot/pde/eclipse.pde.build.git
+
##ssh://userid@git.eclipse.org/gitroot/pde/eclipse.pde.build.git  
## ssh://userid@git.eclipse.org/gitroot/pde/eclipse.pde.git
+
##ssh://userid@git.eclipse.org/gitroot/pde/eclipse.pde.git  
## ssh://userid@git.eclipse.org/gitroot/pde/eclipse.pde.incubator.git
+
##ssh://userid@git.eclipse.org/gitroot/pde/eclipse.pde.incubator.git  
## ssh://userid@git.eclipse.org/gitroot/pde/eclipse.pde.ui.git
+
##ssh://userid@git.eclipse.org/gitroot/pde/eclipse.pde.ui.git  
## ssh://userid@git.eclipse.org/gitroot/platform/eclipse.platform.debug.git
+
##ssh://userid@git.eclipse.org/gitroot/platform/eclipse.platform.debug.git  
## ssh://userid@git.eclipse.org/gitroot/platform/eclipse.platform.git
+
##ssh://userid@git.eclipse.org/gitroot/platform/eclipse.platform.git  
## ssh://userid@git.eclipse.org/gitroot/platform/eclipse.platform.releng.git
+
##ssh://userid@git.eclipse.org/gitroot/platform/eclipse.platform.releng.git  
## ssh://userid@git.eclipse.org/gitroot/platform/eclipse.platform.resources.git
+
##ssh://userid@git.eclipse.org/gitroot/platform/eclipse.platform.resources.git  
## ssh://userid@git.eclipse.org/gitroot/platform/eclipse.platform.runtime.git
+
##ssh://userid@git.eclipse.org/gitroot/platform/eclipse.platform.runtime.git  
## ssh://userid@git.eclipse.org/gitroot/platform/eclipse.platform.team.git
+
##ssh://userid@git.eclipse.org/gitroot/platform/eclipse.platform.team.git  
## ssh://userid@git.eclipse.org/gitroot/platform/eclipse.platform.text.git
+
##ssh://userid@git.eclipse.org/gitroot/platform/eclipse.platform.text.git  
## ssh://userid@git.eclipse.org/gitroot/platform/eclipse.platform.ua.git
+
##ssh://userid@git.eclipse.org/gitroot/platform/eclipse.platform.ua.git  
## ssh://userid@git.eclipse.org/gitroot/platform/eclipse.platform.ui.git   *
+
##'''ssh://userid@git.eclipse.org/gitroot/platform/eclipse.platform.ui.git '''
## ssh://userid@git.eclipse.org/gitroot/platform/eclipse.platform.swt.git   *
+
##'''ssh://userid@git.eclipse.org/gitroot/platform/eclipse.platform.swt.git '''
## ssh://userid@git.eclipse.org/gitroot/platform/eclipse.platform.swt.binaries.git   *
+
##'''ssh://userid@git.eclipse.org/gitroot/platform/eclipse.platform.swt.binaries.git'''
# ''Next''
+
#''Next''  
# Select all branches to clone
+
#Select all branches to clone  
# ''Next''
+
#''Next''  
# Confirm the location that it will clone the repository into.
+
#Confirm the location that it will clone the repository into.  
# an initial branch of '''master''' and a remote name of '''origin''' are standard.
+
#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 :-)
+
#''Finish'' - Now just sit back while git copies the entire repo to your harddrive :-)
  
== Configuring the repo ==
+
== Configuring the repo ==
  
Unless you are working on topic branches, we work in a fairly linear history. Please set branch.'''branchname'''.rebase = true.
+
Unless you are working on topic branches, we work in a fairly linear history. Please set branch.'''branchname'''.rebase = true.  
  
Once you've cloned a repository, you can go the the ''Preferences>Team>Git>Configuration'' page. Select your repository, select the branch you picked when you cloned the repo, and add the new entry. Ex, for the default clone of '''master''', use '''branch.master.rebase=true'''
+
Once you've cloned a repository, you can go the the ''Preferences>Team>Git>Configuration'' page. Select your repository, select the branch you picked when you cloned the repo, and add the new entry. Ex, for the default clone of '''master''', use '''branch.master.rebase=true'''  
  
[[Image:RepositoryConfigurationSettings.png]]
+
[[Image:RepositoryConfigurationSettings.png]]  
  
== Importing the projects ==
+
== Importing the projects ==
  
 +
We need to get the projects from the repo into our workspace:
  
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''
  
# right click on your newly cloned repo and select '''Import Projects'''
+
Now you can start working.
# 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  ==
  
== 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).
  
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  =
  
= 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.
  
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]].  
  
See [[#Clone a repo]].
+
Refer to the [[EGit/User Guide]] for more detailed instructions and pictures.  
  
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).  
  
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 =
  
= 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'''.
  
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.  
  
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.
 +
##'''HEAD''' == current checked out commit
 +
##'''refs/heads/master''' means your '''master''' branch.
 +
##'''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''.
 +
##'''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.
  
# right click on one of your projects and choose '''Team>Switch To>New Branch'''
+
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.  
# you need to pick a source ref.
+
## '''HEAD''' == current checked out commit
+
## '''refs/heads/master''' means your '''master''' branch.
+
## '''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''.
+
## '''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 =
  
= 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.
  
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:
  
To create a patch:
+
#You need to show the commits in the history view.
 +
##Either right-click on a file you just committed and '''Show in history'''
 +
##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
  
# You need to show the commits in the history view.
+
= Apply a patch =
## Either right-click on a file you just committed and '''Show in history'''
+
## 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'''.
  
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.  
  
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:  
 
+
Patches created with git/EGit have a different pattern. They are diff statements that look like:
+
  
 
   diff --git a/bundles/org.eclipse.e4.ui.workbench.renderers.swt/src/org/eclipse/e4/ui/workbench/renderers/swt/HandledContributionItem.java b/bundles/org.eclipse.e4.ui.workbench.renderers.swt/src/org/eclipse/e4/ui/workbench/renderers/swt/HandledContributionItem.java
 
   diff --git a/bundles/org.eclipse.e4.ui.workbench.renderers.swt/src/org/eclipse/e4/ui/workbench/renderers/swt/HandledContributionItem.java b/bundles/org.eclipse.e4.ui.workbench.renderers.swt/src/org/eclipse/e4/ui/workbench/renderers/swt/HandledContributionItem.java
  index 99d339f..37bcf68 100644
+
index 99d339f..37bcf68 100644
  --- a/bundles/org.eclipse.e4.ui.workbench.renderers.swt/src/org/eclipse/e4/ui/workbench/renderers/swt/HandledContributionItem.java
+
--- a/bundles/org.eclipse.e4.ui.workbench.renderers.swt/src/org/eclipse/e4/ui/workbench/renderers/swt/HandledContributionItem.java
  +++ b/bundles/org.eclipse.e4.ui.workbench.renderers.swt/src/org/eclipse/e4/ui/workbench/renderers/swt/HandledContributionItem.java
+
+++ b/bundles/org.eclipse.e4.ui.workbench.renderers.swt/src/org/eclipse/e4/ui/workbench/renderers/swt/HandledContributionItem.java
  
To apply a patch like this, you should:
+
To apply a patch like this, you should:  
  
# copy and paste the patch into the ''Package Explorer''
+
#copy and paste the patch into the ''Package Explorer''  
# Select '''Apply patch to the workspace root'''
+
#Select '''Apply patch to the workspace root'''  
# ''Next''
+
#''Next''  
# under '''Patch Options''' set '''Ignore leading path name segments''' to ''2''
+
#under '''Patch Options''' set '''Ignore leading path name segments''' to ''2''  
# now you can examine the patch and apply is normally.
+
#now you can examine the patch and apply is normally.
  
= Tag the mapfile for a build =
+
= Tag the mapfile for a build =
  
We're still deciding on a best practice on tagging the repos and updating the map files for an I build.
+
We're still deciding on a best practice on tagging the repos and updating the map files for an I build.  
  
One option under discussion is to allow the I build to tag the repos and update the map files automatically based on '''master'''. In the normal case, the build will run with '''master'''. If we need a fix, a map file can be reverted and a new I build with "no repo tagging" can be started.
+
One option under discussion is to allow the I build to tag the repos and update the map files automatically based on '''master'''. In the normal case, the build will run with '''master'''. If we need a fix, a map file can be reverted and a new I build with "no repo tagging" can be started.  
  
When we have a bug for the discussion I'll update this item with the number.
+
When we have a bug for the discussion I'll update this item with the number.  
  
= Commit changes to the main repo =
+
= 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.
+
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.
+
Refer to the [[EGit/User Guide]] for more detailed instructions and pictures.  
  
To get your changes to the main repo in EGit:
+
To get your changes to the main repo in EGit:  
  
# Do a '''pull''' or a '''fetch''' and a '''merge''' into your working branch
+
#Do a '''pull''' or a '''fetch''' and a '''merge''' into your working branch  
# right-click on your project and use '''Team>Commit'''
+
#right-click on your project and use '''Team>Commit'''  
# Your commit message should include the bug number you are using for your fix/work.
+
#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
+
#check the files that should be included in the commit in the ''Files'' section  
# ''Commit''
+
#''Commit''
  
Then you need to push your changes to make sure they've visible to everyone else
+
Then you need to push your changes to make sure they've visible to everyone else  
  
# right-click on your project and use '''Team>Push to Upstream'''
+
#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.
+
#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.
+
#if there's a failure, you need to [[#Update_to_pull_in_the_latest_changes_to_HEAD]] or the relevant branch.
  
 +
<br> Common commit message:
  
Common commit message:
 
 
   Bug 349177 - [releng] stitch ui.workbench fork back into main
 
   Bug 349177 - [releng] stitch ui.workbench fork back into main
  Updating some code to reflect the real change
+
Updating some code to reflect the real change
 +
 
 +
= Update to pull in the latest changes to HEAD  =
  
= Update to pull in the latest changes to HEAD =
+
To make changes visible from our main repo is a 2 step process in git:
  
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
 +
##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'''
 +
##if you have a local commit that has not yet been pushed, you might have to deal with merge conflicts:  
 +
###you will either have to merge the new '''origin/master''' into your '''master''' (which will lead to a merge commit with 2 parent commits)
 +
###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.
  
# '''fetch''' which updates your cloned repo with all of the objects and remote branches from the main repo.
+
Refer to the [[EGit/User Guide]] for more detailed instructions and pictures.  
# '''merge''' which updates your local branch to point to the correct commit
+
## 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'''
+
## if you have a local commit that has not yet been pushed, you might have to deal with merge conflicts:
+
### you will either have to merge the new '''origin/master''' into your '''master''' (which will lead to a merge commit with 2 parent commits)
+
### 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:
  
Git can do both '''fetch''' and '''merge''' for the current branch at once:
+
#right click on your project and select '''Team&gt;Pull'''
  
# right click on your project and select '''Team>Pull'''
+
= Merge conflicting changes  =
  
= Merge conflicting changes =
+
Refer to the [[EGit/User Guide]] for more detailed instructions and pictures.
  
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.  
  
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 [http://www.kernel.org/pub/software/scm/git/docs/git-merge.html#_how_conflicts_are_presented Text Merge Markers]. To switch to a compare editor merge, use the '''Team&gt;Merge Tool''' menu item. See [[EGit/User Guide#Resolving_a_merge_conflict]]
  
By default EGit merges conflicts into the local files using the old merge syntax [http://www.kernel.org/pub/software/scm/git/docs/git-merge.html#_how_conflicts_are_presented 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]]
+
= Cross-referencing between bugzilla and git  =
  
= Cross-referencing between bugzilla and git =
+
Some committers like to attach patches to bugzilla for all changes, so they have a record of exactly what changes occurred to fix the bug. With git there is a better way:
  
Some committers like to attach patches to bugzilla for all changes, so they have a record of exactly what changes occurred to fix the bug. With git there is a better way:
+
*Push the change to git.eclipse.org  
* Push the change to git.eclipse.org
+
*Navigate to git.eclipse.org in your web browser  
* Navigate to git.eclipse.org in your web browser
+
*Find your repository, and click on the "Log" tab  
* Find your repository, and click on the "Log" tab
+
*Click on your commit, which should be near the top of the log at this point  
* Click on your commit, which should be near the top of the log at this point
+
*You are now on a page that shows a graphical diff of call changes that occurred in that commit. Copy the URL of this commit page into a bugzilla comment.
* You are now on a page that shows a graphical diff of call changes that occurred in that commit. Copy the URL of this commit page into a bugzilla comment.
+
  
Now if someone in the future wants to see what changes were made to fix the bug, they have a one click link to see all the changes.
+
Now if someone in the future wants to see what changes were made to fix the bug, they have a one click link to see all the changes.  
  
 +
<br>
  
= References =
+
= References =
  
* [[EGit/User_Guide]] - describes the dialogs and commands that can be accessed for the EGit eclipse plugin
+
*[[EGit/User Guide]] - describes the dialogs and commands that can be accessed for the EGit eclipse plugin  
* [http://progit.org/book/ Pro Git] - a handy description of how git works and some of what git can do
+
*[http://progit.org/book/ Pro Git] - a handy description of how git works and some of what git can do  
* [http://git-scm.com/ Git SCM] - the main git site
+
*[http://git-scm.com/ Git SCM] - the main git site  
* [http://code.google.com/p/msysgit/ msysgit] - A git client and bash shell for windows - might need some crlf flags set, not sure.
+
*[http://code.google.com/p/msysgit/ msysgit] - A git client and bash shell for windows - might need some crlf flags set, not sure.

Revision as of 10:17, 5 August 2011

We'd like to capture some common CVS workflows used by the Eclipse Project and spell out the git/EGit equivalent.

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.

Getting EGit

You can install EGit 1.0.0 from Indigo, it's already available.

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. You might have to use the site suggested in bug 331301- Updating from nightly build fails with MD5 error until that bug is fixed.

Clone a repo

The first step is to clone the one or more repos you need to work on. You want to clone the repo 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.

  1. Switch to the Git Repository Exploring Perspective
  2. Use Clone a Git repository Clone a git repository
  3. 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), Those repos that have been migrated are bolded:
    1. ssh://userid@git.eclipse.org/gitroot/equinox/rt.equinox.bundles.git
    2. ssh://userid@git.eclipse.org/gitroot/equinox/rt.equinox.binaries.git
    3. ssh://userid@git.eclipse.org/gitroot/equinox/rt.equinox.framework.git
    4. ssh://userid@git.eclipse.org/gitroot/equinox/rt.equinox.incubator.git
    5. ssh://userid@git.eclipse.org/gitroot/equinox/rt.equinox.p2.git
    6. ssh://userid@git.eclipse.org/gitroot/equinox/rt.equinox.security.git
    7. ssh://userid@git.eclipse.org/gitroot/jdt/eclipse.jdt.core.git
    8. ssh://userid@git.eclipse.org/gitroot/jdt/eclipse.jdt.debug.git
    9. ssh://userid@git.eclipse.org/gitroot/jdt/eclipse.jdt.git
    10. ssh://userid@git.eclipse.org/gitroot/jdt/eclipse.jdt.ui.git
    11. ssh://userid@git.eclipse.org/gitroot/pde/eclipse.pde.build.git
    12. ssh://userid@git.eclipse.org/gitroot/pde/eclipse.pde.git
    13. ssh://userid@git.eclipse.org/gitroot/pde/eclipse.pde.incubator.git
    14. ssh://userid@git.eclipse.org/gitroot/pde/eclipse.pde.ui.git
    15. ssh://userid@git.eclipse.org/gitroot/platform/eclipse.platform.debug.git
    16. ssh://userid@git.eclipse.org/gitroot/platform/eclipse.platform.git
    17. ssh://userid@git.eclipse.org/gitroot/platform/eclipse.platform.releng.git
    18. ssh://userid@git.eclipse.org/gitroot/platform/eclipse.platform.resources.git
    19. ssh://userid@git.eclipse.org/gitroot/platform/eclipse.platform.runtime.git
    20. ssh://userid@git.eclipse.org/gitroot/platform/eclipse.platform.team.git
    21. ssh://userid@git.eclipse.org/gitroot/platform/eclipse.platform.text.git
    22. ssh://userid@git.eclipse.org/gitroot/platform/eclipse.platform.ua.git
    23. ssh://userid@git.eclipse.org/gitroot/platform/eclipse.platform.ui.git 
    24. ssh://userid@git.eclipse.org/gitroot/platform/eclipse.platform.swt.git 
    25. ssh://userid@git.eclipse.org/gitroot/platform/eclipse.platform.swt.binaries.git
  4. Next
  5. Select all branches to clone
  6. Next
  7. Confirm the location that it will clone the repository into.
  8. an initial branch of master and a remote name of origin are standard.
  9. Finish - Now just sit back while git copies the entire repo to your harddrive :-)

Configuring the repo

Unless you are working on topic branches, we work in a fairly linear history. Please set branch.branchname.rebase = true.

Once you've cloned a repository, you can go the the Preferences>Team>Git>Configuration page. Select your repository, select the branch you picked when you cloned the repo, and add the new entry. Ex, for the default clone of master, use branch.master.rebase=true

RepositoryConfigurationSettings.png

Importing the projects

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

  1. right click on your newly cloned repo and select Import Projects
  2. you want Import existing projects from the Working Directory
  3. Next
  4. Select the projects that you want to import from the repository
  5. 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.

  1. right click on one of your projects and choose Team>Switch To>New Branch
  2. 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
  3. name the branch R3_7_maintenance
  4. select the Rebase merge option
  5. 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:

  1. 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
  2. right click on the commit in the History view, and select Create Patch
  3. 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.e4.ui.workbench.renderers.swt/src/org/eclipse/e4/ui/workbench/renderers/swt/HandledContributionItem.java b/bundles/org.eclipse.e4.ui.workbench.renderers.swt/src/org/eclipse/e4/ui/workbench/renderers/swt/HandledContributionItem.java
index 99d339f..37bcf68 100644
--- a/bundles/org.eclipse.e4.ui.workbench.renderers.swt/src/org/eclipse/e4/ui/workbench/renderers/swt/HandledContributionItem.java
+++ b/bundles/org.eclipse.e4.ui.workbench.renderers.swt/src/org/eclipse/e4/ui/workbench/renderers/swt/HandledContributionItem.java

To apply a patch like this, you should:

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

Tag the mapfile for a build

We're still deciding on a best practice on tagging the repos and updating the map files for an I build.

One option under discussion is to allow the I build to tag the repos and update the map files automatically based on master. In the normal case, the build will run with master. If we need a fix, a map file can be reverted and a new I build with "no repo tagging" can be started.

When we have a bug for the discussion I'll update this item with the number.

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:

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

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

  1. right-click on your project and use Team>Push to Upstream
  2. 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.
  3. 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

Update to pull in the latest changes to HEAD

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

  1. fetch which updates your cloned repo with all of the objects and remote branches from the main repo.
  2. 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:

  1. right click on your project and select Team>Pull

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

Cross-referencing between bugzilla and git

Some committers like to attach patches to bugzilla for all changes, so they have a record of exactly what changes occurred to fix the bug. With git there is a better way:

  • Push the change to git.eclipse.org
  • Navigate to git.eclipse.org in your web browser
  • Find your repository, and click on the "Log" tab
  • Click on your commit, which should be near the top of the log at this point
  • You are now on a page that shows a graphical diff of call changes that occurred in that commit. Copy the URL of this commit page into a bugzilla comment.

Now if someone in the future wants to see what changes were made to fix the bug, they have a one click link to see all the changes.


References

  • EGit/User Guide - describes the dialogs and commands that can be accessed for the EGit eclipse plugin
  • Pro Git - a handy description of how git works and some of what git can do
  • Git SCM - the main git site
  • msysgit - A git client and bash shell for windows - might need some crlf flags set, not sure.

Back to the top