Jump to: navigation, search

Difference between revisions of "EGit/User Guide/Commit"

(Modifying the content)
(Signing off commits)
 
(One intermediate revision by one other user not shown)
Line 1: Line 1:
 
== Committing changes ==
 
== Committing changes ==
  
Modifications to a project which is version-controlled with git are done through commits. In git you modify your project until you have reached a state you are satisfied with and then you commit all these changes together to the repository in one single commit.
+
Modifications to a project which is version-controlled with Git are persistently recorded in the history through commits. In Git you modify your project until you have reached a state you are satisfied with and then you commit all these changes together to the repository in one single commit.
 
   
 
   
 
=== Modifying the content ===
 
=== Modifying the content ===
  
If you have a project which is already shared with git then doing the actual modifications is easy: just modify or delete files either with eclipse or even directly on the file-system. There is no need "check-out" files or to tell git in advance about these operations. Only when you add new files you should be cautious: new files which should be version-controlled have to be explicitly announced to git through the files context-menu.
+
If you have a project which is already shared with Git then doing the actual modifications is easy: just modify or delete files either within Eclipse or even directly on the file-system. There is no need to "check-out" files or to tell Git in advance about these operations. Only when you add new files you should be cautious: new files which should be version-controlled have to be explicitly announced to git through the files context-menu.
  
 
[[Image:EGit_AddFile.png]]
 
[[Image:EGit_AddFile.png]]
  
