= Getting Started =
== Overview ==
If you're new to Git or distributed version control systems generally, then you might want to read [[EGit/Git For Eclipse Users|Git for Eclipse Users]] first. More background and details can be found in the on-line book [http://progit.org/book/ Pro Git].
If there you are coming from CVS, you can find common CVS workflows for Git [[Platform-releng/Git Workflows]].
== Basic Tutorial: Adding a project to version control ==
=== Configuration ===
==== Identifying yourself ====
Whenever the history of the repository is changed (technically, whenever a commit is created), Git keeps track of the user who created that commit. The identification consists of a name (typically a person's name) and an e-mail address. This information is stored in file
~/.gitconfig under dedicated keys.
EGit will ask you for this information when you create your first commit. By default, this dialog is shown only once until you create a new workspace or tick the checkbox "Show initial configuration dialog" on the Git Preference page: [[Image:Egit-0.11-initialConfigurationDialog.png]] You can also untick "Don't show this dialog again" if you want to see it again later. Instead of using this dialog, you can always change this information using the Git configuration:
*Click '''Preferences > Team > Git > Configuration''' *Click '''New Entry''' and enter the key value pairs
[[Image:Egit-0.9-getstarted-email.png]] [[Image:Egit-0.9-getstarted-name.png]] ==== Setting up the Home Directory on Windows ==== Add the environment variable
HOME to your environment variables.
#In Windows 7, type "environment" at the start menu
#Select "Edit environment variables for your account"
#Click the "New" button.
#Enter "HOME" in the name field
#Enter "%USERPROFILE%" or some other path in the value field.
#Click OK, and OK again. You have just added the Home directory on Windows.
EGit needs this path for looking up the user configuration (.gitconfig).
HOME should point to your home directory e.g.
C:\Users\Tom. '''Ensure correct case!''' E.g.
C:\users instead of
C:\Users may cause problems!
HOME variable is not defined the home directory will be calculated by concatenating
HOMEDRIVE are not defined
HOMESHARE will be used.
EGit shows a warning if
HOME is not defined explicitly. Keep in mind that if you set the HOME environment variable while Eclipse is running, you will still see following warning. You will have to restart Eclipse for it to recognize the HOME value.
[[Image:Egit no home.png]]
==== Pointing out the System wide configuration ====
If you use Git for Windows as a companion to EGit, make sure EGit knows where Git is installed so it can find the "system wide settings", e.g. how core.autocrlf is set. Go to the settings and look under Team>Git>Configuration and then the System Settings tab.
If you selected one of the options to use Git from the Command Line Prompt when you installed Git for Windows, then the location of the system
wide settings is filled in with a path and everything is fine. If not, use the Browse button to locate where Git is installed, e.g. C:\Program Files(x86)\Git.
This advice also applies to users of other Git packagings, e.g. Git under Cygwin or TortoiseGit.
Non-Windows users should in theory check this setting, but the system wide settings are usually not used on non-Windows platforms.
=== Create Repository ===
* Create a new Java project
HelloWorld. (In this case, the project was built outside of your Eclipse Workspace.)
* Select the project, click '''File > Team > Share Project'''
* Select repository type '''Git''' and click '''Next'''
* To configure the Git repository select the new project
* Click '''Create Repository''' to initialize a new Git repository for the
HelloWorld project. If your project already resides in the working tree of an existing Git repository the repository is chosen automatically.
* Click '''Finish''' to close the wizard.
* The decorator text "[master]" behind the project shows that this project is tracked in a repository on the ''master'' branch and the question mark decorators show that the
.project and the
.settings files are not yet under version control
=== Track Changes ===
*Click '''Team > Add''' on the project node. (This menu item may read '''Add to Index''' on recent versions of Egit)
*The ''+'' decorators show that now the project's files have been added to version control
*Mark the "bin" folder as "ignored by Git", either by right-clicking on it and selecting '''Team > Ignore''' or by creating a file
.gitignore in the project folder with the following content
*This excludes the
bin folder from Git's list of tracked files.
.gitignore to version control ('''Team > Add'''):
* You may have to set your Package Explorer filters in order to see
.gitignore displayed in the Package Explorer. To access filters, select the down arrow at right of Package Explorer tab to display View Menu.
* Select '''Filters...''' from the View Menu and you will be presented with the Java Element Filters dialog. Unselect the top entry to display files that begin with . (period) such as
*Click '''Team > Commit''' in the project context menu
*Enter a commit message explaining your change, the first line (followed by an empty line) will become the short log for this commit. By default the author and committer are taken from the
.gitconfig file in your home directory.
*You may click '''Add Signed-off-by''' to add a ''Signed-off-by:'' tag.
*If you are committing the change of another author you may alter the author field to give the name and email address of the author.
*Click '''Commit''' to commit your first change.
*Note that the decorators of the committed files changed.
=== Inspect History ===
*Click '''Team > Show in History''' from the context menu to inspect the history of a resource
*Create a new Java class
Hello.java and implement it
*Add it to version control and commit your change
*Improve your implementation and commit the improved class
*The resource history should now show 2 commits for this class
*Click the '''Compare Mode''' toggle button in the History View
src/Hello.java in the Resource list of the History View to open your last committed change in the Compare View
'''Congratulations, you just have mastered your first project using Git !'''
== GitHub Tutorial== === Create Local Repository === *follow [[EGit/User Guide/Getting Started]] to create a new local repository (with your content instead of the demo project) === Create Repository at GitHub === *create a new repository at GitHub [[Image:Egit-0.10-github-create-repo.png]] On the next screen you can see the URLs you may use to access your fresh new repository: *click '''SSH''' to choose the ''SSH protocol''. It can be used for read and write access *click '''HTTP''' to choose the ''HTTP protocol''. It can also be used for read and write access. *click '''Git Read-Only''' to choose the anonymous ''git protocol'' for cloning. It's the most efficient protocol git supports. Since the ''git protocol'' doesn't support authentication it's usually used to provide efficient read-only access to public repositories. [[Image:Egit-0.10-github-cloneurl.png]] === Eclipse SSH Configuration === *Open the Eclipse '''Preferences''' and ensure that your SSH2 home is configured correctly (usually this is ~/.ssh) and contains your SSH2 keys [[Image:Egit-0.10-ssh-preferences.png]] *if you don't have SSH keys yet you may generate them on the second tab '''Key Management''' of this dialog, use a good pass phrase to protect your private key, for more details see [http://help.github.com/working-with-key-passphrases/ "working with key passphrases"] *upload your public SSH key to your [https://github.com/account GitHub account settings] === Push Upstream === *Click '''Team > Remote > Push...''' and copy and paste the SSH URL of your new GitHub repository *If you are behind a firewall which doesn't allow SSH traffic use the GitHub HTTPS URL instead and provide your GitHub user and password instead of using the uploaded public SSH key. To store your credentials into the Eclipse secure store click '''Store in Secure Store'''. *'''Note:''' many HTTP proxies are configured to block HTTP URLs containing a user name, since disclosing a user name in an HTTP URL is considered a security risk. In that case remove the username from the HTTP URL and only provide it in the user field. It will be sent as an HTTP header. [[Image:Egit-0.10-github-pushurl.png]] *Click '''Next''' and on first connection accept GitHub's host key. *Enter your SSH key's passphrase and click '''OK'''. *On the next wizard page click '''Add all branches spec''' to map your local branch names 1:1 to the same branch names in the destination repository. [[Image:Egit-0.10-github-push-refspec.png]] *Click '''Next'''. The push confirmation dialog will show a preview of the changes that will be pushed to the destination repository. [[Image:Egit-0.10-github-push-preview.png]] *Click '''Finish''' to confirm that you want to push these changes. *The next dialog reports the result of the push operation. [[Image:Egit-0.10-github-pushresult.png]] *Point your browser at your GitHub repository to see that your new repository content has arrived [[Image:Egit-0.10-github-pushed-repo.png]]
==EclipseCon 2012 Git Tutorial== Find all exercises and the slides [https://docs.google.com/open?id=0B4F_gjXVrHZVRXkydE0xVFBRRkc1WUpEcXdwQ2I1dw here]. Follow the [https://docs.google.com/document/d/1UCbNCvljiInc6-vwBsHHzOQ1ItC10f1bFAOi8T30DJ8/edit exercise #1] to prepare for the Git Tutorial. = Concepts = Git is built on a few simple and very powerful ideas. Knowing them helps to understand more easily how git works. == Repository == The Repository or Object Database stores all objects which make up the history of the project. All objects in this database are identified through a secure 20 byte [http://en.wikipedia.org/wiki/SHA-1 SHA-1 hash] of the object content. This has several advantages: * comparing two objects boils down to comparing two SHA-1 hashes * since object names are computed from the object content in the same way in every git repository the same object will be stored under the same name in all repositories which happen to contain this object * an object never changes once created (obvious since changing the contents means a new hash must be calculated and a new name assigned) * repository corruption can easily be detected by checking if the SHA-1 object name still is the secure hash of the object's content Git has four object types : * A '''Blob object''' stores file content * A '''Tree object''' stores the directory structure and contains '''Blob objects''' and other '''Tree objects''' together with their file system names and modes * A '''Commit object''' represents a snapshot of the directory structure at the time of the commit and has a link to its predecessor '''Commit object''' which form an acyclic graph of the repository revisions forming the repository history. * A '''Tag object''' is a symbolic named link to another repository object which contains the object name and type of the referenced object and optionally information about the one who created the tag and signing information. The object database is stored in the
.git/objects directory. Objects are either stored as loose objects or in a pack format efficiently packing many objects into a single file to enable efficient storage and transport of objects.
Git provides a built-in trust chain through secure SHA-1 hashes which allow it to verify if objects obtained from a (potentially untrusted) source are correct and have not been modified since they have been created.
If you get the signed tag for e.g. a project release which you can verify with e.g. the tagger's (e.g. the project lead's) public signing key
git ensures that the chain of trust covers the following:
* the signed tag identifies a commit object
* the commit object represents exactly one project revision including its content and history
* the commit object contains the tree of blob objects and other tree objects representing the directory structure of the project revision
* the blob objects contain the file contents for this project revision
All of the involved object names can be checked for consistency using the SHA-1 algorithm to ensure the correctness of the project revision and this way ensure that the entire history can be trusted.
== Index ==
The '''Git Index''' is a binary file stored in the
.git/index directory containing a sorted list of file names, file modes, file meta data used to efficiently detect file modifications and the SHA-1 object name of blob objects.
It has the following important properties:
* The index contains all information necessary to generate a single uniquely defined tree object. E.g. a commit operation generates this tree, stores it in the object database and associates it with the commit.
* The index enables fast comparison of the tree it defines with the current working directory. This is achieved by storing additional meta data about the involved files in the index data.
* The index can efficiently store information about merge conflicts between the trees involved in the merge so that for each pathname there is enough information about the involved trees to enable a three-way merge.
== Branches ==
A branch in Git is a named reference to a commit. There are two types of branches, namely "Local" and "Remote Tracking" branches which serve different purposes.
=== Local Branches ===
Whenever a change to a (local) Repository is committed, a new commit object is created. Without any other means, it would be very difficult to keep track of the changes in the Repository, in particular when other commits are added to the Repository, for example due to an update from the remote Repository or when checking out another commit.
A local branch helps with this task by providing a (local) name by which the "current" commit can be found. When changes are committed to the local repository, the branch is automatically updated to point to the newly created commit.
In addition, it is possible to add a so-called upstream configuration to a local branch which can be helpful when synchronizing with a remote repository.
=== Remote Tracking Branches ===
Remote tracking branches are created automatically when cloning and fetching from remote repositories. A remote tracking branch in the local repository always corresponds to a (local) branch in the remote repository, and the name of such a branch is following a certain convention.
The remote tracking branch points to the same commit as the corresponding branch in the remote repository (at the time of clone/fetch).
Remote tracking branches can be used for automated creation of upstream configuration for local branches.
== Working Directory ==
The working directory is the directory used to modify files for the next commit. By default it is located one level above the .git directory.
Making a new commit involves typically the following steps :
* Checkout the branch the new commit shall be based on, this changes the working directory so that it reflects the ''HEAD'' revision of the branch.
* Do modifications in the working directory
* Tell git about these modifications (add modified files). This transfers the modified file contents into the object database and prepares the tree to be committed in the index.
* Commit the tree prepared in the index into the object database.
* The result is a new commit object and the ''HEAD'' of the current branch moves to the new commit.
== Recording Changes in the Repository ==
You start from a fresh checkout of a branch of a local repository. You want to do some changes and record snapshots of these changes in the repository whenever you reach a state of your changes you want to record.
Each file in the working directory can either be ''tracked'' or ''untracked''.
* Tracked files are those which were in the last snapshot or files which have been newly staged into the ''index''. They can be ''unmodified'', ''modified'', or ''staged''.
* Untracked files are all other files which were not in the last snapshot and have not been added to the ''index''.
When you first clone a repository all files in the working directory will be ''tracked'' and ''unmodified'' since they have been freshly checked out and you didn't start editing them yet.
As you edit files git will recognize they are ''modified'' since you have modified them since the last commit.
You ''stage'' the modified files into the index and then commit the staged changes and the cycle repeats.
This lifecycle is illustrated here
= Tasks =
== Creating Repositories ==
=== Considerations for Git Repositories to be used in Eclipse ===
==== The short story ====
When setting up Git Repositories with EGit, there are two recommendations for the creation of "productive" (as opposed for "playground") Repositories:
* Don't create the Repository within the Eclipse workspace
** Be careful when cloning or creating a Repository
** Make sure to use the Git Sharing Wizard correctly
* Don't create a Repository with an Eclipse project as root
** Make sure to use the Git Sharing Wizard correctly
The first one happens when you specify a workspace folder during cloning or creation of a Repository.
Both of the above will happen when you use the Git Sharing Wizard from an Eclipse project that you have created manually in your workspace without taking precautions (the wizard has been fixed in the latest version).
Below you will find some motivation for these recommendations.
==== The longer story ====
===== Eclipse Workspace and Repository working directory =====
Git Repositories can be created in different ways, for example by cloning from an existing Repository, by creating one from scratch, or by using the EGit Sharing wizard.
In any case (unless you create a "bare" Repository, but that's not discussed here), the new Repository is essentially a folder on the local hard disk which contains the "working directory" and the metadata folder. The metadata folder is a dedicated child folder named ".git" and often referred to as ".git-folder". It contains the actual repository (i.e. the Commits, the References, the logs and such).
The metadata folder is totally transparent to the Git client, while the working directory is used to expose the currently checked out Repository content as files for tools and editors.
Typically, if these files are to be used in Eclipse, they must be imported into the Eclipse workspace in one way or another. In order to do so, the easiest way would be to check in .project files from which the "Import Existing Projects" wizard can create the projects easily. Thus in most cases, the structure of a Repository containing Eclipse projects would look similar to something like this:
===== Implications =====
The above has the following implications:
* It is probably not a good idea to make a project the root folder of your Repository
: The reason is that you will never be able to add another project to this Repository, as the .project file will occupy the root folder; you could still add projects as sub-folders, but this kind of project nesting is known to cause lots of problems all over the place. In order to add another project, you would have to move the project to a sub-folder in the Repository and add the second project as another sub-folder before you could commit this change.
* It is a good idea to keep your Repository outside of your Eclipse Workspace
: There are several reasons for this:
: The new Repository will consider the complete folder structure of the Eclipse workspace as (potential) content. This can result in performance issues, for example when calculating the changes before committing (which will scan the complete .metadata folder, for example); more often than not, the workspace will contain dead folders (e.g. deleted projects) which semantically are not relevant for EGit but can not be excluded easily.
: The metadata (.git-) folder will be a child of the Eclipse Workspace. It is unclear whether this might cause unwanted folder traversals by Eclipse.
: You can easily destroy your Repository by destroying your Eclipse Workspace
=== Creating a new empty Git Repository ===
You can create a project first and share it afterwards. The Share Project Wizard supports creation of Git repositories (see [[EGit/User Guide/Sharing#Adding_a_project_to_version_control|Adding a project to version control]]).
You can also create a new empty Git Repository from the Git Repositories View (see [[EGit/User_Guide#Creating_a_Repository|Creating a Repository]]).
=== Creating a Git Repository for multiple Projects ===
You may first create multiple projects under a common directory and then create a common repository for all projects in one go:
*create the Eclipse projects e.g. a, b, c under a common directory e.g.
*select all projects a, b, c - from context menu click '''Team > Share Project > Git'''
*select all projects a, b, c
*the wizard automatically moves up the default repository location to the parent folder since multiple projects have been selected
*click '''Create Repository''' and '''Finish'''
== Starting from existing Git Repositories == In order to work with the content of a Git repository in the Eclipse workbench, the contained files and folders must be imported as projects. In principle, this import can be done using the generic "New Project" or "Import..." wizards, since the working directory of a Git Repository is just a normal directory in the local file system. However, the newly created projects would still have to be shared manually with Git. The "Import Projects from Git" wizards integrates project import and sharing and also offers some extra convenience. === Starting the import wizard === To start the wizard click '''Import > Git > Projects from Git''' If you started in a clean workspace, the first page will display an empty list: [[Image:Egit-0.9-import-projects-select-repository.png]] Before you can continue, you need to add one or several Git repositories to the list. If you have already repositories in the list, this step is optional. === Cloning or adding Repositories === There are two ways to add Git repositories to the list: #Clone a remote repository #Add an existing repository from your local file system ==== Cloning a Repository ==== The first option is used if you start with a remote repository. The clone operation will copy that repository to your local file system. To start the Clone Wizard click '''Clone...'''. The Clone Wizard is described in more detail in [[EGit/User Guide#Cloning_Remote_Repositories|Cloning Remote Repositories]]. Upon successful completion of the clone operation, the newly cloned repository appears in the list automatically. ==== Adding a Repository ==== The second option is useful if you already have a repository in your local file system, for example because you have cloned it earlier, you created it from scratch or you copied it from somewhere else. Click '''Add...'''; and select a directory in the local file system. Press '''Search''' to trigger a scan for Git repositories contained in this directory. If Git repositories are found, they will be listed and you can select repositories to add : [[Image:Egit-0.11-import-projects-add-dialog.png]] After successful completion, the repository list should contain some repositories: [[Image:Egit-0.11-import-projects-filled-list.png]] === Selecting a Repository from the List === You can now select a repository and click '''Next'''. On the following wizard page, you will decide how to import projects. === Importing projects === This page offers a group with radio buttons that allow you to select a wizard and a directory tree that optionally allows you to select a folder in the working directory. [[Image:Egit-0.11-import-projects-select-wizard.png]] === Wizard for project import === ==== Import Existing Projects ==== If this radio button is selected, the wizard will scan the local file system for .project files and display the projects found for being imported. This is the most comfortable solution and should be used if .project files are checked into the Repository. ===== Limiting the Scope for Project Import ===== In this case, the directory tree at the bottom is active. You can limit the search for .project files by selecting a folder in this tree, otherwise the complete working directory of the repository will be scanned. On the next page, a list of the found projects (if any) will be shown. This is very similar to the generic '''Import Existing Projects''' wizard, but has some additional filtering capabilities: [[Image:Egit-0.9-import-projects-select-projects.png]] ==== Use the New Projects Wizard ==== When this option is chosen, the generic "New Project" wizard will open. After completion of the "New Project" wizard, the "Import Projects from Git" wizard will resume and assist with sharing the projects you just created. In this case, the directory tree at the bottom is inactive, as the selection is not relevant for the "New Project" wizard. ==== Import as General Project ==== This option can be helpful when there are neither .project files available nor a suitable "New Project" wizard applies to the content of the Git Repository. If chosen, the wizard will generate a .project file and point the project to a folder of the Repository's working directory. The result is a "General Project". By default, the newly generated project will point to the working directory of the Repository. By selecting some folder from the directory tree at the bottom, you can have the project generated for that folder. Click '''Next''' to open a simple dialog for entering a name and a directory for the new project: [[Image:Egit-0.9-import-projects-general-project.png]] By default the suggested project name matches the name of the directory.
== Working with remote Repositories == === Cloning Remote Repositories === Using the Git Clone Wizard you may clone remote repositories using different transport protocols. The wizard can be started from the "Import Projects from Git" wizard using
'''Import... > Git > Projects from Git > Next > Clone...''' or from the "Git Repositories View" (described in [[EGit/User_Guide#Managing_Repositories|Managing Repositories]]) using the '''Clone a Git Repository''' toolbar button or view menu. ==== Repository Selection ==== On the first page of the wizard enter the location of the remote repository: [[Image:Egit-0.9-clone-wizard-url-page.png]] *'''URI''' - The complete URI of the remote repository or the path on the file system. This field is automatically synchronized with the other fields.
Note that you can use the '''Local file...''' button to browse for a local directory and that the URI field offers content assist by offering previously used values *'''Host''' - The name of the remote host or empty if cloning from the file system. *'''Repository Path''' - Path to the remote repository or on the file system. *'''Protocol''' - One of the protocols described below. *'''Port''' - Port number. *'''User''' - The user name used for authentication. *'''Password''' The password used for authentication. *'''Store in Secure Store''' Whether the password is saved in the Eclipse secure store. The following protocols are supported: *'''file''' - File system access to the repository. *'''ftp''' - [http://tools.ietf.org/html/rfc959 File Transfer Protocol] *'''git''' - The most efficient built-in git protocol (default port 9418). This protocol doesn't provide authentication. Typically used for anonymous read access to the repository. *'''http''' - [http://tools.ietf.org/html/rfc2616 Hypertext Transfer Protocol] can be tunneled through firewalls. *'''https''' - [http://tools.ietf.org/html/rfc2818 Hypertext Transfer Protocol Secure] can be tunneled through firewalls. *'''sftp''' - [http://en.wikipedia.org/wiki/SSH_File_Transfer_Protocol SSH File Transfer Protocol] *'''ssh''' - Git over [http://tools.ietf.org/html/rfc4251 secure shell (SSH)] protocol. Typically used for authenticated write access to the repository.
'''Note:''' If you are behind a firewall you may need to configure your proxy settings ('''Preferences > General > Network Connections'''). Many HTTP proxies are configured to block URLs containing a username (and/or password) like e.g. http://fred:email@example.com/egit.git hence it's recommended to use the ''user'', ''password'' fields at the bottom of the wizard page, the credentials will be transmitted as HTTP headers. ==== Branch Selection ==== On the next page choose which branches shall be cloned from the remote repository: [[Image:Egit-0.11-clone-wizard-branch-page.png]] If you are not sure which branches you need, simply hit "Select All". You can filter the branches by their name by typing using the text control above the list. Note, however, that branches that have been checked will always be shown in the list, i.e. they will not be filtered. ==== Local Destination ==== On the next page define where you want to store the repository on the local file system and define some initial settings. [[Image:Egit-0.9-clone-wizard-destination-page.png]] *'''Directory''' - The directory which will contain the Git repository. It will be created by the wizard if it does not yet exist. *'''Initial branch''' - Choose here which local branch will be created and initially checked out. *'''Remote name''' - Define a name for the remote repository. The default is "origin". The default root path for storing Git repositories can be configured in the preference '''Team > Git > Default Repository Folder'''
You can press '''Finish''' on this page or press '''Next''' if you are working with [http://code.google.com/p/gerrit/ Gerrit Code Review] and you want to configure your repository accordingly. ==== Cloning from specific locations ==== The Clone wizard of EGit can be extended by other plugins in order to search for repositories on specific backends which host git repositories. Currently such an extension is available for Github and soon will be available for Gerrit. For both you need to install the respective Mylyn connectors. The Gerrit Mylyn connector extension then will also configure the remote repository for the work with Gerrit. This can also be done or changed later from the Git Repositories View, see [[#Gerrit_Configuration|Gerrit Configuration]]. When you have installed such an extension, the Clone wizard opens with a selection page where you can choose between different sources of the repository to clone: [[Image:Egit-1.3-CloneSources.png]] === Pushing to other Repositories === ==== Pushing to upstream ==== If you are working with a local branch which has a so-called "[[#Upstream_Configuration|Upstream Configuration]]", the most convenient way for pushing relies on this upstream configuration. Typically local branches are created based on a remote tracking branch. Since the remote tracking branch is associated with a remote and the remote contains the information required to access the corresponding remote repository, it is possible to automatically create this upstream configuration while creating the local branch (see [[#Branching|Branching]] for more information). When pushing upstream from the local branch, push requires no further parameters and hence can be performed without showing another dialog based on the stored upstream configuration. In order to push upstream, right-click on a project and select '''Team > Push to upstream''' or right-click on a Repository in the Repositories View and click '''Push to upstream'''. There is also an action available in the [[#Git_Workbench_Toolbar_and_Git_Workbench_Menu|Git Command Group]].
Push will then be executed immediately after selecting the action. Once finished, a confirmation dialog will be shown displaying information about the pushed data and/or error messages: [[Image:Egit-0.11-PushResultDialog.png]] ===== Configuring upstream push ===== The upstream push can be configured using the "Configure..." button on the confirmation dialog (see above) or by right-clicking a project and selecting '''Team > Remote > Configure push to upstream...'''. A configuration dialog will be shown for configuration of push URIs and corresponding branch mappings (RefSpecs): [[Image:Egit-0.11-ConfigurePushToUpstream.png]] The dialog is divided into three main sections. In the upper part, information about the current Repository and the currently checked out branch is shown. The outer Group shows the Push Configuration for the remote that is associated with the current branch (in our case, "origin" as shown in the Group text). In this specific example, there is a warning message that there are several branches that use the remote named "origin". This means that changes in the push configuration will affect all these branches, not just the branch shown in the Branch field. The URI Group contains two controls, a URI field and a Push URIs list. If the list is empty, the URI in the URI field will be used for Push, if at least one entry is in the Push URIs list, the URIs in the list will be used instead. It should be noted that if the Push URIs list is empty and the URI is changed in this dialog, the new URI will also be used for Pull, so care should be taken when doing so. The RefMapping Group allows specification of one or several RefSpecs (see [[#Refspecs | Refspecs]]) for Push. The "Add" will open a small wizard that helps in the creation of the RefSpecs. You can also paste a RefSpec from the clipboard into the list. Clicking on the "Advanced" control will show/hide an "Edit (Advanced...)" button that allows for more complex RefSpec editing similar to the [[#Push_Wizard|Push Wizard]] below. The buttons in the lower button bar allow you to save your changes and do the push immediately, save the changes without fetching, dry-run (push without saving the configuration), revert your changes, and Cancel. ==== Direct Push ==== Alternatively, you can use [[#Direct_Fetch_and_Push_Support|Direct Push Support]] on a Push Specification of a Remote. ==== Push Wizard ==== The most powerful (but also most complex) way is using the Push Wizard
'''Team > Remote > Push...''' ===== Push URI ===== *If you already configured a Push Specification in the Repositories View you may also select it here using the drop-down list under '''Configured remote repositories'''. The '''Finish''' button will be enabled if the Push Specification for this remote is configured properly (i.e. has at least one URI and a ref spec. *Otherwise click '''Custom URI''' and enter the URI of the upstream repository you want to push to. [[Image:Egit-0.9-push-wizard-destination-page.png]] ===== Push Ref Specifications ===== See also [[#Refspecs|Refspecs]] for more explanations. Click '''Next'''
If this is the first time you connect to this repository via ssh you will have to accept the host key of the remote repository [[Image:Egit-0.9-push-wizard-accept-hostkey.png]] If your ssh key is protected by a passphrase (which is recommended) you have to enter it here [[Image:Egit-0.9-push-wizard-ssh-passphrase.png]] Click '''Add all branches spec''' [[Image:Egit-0.9-push-wizard-refspec-allbranches.png]] This is a convenient way to declare that you want to map your local branch names to the same branch names on the upstream repository you want to push changes to. Click '''Add all tags spec''' to map local tags 1:1 to tags in the repository you want to push to. If you want to map local branches to those in the upstream repository in a different way you may define more detailed mapping specifications in the following way *enter source and destination ref or select already existing branches from the drop-down lists *click '''Add spec''' This will transfer the newly defined mapping to the list '''Specifications for push''' '''Other common push specs:''' *You may e.g. map refs/heads/* to refs/heads/joe/* if you want to name the branches you push to according to your nickname ''joe''. This is useful if multiple users want to publish their local branches on personal branches in a jointly used public repository. *Another usual mapping is to map the source ref HEAD to the destination refs/heads/master. This means you want to map your current HEAD (which might currently point e.g. to any local topic branch) to the upstream master branch. ===== Delete Ref Specifications ===== To delete a ref in the destination repository select the ref to be deleted from the drop-down list '''Remote ref to delete''' and click '''Add spec'''. This will create a corresponding entry in the '''Specifications for push''' list. Alternatively you may type in the specification for the refs to be deleted, this may also use wildcards. Pushing Delete Ref Specifications will delete the matching Refs in the destination repository. [[Image:Egit-0.9-push-wizard-delete-refspec.png]] ===== Conflicting Push Ref Specifications ===== If you add multiple conflicting Push Ref Specifications they will be marked in red, solve this by removing or editing the conflicting specs. It is also possible to edit the specs in-place in the list '''Specifications for push''' [[Image:Egit-0.9-push-wizard-refspec-conflict.png]] ===== Push Confirmation ===== Click '''Next''' This will open the Push Confirmation dialog showing a preview which changes will be pushed to the destination repository. If this does not match your expectation click '''Back''' and correct your push specs accordingly. *For ref updates the range of commits to be pushed will be shown in the format '''<SHA1-from>..<SHA1-to>''' e.g. '''d97f5a2e..adfdbfd2''' means all commits between '''d97f5a2e''' and '''adfdbfd2''' will be pushed. *For refs which do not yet exist in the destination repository '''[new branch]''' or '''[new tag]''' is displayed. *For refs which will be delete '''[deleted]''' is shown. [[Image:Egit-0.9-push-wizard-confirm-push.png]] *Select the '''Push only if remote refs don't change in the mean time''' check box if you want to be sure that what you see in this preview is also what you get when pushing these changes out. *Select the '''Show final report dialog only when it differs from this confirmation report''' check box if you only want to get a report after executing the push if the result differs from this preview. ===== Push Result Report ===== Click '''Finish''' Depending on the options you have chosen a push result report dialog is shown [[Image:Egit-0.9-push-wizard-push-result.png]] In the box at the bottom the push confirmation message from the remote server is displayed. In case of any errors you will find the error message from the remote server here. To see the message for a given list entry simply select it in the list. Click '''Ok''' to close the dialog.
=== Fetching from other Repositories === ==== Fetching from upstream ==== If you are working with a local branch which has a so-called "[[#Upstream_Configuration|Upstream Configuration]]", the most convenient way for fetching relies on this upstream configuration. A local branch is typically created based on a remote tracking branch. Since the remote tracking branch is associated with a remote and this remote contains the information required to access the remote repository, it is possible to automatically create this upstream configuration while creating the local branch (see [[#Branching|Branching]] for more information). When fetching from upstream, this persisted configuration can be used to fetch automatically without the need to provide further parameters in a dialog. In order to fetch from upstream, click '''Team > Fetch from upstream''' on a project or click '''Fetch from upstream''' on a Repository in the Repositories View. There is also an action available in the [[#Git_Workbench_Toolbar_and_Git_Workbench_Menu|Git Command Group]]. Fetch will be executed immediately after selecting the action. Once finished, a confirmation dialog will be shown displaying information about the fetched data and/or error messages: [[Image:Egit-0.11-FetchResultDialog.png]] ===== Configuring upstream fetch ===== The upstream fetch can be configured using the "Configure..." button on the confirmation dialog (see above) or by clicking '''Team > Remote > Configure fetch from upstream...''' on a project. A configuration dialog will be shown for configuring the fetch URI and branch mappings (RefSpecs): [[Image:Egit-0.11-ConfigureFetchFromUpstream.png]] The dialog is divided into three main sections. In the upper part, information about the current Repository and the currently checked out branch is shown. The outer Group shows the Fetch Configuration for the remote that is associated with the current branch (in our case, "origin" as shown in the Group text). The URI field can be used to add/change the fetch URI. The RefMapping Group allows specification of one or several RefSpecs (see [[#Refspecs | Refspecs]]) for Fetch. The "Add" button will open a small wizard that helps in the creation of the RefSpecs. You can also paste a RefSpec from the clipboard into the list. Clicking on the "Advanced" control will show/hide an "Edit (Advanced...)" button that allows for more complex RefSpec editing similar to the [[#Fetch_Wizard|Fetch Wizard]]. The buttons in the lower button bar allow you to save your changes and do the fetch immediately, save the changes without fetching, dry-run (fetch without saving the configuration), revert your changes, and Cancel. ==== Direct Fetch ==== Another way for fetching is to use [[#Direct_Fetch_and_Push_Support|Direct Fetch Support]] on a Fetch Specification of a Remote. ==== Fetch Wizard ==== The most powerful (but also most complex) way is using the Fetch Wizard
'''Team > Fetch...''' * If you already configured a Fetch Specification in the Repositories View you may also select it here using the drop-down list under '''Configured remote repositories'''. The '''Finish''' button will be enabled if the Fetch Specification for this remote is configured properly (i.e. has at least one URI and a ref spec. [[Image:Egit-0.9-fetch-wizard-source-page.png]] * Otherwise click '''Custom URI''' and enter the URI of the upstream repository you want to fetch changes from. [[Image:Egit-0.9-fetch-wizard-source-url-page.png]] ===== Fetch Ref Specifications ===== See also [[#Refspecs | Refspecs]] for more explanations. Click '''Next'''
Click '''Add all branches spec''' [[Image:Egit-0.9-fetch-wizard-refspec.png]] This is a convenient way to declare that you want to map the branch names in the upstream repository you want to fetch changes from 1:1 to the same local branch names. *Click in the edit field '''Destination Ref''' and replace the path segment ''choose_remote_name'' with a symbolic name for the upstream repository you are going to fetch from. *The default remote name for the repository your repository has been cloned from is '''origin'''. The master of this remote maps by default from '''refs/heads/master''' to '''refs/remotes/origin/master'''. *If you e.g. want to additionally track branches from Joe's repository in your local repository you would map the branch in his repository '''refs/heads/*''' to the following tracking branches '''refs/remotes/joe/*'''. *Deselect '''Force Update''' if you want to allow fast-forward updates only, select this option if you also want to allow non-fast-forward changes. *Click '''Force Update all Refs''' to set the force update option on all specs *Click '''Remove all specs''' to remove all specs from the list '''Specifications for fetch''' *Click '''Add all tags spec''' to map tags tags in the repository you want to fetch from 1:1 to local tags. If you want to map branches or tags in the upstream repository to local branches in a different way you may define more detailed mapping specifications in the following way *enter source (ref in source repository) and destination ref (tracking branch or tag in local repository) or select already existing branches from the drop-down lists *click '''Add spec''' This will transfer the newly defined mapping to the list '''Specifications for fetch''' ===== Fetch Result Report ===== Click '''Finish''' [[Image:Egit-0.9-fetch-wizard-result.png]] A fetch result dialog is shown. * For ref updates the range of commits which have been fetched will be shown in the format '''
=== Pulling New Changes from Upstream Branch === * Right-click on a project in the Package Explorer and select '''Team > Pull''' or right-click on a repository in the Git Repositories view and select '''Pull''' to pull new changes from the upstream branch your local branch is tracking. This also works if resources are selected from more than one repository. *Whenever you create a local branch based on a remote tracking branch EGit can configure a tracking relationship so that subsequent pulls will fetch and then merge or rebase (depending on the configuration of this tracking relationship) the changes from the tracked upstream branch; see [[#Branching|Branching]] for details. Ad-hoc selection of the upstream branch to pull from is not yet supported by EGit. Available alternatives include: *run '''git pull''' from outside eclipse (but [http://marc.info/?l=git&m=123924844219075 beware on Windows]) *if you did no local change or want to discard your local changes, use '''Team > Reset...'''
== Working with Gerrit == If you are working with Gerrit (http://code.google.com/p/gerrit/), EGit allows you to conveniently push and fetch changes to and from the Gerrit servers. === Pushing a change to a Gerrit Code Review Server === Right-click on a project and select '''Team > Remote > Push to Gerrit...''' or right-click on a Repository node in the Repositories View and select '''Push to Gerrit...''' A dialog will appear that lets you select or enter a URI and branch name: [[Image:Egit-2.1-pushChangeToGerritDialog.png]] *In the URI combo, select or enter the URI that points to your Gerrit instance; the combo will be pre-filled with all URIs defined in any remote of your current Repository; in addition you can type any URI into this field *In the Gerrit Branch field, enter the name of the Gerrit branch to push to The dialog also offers a content assist for the Gerrit branch. Simply press "Ctrl+Space" to activate this (consult the tooltip that appears when hovering over the little bulb decorator near the Gerrit Branch field). The remote tracking branches for the current repository will be shown. Note that this content assist is filtered, so in order to see all proposals, you need to make sure to have the Gerrit Branch field empty before requesting the content assist. Upon clicking '''Finish''', the currently checked out commit will be pushed to the Gerrit branch specified. Also, the URI and Gerrit Branch values will be remembered and suggested again when the dialog is opened again later. This allows for more flexibility when working with different Gerrit branches in parallel (e.g. frequently switching between development and hotfixing). === Fetching a change from a Gerrit Code Review Server === Right-click on a project and select '''Team > Remote > Fetch from Gerrit...''' or right-click on a Repository node in the Repositories View and select '''Fetch from Gerrit...''' A dialog will appear that lets you select or enter a URI and a change as well as some additional options: [[Image:Egit-0.11-fetchChangeFromGerritDialog.png]] *In the URI combo, select or enter the URI that points to your Gerrit instance; the combo will be pre-filled with all URIs defined in any remote of your current Repository; in addition you can type any URI into this field *In the Change field, you must enter the full name of a change; you can either take this value from the Gerrit Web UI, use the content assist described below, or build the name using the following pattern:
"refs/changes/" + (last two digits from change number) + / + (change number) + / + (revision number) *In the "Actions to perform after fetch" you can decide what to do after the change has been fetched; you can either create and checkout a branch pointing to the change, create and checkout a tag pointing to the change, or simply checkout the change (thus making HEAD detached); the last option does nothing after fetch, but you will be able to find the commit pertaining to the change at FETCH_HEAD (go to the Repositories View and find FETCH_HEAD under the References node of your Repository, see [[#Inspecting_References | Inspecting References ]]).
The name for the branch or tag is suggested by the dialog but can be overwritten as needed.
Since deletion of tags is currently not supported in EGit, we suggest to use local branches rather than tags for the time being. Since the Repositories view allows to group branches hierarchically using "/" as hierarchy separator, the suggested names can come in very handy when dealing with large numbers of changes. Instead of the tedious copy-paste or manual entering of the change ID, the dialog also offers a content assist for the change. Simply press "Ctrl+Space" to activate this (consult the tooltip that appears when hovering over the little bulb decorator near the Change field). The Gerrit Server will be contacted and all available changes will be fetched and shown in a content assist dialog: [[Image:Egit-0.11-ContentAssistGerritChange.png]] The list will be filtered with your input in the change field. After selecting the change in the content assist, the Change field will be filled with the correct information. == Inspecting the state of the Repository == === Label Decorations === Label decorations show Git specific information on resources under Git version control. They appear in all views showing model objects, like Package Explorer, Project Explorer, Navigator, Hierarchy View. The Git label decorations can be switched on globally in the Preference Menu ('''Window > Preferences''') under '''General > Appearance > Label Decorations'''. More detailed settings can be done in the Preferences under '''Team > Git > Label Decorations'''. There are two different types of label decorations: text decorations and icon decorations. ====Text Decorations==== Text decorations appear on the left or right side of the text label. They can be configured on the Preferences dialog under '''Team > Git > Label Decorations''' on the tab '''Text Decorations'''. For example, the default for a dirty resource is a '''>''' on the left side of its name. These are the default settings: [[Image:01-TextDecorations.png]] For files and folders there are the variables "name", "dirty" and "staged". "Dirty" and "staged" are flags; if they are true, the text after the colon is displayed. For projects there are the additional variables "repository" and "branch". The "repository" variable displays the name of the repository. The "branch" variable displays the name of the currently checked out branch. If no branch is checked out, the decoration shows the shortened name of the commit (first seven characters followed by ellipsis). If tags and/or remote branches are pointing to this commit, a "best guess" heuristic is applied to also show this information: tags take precedence over remote branches, if several tags apply, the newest one is displayed; if there are several remote branches or tags have no modification date, then alphabetic sorting is applied and the last one is shown. Example: the checked out commit '''e49f576...''' refers to tag '''v.0.7.1''' of repository '''egit''':
[[Image:03-ExampleDecoration.png]] ==== Icon Decorations ==== Icon decorations appear on the lower right corner of the icon displayed in front of the label. They can be configured on the Preferences dialog under '''Team > Git > Label Decorations''' on the tab '''Icon Decorations'''. These are the default decorations: [[Image:02-IconDecorations.png]] *'''dirty (folder)''' - At least one file below the folder is dirty; that means that it has changes in the working tree that are neither in the index nor in the repository. *'''tracked''' - The resource is known to the Git repository and hence under version control. *'''untracked''' - The resource is not known to the Git repository and will not be version controlled until it is explicitly added. *'''ignored''' - The resource is ignored by the Git team provider. The preference settings under '''Team > Ignored Resources''', "derived" flag and settings from .gitignore files are taken into account. *'''dirty''' - The resource has changes in the working tree that are neither in the index nor in the repository. *'''staged''' - The resource has changes which have been added to the index. Note that adding changes to the index is currently possible only in the commit dialog via the context menu of a resource. *'''partially-staged''' - The resource has changes which are added to the index and additional changes in the working tree that neither reached the index nor have been committed to the repository. See [[#Partial_Staging|partial staging from the Git Staging view]] for how to do that. *'''added''' - The resource has not yet reached any commit in the repository but has been freshly added to the Git repository in order to be tracked in future. *'''removed''' - The resource is staged for removal from the Git repository. *'''conflict''' - A merge conflict exists for the file. *'''assume-valid''' - The resource has the "assume unchanged" flag. This means that Git stops checking the working tree files for possible modifications, so you need to manually unset the bit to tell Git when you change the working tree file. Also see [[#Menu_Actions|Assume unchanged action]]. === Commit Dialog === A summary of the status of all modified tracked files is displayed on the commit dialog. By double clicking a file the changes to be committed will be displayed in a compare dialog. As EGit currently always commits the content of the working tree (corresponding to git commit -a on the command line) the compare dialog will compare the working tree with the last commit.
=== Comparing Content === In daily work you will often want to see the changes between your last commit, the index, and the current working tree. In order to do so, select a Resource (project, folder, or file) in the project explorer or navigator and right-click an action under '''Compare With'''. To analyze the contents of a specific commit you should use the [[#History_View|History View]] which supports this task much better, see task [[#Inspecting_Commits|Inspecting Commits]]. ==== Compare editor and Git Tree Compare View ==== If you use any of the submenu actions of '''Compare With''' on a single file, a compare editor will be shown, otherwise the [[#Git_Tree_Compare_View|Git Tree Compare View]] will be opened that lets you browse the changes; by double-clicking on a changed file in this view, a compare editor will be opened for this file. An exception is the submenu action '''History...''', which opens the History View. ==== Compare working tree with last commit ==== The difference between a resource in the current working directory and in the last commit in the current branch can be viewed from the context menu '''Compare With > HEAD revision'''. This feature is also available in the Commit dialog. Double clicking on an entry in the Commit dialog opens a compare dialog. ==== Comparing Working Tree with Index ==== The differences between the current working tree and the index (based on the currently selected resource) can be viewed from the context menu '''Compare With > Git Index'''. ==== Comparing Working Tree with a branch, a tag or a reference ==== *Select a resource *right-click '''Compare With > Branch, Tag, or Reference...''' *select a branch, tag or reference ==== Comparing Working Tree with Any Commit ==== ===== From the project explorer: ===== *Select a resource *right-click '''Compare With > Commit...''' *select a commit from the commit graph ===== From the history view (files only): ===== *Select a file in the package explorer *right-click '''Team > Show in History''' or '''Compare With > History...''' *in the commit graph select a commit *from the context menu select '''Compare with working tree''' *this will open a compare dialog showing the changes between the selected commit and the current working tree ==== Comparing Two Commits ==== *Select a resource in the Package Explorer *click '''Team > Show in History''' or '''Compare With > History...''' (the latter for files only) *in the commit graph select two commits *right-click '''Compare with each other''' *this will open a compare dialog showing the changes between the two selected commits *you can also open a Git Tree Compare view by right-clicking '''Compare with each other in Tree''' ==== Comparing Index with HEAD or Any Other Commit ==== This feature is not implemented yet.
=== Comparing with Branches (Synchronize) === The difference between the working tree (including not committed changes) and a branch or tag can be viewed by clicking the dynamic menu '''Team > Synchronize''' on a project and selecting the ''Ref'' you want to synchronize your working tree against. If the Git repository contains multiple Eclipse projects it is sufficient to select one project, the '''Synchronization View''' will also include all other projects. [[Image:Egit-1.0-synchronize-dynamic.png]] If you want to synchronize with a Ref not listed in the dynamic menu click '''Team > Synchronize > Other...'''. Then in the Synchronize Wizard click into the destination column of the repository you want to synchronize and select the Ref you want to compare against. [[Image:Egit-1.0-synchronize-custom.png]] When clicking "Include local uncommitted changes in comparison" also local, not yet staged changes and the already staged changes will be shown in comparison. It is also possible to compare multiple repositories at once. In this case in the Synchronize Wizard select for each repository the Ref you want to compare against. === Quickdiff === Instead of using a compare editor you can enable quick diff support and see the changes within the text editor.
This feature can be enabled via the '''General > Editors > Text Editors > Quick Diff''' preference page: [[Image:04-QuickDiffPreferences.png]] The difference annotation will then be displayed on the left hand side of the editor: [[Image:05-QuickDiffInEditor.png]] If you move your mouse over the annotation you see the content of the version you are comparing to: [[Image:06-QuickDiffInEditorPopup.png]] Per default, the comparison is against the HEAD. You can determine the version you are comparing to, the so-called quickdiff baseline, from the context menu of a commit in the history view ('''Show in > History'''). There are three menu entries: *'''Quick Diff -> Reset baseline to first parent of HEAD''' - Compare against the first commit before HEAD. *'''Quick Diff -> Reset baseline to HEAD''' - Compare against HEAD. *'''Quick Diff -> Set as baseline''' - Compare against the selected commit
=== Inspecting Commits === To inspect a given commit *from the context menu in package explorer select '''Team > Show in History''' *select the commit you want to inspect [[Image:EGit-0.7-ViewDiffInResourceHistory.png]] ==== View Diff for a Commit ==== The history view displays the diff in the lower left pane. Selecting a file in the lower right pane scrolls to the corresponding file section of the diff. ==== Showing the contents of a Commit ==== The behavior of a double click on a file in the lower right pane depends on the state of the compare mode toggle button. If it's on, a compare editor will be opened which compares the file content in the current commit with the content in the ancestor commit; if it's off, an editor will be opened showing the file content in the current commit. == Committing Changes == Modifications to a project under git version control are persisted in the git history through commits. Starting from the state checked out from the git repository modify your project until you have reached a state you are satisfied with and then commit all these changes into the repository as one single commit. Each commit represents a well defined snapshot of all the files stored in the repository. === Modifying the content === To modify a project which is already shared with Git modify or delete files either within Eclipse or directly in the file system. There is no need to tell Git in advance about these operations. New files which should be version-controlled have to be explicitly put under Git version control : * click '''Team > Add''' in the file's context menu Alternatively you may display untracked files in the Commit dialog and check the '''Show untracked Files''' checkbox to select them for inclusion into the commit. Label decorators e.g. in the Package Explorer View show * untracked files which are not yet under git version control (marked with "?") * files which have been added (marked with "+") * modified files (marked with ">" in front of the filename) For details see [[#Label_Decorations|Label Decorations]]. Here is an example in the Package Explorer for * a committed file * a file modified in the working tree but not yet staged for the next commit * a modified file which modifications have been staged for the next commit * a file which has been newly staged for first-time inclusion with the next commit * a file which is not under git version control [[Image:Egit-0.9-label-decorators.png]] === Committing === To commit a change click '''Team > Commit...''' in the context menu of a resource in the project. Git tracks all changes made to the entire repository capturing the modifications of all version-controlled files in that repository not regarding if these files reside in the same Eclipse project or not. Once you have triggered the commit the '''Commit Dialog''' will pop-up [[Image:Egit-0.9-commit-dialog.png]] Select the changes you want to commit, enter the commit message and to create the commit, press '''Ctrl+Enter''' ('''Command+Enter''' on Mac OS X) in the commit message text field, or click '''Commit'''. ==== Commit Message ==== In the Commit Dialog you specify the commit message describing the change. It is good practice to start the message with a short first line summarizing the change followed by a blank line and then the message body. In order to ensure that also git command line tools can format these messages nicely the lines shouldn't be formatted too wide (this is indicated by a grey vertical line). [[Image:Egit-0.9-commit-dialog-spell-quickfix.png]] The commit message text is checked for errors by the Eclipse spell checker. The spell checker can be configured via the Eclipse '''Preferences > General > Editors > Text Editors > Spelling'''. Press '''Ctrl+1''' to open quick fixes which may help to fix the spelling errors. [[Image:Egit-1.2-commit-dialog-path-assist.png]] The commit message editor supports content assist for file names shown in Files section of the commit dialog, which can be activated pressing Ctrl-Space. '''Footer Tags'''
In the last paragraph of the commit message optional footer tags may follow :
Bug: 3176 Change-Id: I267b97ecccb5251cec54cec90207e075ab50503e Reported-by: Joe DeveloperThe semantics of these tags are project or tool specific * If there is an entry in a bug tracking system for the change to be committed it is a good idea to add it here as a bug tag * [http://code.google.com/p/gerrit/ Gerrit Code Review] uses the ''Change-Id:'' footer to correlate different patchsets of a change evolving during the review process towards the finally accepted patch. To generate a Gerrit Change-Id click '''Compute Change-Id for Gerrit Code Review'''; the ID will be generated on commit, until then a null Change-Id is shown as a placeholder. With the egit configuration parameter '''gerrit.createchangeid''' set to true the corresponding checkbox in the Commit Dialog is always preselected. This parameter can be set on repository level, on system level or on user level. See [http://wiki.eclipse.org/EGit/User_Guide#Repository_Configuration Repository Configuration] for more information. * The ''Signed-off-by:'' footer is used by many projects to create a formal track record of declarations that the signing author contributed the changes under the project's license and IP rules. This way the IP provenance of a project's evolving code base can be captured on a technical level. See e.g. the [http://elinux.org/Developer_Certificate_Of_Origin Developer Certificate Of Origin] used by the Linux kernel project. If the egit preference '''Insert Signed-off-by''' in '''Team > Git > Commit Dialog''' is set the corresponding checkbox in the Commit Dialog is always preselected. Additionally this dialog controls which of the changes will be included in the commit. If you clear the checkbox in front of a file, the changes to this file will not be included in the commit. The local file in your eclipse workspace will still contain the modifications giving you the chance to commit these changes with a subsequent commit. This feature is often used to separate modifications done to a set of files into different commits. '''One example:''' Imagine since the last commit you have fixed a bug in A.java and you have added a new method to B.java. These two modifications are logically independent from each other hence you may want to commit them in two independent commits. In this case you initate the commit, deselect B.java from the set of committed files and specify a commit message describing only the bugfix in A.java. After a successful first commit you just call commit again and the upcoming dialog will present you the remaining changes in B.java. Now you specify a commit message describing the addition of the method and finish the second commit. New files you added to the project which have not been explicitly added to version control (see "Modifying the content") will be listed in the commit dialog if you select the checkbox "Show untracked Files". If you select the checkbox in front of these files in the list they will be added to the repository and committed once you press the commit button. Files which are excluded by the team ignore list or a .gitignore file or which are derived (e.g. the bin folder in java projects) will not be shown here. If you have no other changes in your repository than such untracked files the checkbox '''Show untracked Files''' is selected by default. ==== Amending Commits ==== If you recognize that you missed something when committing a change you may fix this: open the commit dialog again and specify that the current commit shall "amend" the previous commit in the current branch. The new commit will then replace the previous one. This feature is often used to correct incorrect commits before they are published to other repositories. '''Note:''' do not amend commits if they have already been published to a shared repository since this may disturb others if they already based their changes on the published change. '''Amend example:'''
Signed-off-by: William Shakespeare
branch.autosetuprebase, set it to
alwaysif you want to use the rebase pull strategy by default. If you set this in the repository configuration this is used for all local branches created based on a remote tracking branch in this repository, if you set it in your user configuration it will be used for all your repositories. In the lower part, you can decide whether the new branch shall be checked out immediately. == Merging == A merge incorporates changes from named commits (since the time their histories diverged from the current branch) into the current branch. === Merging a branch or a tag into the current branch === You have two places where you can trigger the merge: * from the team menu * from the Git Repositories View ==== Starting merge from the team menu ==== In the Package Explorer or Navigator, open the context menu on a project node. Select '''Team > Merge...''' Now the merge dialog opens: [[Image:MergeDialog.png]] On the dialog, select a branch or a tag you want to merge with your current branch. ==== Starting merge from the Git Repositories View ==== You can trigger a merge from any branch and tag node and from the repository node if you have checked out a local branch. See [[#Merging_a_Branch_or_a_Tag|Merging a Branch or a Tag]] for further details. ==== Possible merge results ==== After pressing the Merge button, the following scenarios can occur: * ''Already up to date'': Your current branch points to a commit that has the selected branch or tag as predecessor. In this case nothing is changed. * ''Fast-forward'': Your current branch points to a commit that is a predecessor of the selected branch or tag. In this case your branch is moved and points to the selected branch or tag; this new HEAD is checked out to the working tree. Fast-forward is very common when working with remote repositories: When a remote tracking branch is updated, the merge with the corresponding branch generally is a fast-forward. You can perform a pull by fetching the remote branch (e.g. origin/master) and merging it into the corresponding local branch (e.g. master). * ''Real merge'': When neither of the conditions above apply egit triggers a merge of the commits. There are two possible outcomes: If no conflicts occur the current branch will point to a newly created merge commit; if conflicts occur the conflicting files will be marked with label decorators (see [[#Resolving_a_merge_conflict|Resolving a merge conflict]] for further actions in case of merge conflicts). ===== Merge Result dialog ===== The result of a merge is summarized in a dialog: [[Image:MergeResultMerged.png]] On the first line you see the result of the merge. The possible results are "Already-up-to-date", "Fast-forward", "Merged", "Conflicting" or "Failed". A possible reason for "Failed" may be that there are conflicting changes in the working directory. On the second line you see the new HEAD commit in case of a successful merge (Already-up-to-date, Fast-forward or Merged). In the table you see the commits which were merged. === Resolving a merge conflict === A merge can result in conflicts which require user action. This is the case when the content of files cannot be merged automatically. These conflicts are marked with a label decoration in the navigation tree. The merge conflicts in the content of files are presented with textual conflict markers (see http://www.kernel.org/pub/software/scm/git/docs/git-merge.html#_how_conflicts_are_presented for more details). [[Image:Egit-0.10-merge-conflict.png]] ==== Using Merge Tool ==== * select the top level resource showing the red conflict label decorator * click '''Team > Merge Tool''' * select the merge mode ''Use HEAD (the last local version) of conflicting files'' and click '''OK''' [[Image:Egit-0.10-select-merge-mode.png]] * the merge editor opens showing the working tree version in the left pane and the version to be merged in the right pane [[Image:Egit-0.10-merge-tool.png]] * edit the working tree version until you are happy with it * '''Team > Add''' the merged resource to mark the conflict as resolved * commit the merge commit via '''Team > Commit''' ==== Manual conflict resolution ==== To resolve a conflict you have to do the following steps: * Navigate to the conflicting resource * Edit the content of the conflicting resource * Tell EGit that the conflict is resolved with '''Team > Add''' * Commit the conflict resolution with '''Team > Commit''' ==== Finding conflicting files ==== A repository which contains conflicting files has the textual label decorator "|Conflicts" attached to the repository name. Conflicting resources and folders containing such conflicting resources get a conflict label decoration. [[Image:Conflicts.png]] ==== Editing conflicting files ==== In the file content, the area where a pair of conflicting changes happened is marked with markers <<<<<<<, =======, and >>>>>>>. The part before the ======= is typically your side, and the part afterwards is typically their side (see http://www.kernel.org/pub/software/scm/git/docs/git-merge.html#_how_conflicts_are_presented for more details). Open the file in an editor, edit the content and save the editor. Note that this step is not mandatory. EGit does not check the content to decide if a conflict is resolved. The next step is the relevant one. ==== Adding conflict resolution to the git index ==== Once you are finished with editing a file select '''Team > Add''' to add the conflict resolution to the git index. You can do it on a folder or the whole project to resolve all conflicts at once. When you have resolved all conflicts the textual repository label decoration changes to "Merged". There are no conflict markers anymore. [[Image:ResolvedConflicts.png]] ==== Committing a merge ==== When the repository is in state "Merged" (as is indicated with the textual label decorator "|Conflicts" attached to the repository name) the merge can finally be committed. Select '''Team > Commit...''' anywhere in the navigation tree. The commit dialog opens with a slightly different look compared to a normal commit: * The Commit message area is prefilled with a standard merge commit message. * It is not possible to amend a previous commit. * It is not possible to add untracked files. * it is not possible to uncheck the checkboxes. This guarantees that all resolved conflicts are committed. After pressing the "Commit" Button the merge is completed. === Aborting Merge === If a merge resulted in conflicts you can abort the merge with a hard reset to the current branch. This can be done in state "Conflicts" and in state "Merged", i.e. before and after you have resolved the conflicts. The hard reset can be done from the team menu, the Git Repositories View or the History View. See [[#Revert_all_local_and_staged_changes|Revert all local and staged changes]] for more details.
A topic / D---E masterNow, let's assume that there were some more commits on "topic" and as well some more commits on "master" (for example, "master" may track some remote repository and there were some changes in that remote repository that have been pulled into "master"):
A---B---C topic / D---E---F---G masterNow, in order to incorporate the changes in "master" into "topic", a Rebase of "topic" onto "master" would produce
A'--B'--C' topic / D---E---F---G master
Chapter 1 Once upon a time... Chapter 2 To be or not to beNow, in "topic", two commits are created, the first one adding a French translation to Chapter 2, and another one adding a German translation: After first change in "topic":
Chapter 1 Once upon a time... Chapter 2 To be or not to be Être ou ne pas êtreAfter second change in "topic":
Chapter 1 Once upon a time... Chapter 2 To be or not to be Être ou ne pas être Sein oder nicht seinAt the same time, the file was changed in "master" by adding two commits adding French and German translations to Chapter 1:
Chapter 1 Once upon a time... Il était une fois Es war einmal Chapter 2 To be or not to beThe commit history looks like this: [[Image:EGit-0.10-MergeDemoHistory.png]] Now, if "topic" is rebased onto "master", the two changes in topic are applied in the same sequence as they were applied during the evolution of "topic". The result is a merged version of "FamousWords.txt":
Chapter 1 Once upon a time... Il était une fois Es war einmal Chapter 2 To be or not to be Être ou ne pas être Sein oder nicht seinand a commit history with the commit history of "topic" on top of the current "master":
A'--C' topic / D---E---F---G master=== Starting Rebase === Rebase is available in the Git Repositories View. On Repository nodes, '''Rebase...''' opens a dialog asking the user to select a branch that is not checked out; the currently checked out branch will then be rebased onto the selected branch. On "Branch" nodes (both Local and Remote Tracking branches, but not on the currently checked out branch), '''Rebase''' immediately rebases the currently checked out branch onto the selected branch: [[Image:EGit-0.10-StartRebaseFromRepoView.png]] === Rebase Confirmation Dialog === If Rebase was successful, a confirmation dialog will be displayed; this dialog can be suppressed by ticking a checkbox; a preference on the Git preference page allows to make the dialogs appear again. If the dialog is suppressed, an "Information" message is written to the Eclipse log instead. === Rebase Conflicts === If a conflict occurs during rebase, a dialog is shown giving some information about the commit that caused the conflict. By selecting a radio button, you can decide whether to *Start the Merge Tool to resolve the conflicts manually *Skip the current commit *Abort the rebase altogether *Do nothing (return to the workbench), this is equivalent to hitting "Escape": [[Image:EGit-0.10-RebaseConflictDialog.png]] Unless "Skip" or "Abort" was chosen in the dialog, the conflicts must be resolved manually by editing the conflicting files. When done with editing, the files must be declared as being resolved by "Adding" them to the index. After all conflicts have been resolved, Rebase can be resumed by right-clicking on the Repository node in the Git Repositories View and selecting Rebase > Continue. The "Skip" and "Abort" options are also available from the Git Repositories View by right-clicking on the Repository node and selecting Rebase > Skip and Rebase > Abort, respectively. The Merge Tool can also be started from the corresponding entry in the Team menu. === Aborting Rebase === As long as the Repository is in "Rebasing" state, the user can always abort the rebase in the Git Repositories View using the menu action "Rebase > Abort" which is available on the Repository node. === Rebase Limitation === The current EGit rebase implementation is not yet able to handle all possible version graphs. If the graph is too complicated rebase will abort with an error message. As a workaround until these more complex graphs are also supported by EGit's rebase you may instead use native git from the command line. == Cherry Picking == === Cherry-pick Introduction === A given commit ''C'' on branch ''stable-1.0'' contains a set of changes you would like to integrate in your current development on branch ''master''.
A--B--C--D stable-1.0 / D---E---F---G master HEADCherry-pick the commit ''C'' to create a new commit ''C' '' on top of the head commit of the currently checked out branch ''master''. ''C' '' will then contain the changes performed in ''C'' applied onto the HEAD of the currently checked out branch ''master''.
A--B--C--D stable-1.0 / D---E---F---G--C' master HEAD=== Cherry-pick Example === You are currently working on branch "feature2" (HEAD). There is a commit "feature 1" in another branch.
.gitfolder) to the clipboard, then open the context menu on the view panel: [[Image:RepoMgrPasteRepositoryPath.png]] or click '''Edit > Paste''' from the main menu (or the corresponding keyboard shortcut). If the clipboard content is not suitable, an error popup will be displayed, otherwise the added Repository should appear automatically. After the view has been populated with some repositories, it should look like this: [[Image:RepoMgrViewWithRepos.png]] === Removing Repositories === ==== Removing a Repository from the Repositories View ==== In order to remove a repository from the Repositories View select a repository and click "Remove Repository" [[Image:Egit-0.10-RemoveRepository.png]] ==== Deleting a Repository ==== In order to delete a repository, select it in the Repositories View and click "Delete Repository". [[Image:Egit-0.10-DeleteRepository.png]] Then confirm that you want to delete the repository [[Image:Egit-0.10-ConfirmRepositoryDeletion.png]] and decide if you want to delete projects contained in the repository from the Eclipse workspace. [[Image:Egit-0.10-ConfirmProjectRemoval.png]]
The values are separated by commas and have the following meaning: # Format version # Git repository URL # Name of branch to initially check out # Path to the project to import (folder which contains .project), relative to the repository Each project has one entry. So for multiple projects in the same repository, create such an entry for each project with the same repository URL. The import is smart enough to only clone each repository once. If the repository contains a project at the root, use . as the project path. = Reference = == Menus == === Project Context Menu === On project nodes in navigation views (Navigator, Package Explorer etc.) the following Git actions are available for projects shared with the Git team provider:
git statusshowing changes made in the working tree. Unstaged changes which have not yet been transferred to the git index are displayed in the '''Unstaged Changes''' pane, changes which have already been "added" (staged) to the Git index are shown in the '''Staged Changes''' pane. By default these panes are displayed in a row layout, which can be changed to a column layout by the '''Column Layout''' option. The Staged- and Unstaged Changes panes by default show the full path of the files. They can be configured by the '''Show File Names First''' option to show the file names first, followed by the directory that the files are located in. Double-click modified files to open a compare view. If fired from the "unstaged" pane the compare view will show the not-yet staged changes. When fired from the "staged" pane it will display the already staged changes. To open a file in the editor, use the '''Open Workspace Version''' action on the file's context menu. To stage a file, drag it from the '''Unstaged Changes''' pane to the '''Staged Pages''' pane. Alternatively, use the '''Add to Git Index''' action on the file's context menu in the '''Unstaged Changes''' pane. The '''Replace with File in Git Index''' action will replace the selected file in the working tree. If the file is unstaged, it will be reset. If it is staged, the working tree version will be replaced with the staged version from the Git index. To unstage a file, drag it from the '''Staged Changes''' pane to the '''Unstaged Changes''' pane. Alternatively, use the '''Remove from Git Index''' action on the file's context menu. The commit action will commit the staged changes only -- similar to what
git commitdoes in native git. An integrated commit message editor allows to edit the commit message for the commit. In contrast to the commit dialog, the staging view can be kept open while doing changes. This allows for incrementally writing the commit message along with the changes. The commit message being edited is associated with the repository, the staging view is linked with. It is not stored persistently and will get lost if the staging view or Eclipse are closed. To commit, press '''Ctrl+Enter''' ('''Command+Enter''' on Mac OS X) in the commit message text field, or click on the '''Commit'' or '''Commit and Push''' button. ==== Partial Staging ==== Sometimes it's useful to commit only some changes of a file. An example is when working on a feature and noticing a typo or small bug, which is unrelated to the feature. To commit only certain changes, these changes have to be staged first. To do this, double-click on the file in the '''Unstaged Changes''' pane. This will open the compare editor. On the left side is the workspace version, on the right is the index (staged) version. Both sides of the compare editor are editable. When changing something in the right side (index) and saving, the file will turn up in the '''Staged Changes''' pane and when committing, exactly that content will be committed. To stage a group of changed lines, the '''Copy Current Change from Left to Right''' toolbar button (arrow icon) can be used. === Git Reflog View === [[Image:Egit-1.2-reflog-view.png]] The Reflog View shows the Git reflog for a selected repository. It supports showing the reflog for a specific branch by selecting the hyperlink ref name in the top right of the view. Double-clicking or selecting the context menu action '''Open in Commit Viewer''' on a reflog entry opens the corresponding commit in the commit viewer. The context menu action '''Checkout''' will checkout the selected commit and the [[#.22Detached.22_HEAD|HEAD will become detached]]. == Git URLs == Git URLs in general consist of transport protocol scheme, address of the remote server and the repository path within the remote server and for some authenticating protocols also the user ID. EGit supports the following protocols *'''file''' - Direct file system access to the repository. *'''git''' - The most efficient built-in git protocol (default port 9418). This protocol doesn't provide authentication. Typically used for anonymous read access to the repository. *'''ssh''' - Git over [http://tools.ietf.org/html/rfc4251 secure shell (SSH)] protocol. Typically used for authenticated write access to the repository. *'''http''' - [http://tools.ietf.org/html/rfc2616 Hypertext Transfer Protocol] can be tunneled through firewalls. *'''https''' - [http://tools.ietf.org/html/rfc2818 Hypertext Transfer Protocol Secure] can be tunneled through firewalls. *'''ftp''' - [http://tools.ietf.org/html/rfc959 File Transfer Protocol] *'''sftp''' - [http://en.wikipedia.org/wiki/SSH_File_Transfer_Protocol SSH File Transfer Protocol] Git URLs are used when * [[#Cloning_Remote_Repositories | cloning repositories]] * [[#Fetching_from_other_Repositories | fetching]] changes from another repository * [[#Pushing_to_other_Repositories | pushing]] changes to another repository
HEAD:refs/heads/masterThis means that the currently checked out branch (as signified by the HEAD Reference, see [[#Git_References|Git References]]) will be pushed into the master branch of the remote repository. === Fetch Refspecs === A typical example for a Fetch RefSpec could be
refs/heads/*:refs/remotes/origin/*This means that all branches from the remote repository will be fetched into the corresponding remote tracking branches of the local repository. == Remotes == Remotes are used to manage the repositories ("remotes") whose branches you track from your repository. In EGit Remotes are defined when * [[#Cloning_Remote_Repositories | Cloning a repository]] from another repository, by convention this repository the newly cloned one has been created from is named "origin". If you prefer a different name the clone wizard allows to specify that. * [[#Remote_Repositories | Defining Remotes in the Repositories View]] A Remote first of all defines a '''name''' for the repository whose branches you track, this is important since you may want to track branches from different repositories so the name helps to understand what repository a certain operation is dealing with. In addition [[#Refspecs | Refspecs]] specified for a given Remote define a '''mapping of branches and tags''' in your local repository to branches and tags in the remote repository. You may want to use different mappings for inbound or outbound transport operations hence there are [[#Cloning_Remote_Repositories | editors]] to define Fetch and Push Configurations available in EGit. == Git Ignore ==
.gitignorefiles located in the working tree specify files that intentionally should not be tracked by git. They only concern files that are not yet tracked by git. In order to ignore uncommitted changes in already tracked files refer to the [[#Menu_Actions | assume unchanged action]]. Each line in
.gitignorefiles defines a pattern. Git checks ignore patterns following the hierarchy of the working tree from highest to lowest. Patterns defined in higher level
.gitignorefiles are overridden by those defined in lower levels. Files which shall be ignored for all working on a given project are usually included in the project's repository to easily share them in the team. Pattern format definition: * blank lines are ignored * lines starting with '''#''' serve as comments * the optional prefix '''!''' negates the pattern. Files excluded by a matching previous pattern become included again. Patterns ending with a slash only match directories but not files or symbolic links. * patterns not containing a slash are treated as shell glob patterns matched against the path relative to the location of the .gitignore file * git treats patterns as shell globs as defined in [http://www.kernel.org/doc/man-pages/online/pages/man3/fnmatch.3.html fnmatch(3)] * wildcards in patterns do not match '''/''' in path names * a leading slash matches the beginning of a pathname The EGit '''Ignore''' [[#Menu_Actions | menu action]] adds the selected resource to the
.gitignorefile in the resource's parent directory. To enter other ignore patterns use a text editor. '''Note:''' EGit does not yet respect
.gitignorefiles outside Eclipse projects, so if you have a repository containing multiple projects you should add a
.gitignorefile for each project instead of a single one in the root directory. == Git Fetch Factory for PDE Build == As part of EGit's PDE Tools, there's a PDE Build fetch factory for Git included in the '''org.eclipse.egit.fetchfactory''' plug-in. The map file's file format: '''type@id,[version]=GIT,args''' Where '''args''' is a comma-separated list of key-value pairs. Accepted '''args''' include: * '''tag*''' - mandatory Git tag * '''repo*''' - mandatory repo location * path - optional path relative to repo which points to the element (otherwise it's assumed that the element is at the repository root) * prebuilt - optional boolean value indicating that the path points to a pre-built bundle in the repository Fetching is implemented as a three-step process: * The repository is cloned to local disc. If it already exists, it is assumed that it was previously cloned and just new commits will be fetched * The specified tag will be checked out in the local clone * The content of the path will be copied to the final build location