You can see in for example int the Package Explorer View which files have been added (the icon for this file contains a "+") and which files have been modified (there is a ">" in front of the filename. Here is an example of one added and one modified file in the Package Explorer:
+
You can see for example in the Package Explorer View which files have been added (file icon marked with "+") and which files have been modified (file marked with ">" in front of the filename). Here is an example of one added and one modified file in the Package Explorer:
  
 
[[Image:EGit_AddedAndModifiedFiles.png]]
 
[[Image:EGit_AddedAndModifiedFiles.png]]
Line 15: Line 15:
 
=== Committing ===
 
=== Committing ===
  
When you are satisfied with the state of the project you may commit your recent changes. To do that select "Team -> Commit..." from the context menu of a project or a file in the project.  
+
When you are satisfied with the state of the project you may commit your changes. To do that select "Team -> Commit..." from the context menu of a project or a file in the project.  
  
 
[[Image:EGit_Commit.png]]
 
[[Image:EGit_Commit.png]]
  
It does not play a role whether you select this action on a certain file on on the whole project. The reason for this is the following: in git you never commit individual changes to a certain file. Instead you always commit a new state of the whole git repository capturing the state of each and every version-controlled file in that repository. There is no commit on a certain file or even on a certain project. A commit will capture all eclipse projects which are configured to be version controlled in the same git repository as the project on which you initially triggerd the commit.  
+
It does not play a role whether you select this action on a certain file or on the whole project. The reason for this is that Git tracks all changes made to the whole repository capturing the modifications of each and every version-controlled file in that repository not regarding if these files reside in the same Eclipse project or not.  
  
Once you have triggerd the commit the following dialog will pop-up.
+
Once you have triggered the commit the following dialog will pop-up.
  
 
[[Image:EGit_CommitDialog.png]]
 
[[Image:EGit_CommitDialog.png]]
  
In this dialog you specifiy the commit-message. This text may describe for example what you have changed and why you did it.
+
In this dialog you specifiy the commit message describing the change.
  
Additionally can control in this dialog which of the touched files will be included in the commit. If you clear the checkbox in front of a file, the changes to the 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 seperate the modifications you did to a set of files into different commits.   
+
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. This two modifications are independent from each other and you may regret that you have not committed directly after you have fixed the bug in A.java. 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 succesfull first commit you just call commit again and the upcoming dialog will present you the remaining changes in B.java. Now you can specify a commit message for the addition of the method and finish the commit.
+
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 independant 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 succesfull 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.
  
Be aware that new files which you added to the project and which you have not explicitly added to version control (see "Modifying the content") will not be listed in the commit dialog and will not be part of the commit. If you are not sure whether you have created such files you may select "Team -> Add to Version Control" on an eclipse project to add new files in the project to version control.
+
Be aware that new files you added to the project which have not been explicitly added to version control (see "Modifying the content") will not be listed in the commit dialog and will not be part of the commit. If you are not sure whether you have created such files you may select "Team -> Add to Version Control" on an Eclipse project to add new files in the project to version control.
  
 
==== Ammending Commits ====
 
==== Ammending Commits ====
  
When you commit you may specify that the current commit should "amend" the previous commit in the current branch. Your commit will then replace the previous commit. This feature is often use to correct wrong commits.
+
When you commit you may specify that the current commit should "amend" the previous commit in the current branch. Your commit will then replace the previous commit. This feature is often use to correct wrong commits before they are published to other repositories.
  
Example: Imagine you have committed a change to a file and after the commit you find out that the file contained a typo.
+
Example: Imagine you have committed a change to a file containing a typo  
  
 
[[Image:EGit_Typo.png]]
 
[[Image:EGit_Typo.png]]
  
After you commited you detect the typo. In order to correct this typo and to get rid of the wrong commit you just fix the typo in the source file.
+
After you committed you detect the typo. In order to correct this typo and the corresponding commit you just fix the typo in the source file
  
 
[[Image:EGit_Corrected.png]]
 
[[Image:EGit_Corrected.png]]
Line 49: Line 49:
 
[[Image:EGit_AmendBringsOldCommitMessage.png]]
 
[[Image:EGit_AmendBringsOldCommitMessage.png]]
  
When you do so the commit message of your previous commit (the one which you want to replace) is filled into the "Commit Message" field. This gives you the chance not only to correct errors in the content of the version-controlled files but to also correct errors (e.g. typos) you did in the commit message.
+
The commit message of your previous commit (the one which you want to replace) is filled into the "Commit Message" field. This gives you the chance not only to correct errors in the content of the version-controlled files but to also correct errors (e.g. typos) in the commit message describing your change.
  
As an alternative to amending previous commits you could just commit the corrected version as a subsequent commit. But the first commit containing the typo is of no use to anybody else and in order not to clutter the history of your project with unneeded commits you may decide to use the amend feature.
+
As an alternative to amending you could just commit the corrected version as a subsequent commit. But the first commit containing the typo is of no use to anybody else and in order not to clutter the history of your project with unneeded commits you may decide to use the amend feature.
  
Be aware that ammending commits which already visible in other repositories may cause trouble. Once you have pushed a commit to a remote repository or once your local repository was cloned by a somebody else you should be very careful whith amending commits. Simply publishing a second commit which corrects the first one is in the case probably a better solution.
+
Be aware that amending commits which are already published to other repositories may cause trouble. Once you have pushed a commit to a remote repository or your local repository was cloned by somebody else you should be very careful whith amending commits. In this case publishing a second commit which corrects the first one is probably a better solution.
  
 
==== Signing off commits ====
 
==== Signing off commits ====
  
Git gives you the chance to "sign off" commits. This adds a "Signed off by <Your Name and Email-Adress>" line to the commit message.
+
Git gives you the chance to "sign off" commits. This adds a "Signed-off-by: <Your Name and Email-Adress>" footer to the commit message.
The purpose of this signed-off-by information is not defined by git but by the team which uses git. Some teams use this information to record who has reviewed a certain commit. Other teams use the signed-off information to record that a commiter agreed to certain standards/rules. E.g. you may have to sign-off your own commits to state that you have read and understood the license-specific rules of your project.
+
The purpose of this signed-off-by information is not defined by Git but by the team using Git. Some teams use this information to record who has reviewed a certain commit. Other teams use the signed-off information to record that a commiter agreed to certain standards/rules. E.g. you may have to sign-off your own commits to state that you have read and understood the license-specific rules of your project.
 +
 
 +
[[Category:Draft Documentation]]

Latest revision as of 14:41, 2 November 2009

Committing changes

Modifications to a project which is version-controlled with Git are persistently recorded in the history through commits. In Git you modify your project until you have reached a state you are satisfied with and then you commit all these changes together to the repository in one single commit.

Modifying the content

If you have a project which is already shared with Git then doing the actual modifications is easy: just modify or delete files either within Eclipse or even directly on the file-system. There is no need to "check-out" files or to tell Git in advance about these operations. Only when you add new files you should be cautious: new files which should be version-controlled have to be explicitly announced to git through the files context-menu.

EGit AddFile.png

You can see for example in the Package Explorer View which files have been added (file icon marked with "+") and which files have been modified (file marked with ">" in front of the filename). Here is an example of one added and one modified file in the Package Explorer:

EGit AddedAndModifiedFiles.png

Committing

When you are satisfied with the state of the project you may commit your changes. To do that select "Team -> Commit..." from the context menu of a project or a file in the project.

EGit Commit.png

It does not play a role whether you select this action on a certain file or on the whole project. The reason for this is that Git tracks all changes made to the whole repository capturing the modifications of each and every version-controlled file in that repository not regarding if these files reside in the same Eclipse project or not.

Once you have triggered the commit the following dialog will pop-up.

EGit CommitDialog.png

In this dialog you specifiy the commit message describing the change.

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 independant 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 succesfull 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.

Be aware that new files you added to the project which have not been explicitly added to version control (see "Modifying the content") will not be listed in the commit dialog and will not be part of the commit. If you are not sure whether you have created such files you may select "Team -> Add to Version Control" on an Eclipse project to add new files in the project to version control.

Ammending Commits

When you commit you may specify that the current commit should "amend" the previous commit in the current branch. Your commit will then replace the previous commit. This feature is often use to correct wrong commits before they are published to other repositories.

Example: Imagine you have committed a change to a file containing a typo

EGit Typo.png

After you committed you detect the typo. In order to correct this typo and the corresponding commit you just fix the typo in the source file

EGit Corrected.png

Afterwards you trigger the commit and select the option "Amend previous commit".

EGit AmendBringsOldCommitMessage.png

The commit message of your previous commit (the one which you want to replace) is filled into the "Commit Message" field. This gives you the chance not only to correct errors in the content of the version-controlled files but to also correct errors (e.g. typos) in the commit message describing your change.

As an alternative to amending you could just commit the corrected version as a subsequent commit. But the first commit containing the typo is of no use to anybody else and in order not to clutter the history of your project with unneeded commits you may decide to use the amend feature.

Be aware that amending commits which are already published to other repositories may cause trouble. Once you have pushed a commit to a remote repository or your local repository was cloned by somebody else you should be very careful whith amending commits. In this case publishing a second commit which corrects the first one is probably a better solution.

Signing off commits

Git gives you the chance to "sign off" commits. This adds a "Signed-off-by: <Your Name and Email-Adress>" footer to the commit message. The purpose of this signed-off-by information is not defined by Git but by the team using Git. Some teams use this information to record who has reviewed a certain commit. Other teams use the signed-off information to record that a commiter agreed to certain standards/rules. E.g. you may have to sign-off your own commits to state that you have read and understood the license-specific rules of your project.