top
Back to Archived Releases
|
eclipse cvs features |
| Eclipse Team Component | |
|
Last Modified: May 14, 2002 |
|
| Table of contents: |
| General Features: |
top
|
If folders and/or files that are under CVS control are deleted, these
deletions are remember and will be communicated to the server on the next
commit (either using Team/Commit or a commit operation in the Synchronize
view).
Renaming or moving a resource will be treated as a deletion at the old location and a creation at the new location. The new resources will not be place under CVS control until the user performs an Add to Version Control (either from the Team menu or in the Synchronize view).
| Synchronize View: |
top
|
The synchronization view is an Eclipse way of synchronizing a local workspace with an associated remote repository. For Eclipse CVS users, you can use this view to add/commit/update/merge changes in day-to-day development with your team. It provides an alternative to using CVS in a command line centric manner.
By far, the sync view is one of the most powerful features of the Eclipse CVS plugin.
The table below shows all the possible synchronization states for resources shown in the synchronization view and the CVS operations that can be performed for each state. The operations marked with a * are considered advanced operations and may only available from the context menu when in the advanced mode (e.g. modes allow filtering the sync view to show incoming, outgoing, or conflicting changes seperatly).
| Direction/Change Type | Change | Addition | Deletion |
| Incoming File or Folder |
1. Update from Repository (remote resource copied into workspace) 2. Override and Commit (overrides the remote revision with the revision in your workspace) * |
1. Update from Repository (remote resource copied into workspace) 2. Override and Commit (deletes the remote resource) * |
1. Update from Repository (deletes resources from workspace) 2. Override and Commit (overrides the deletion and commits the local resource to the repository) * |
| Outgoing Unshared File or Folder Addition (An unshared resource is one that has not been added to CVS control) |
N/A |
1. Add to Version Control (local resource added to version control so it can be commited) 2. Add to .cvsignore (marks to resources as ignored. The resources are removed from the sync view after being ignored) 3. Override and Update (local resources are deleted)* |
N/A |
| Outgoing File or Folder (An outgoing folder will never be a change) |
1. Commit (local resource commited to repository) 2. Override and Update (remote resource copied into workspace overriding local changes)* |
1. Commit (local resource commited to repository) 2. Override and Update (local resources are deleted)* |
1. Commit (remote resource deleted from repository) 2. Override and Update (remote resource copied into workspace overriding the local deletion) * |
|
Conflicting File a) auto-merge b) manual-merge |
1a. Override and Update (merges changes from remote into local resource) 2a. Override and Commit (local resource copied to repository overriding remote changes) 1b. Override and Update (remote resource copied into workspace overriding local changes) 2b. Override and Commit (same as 2a) |
same as conflicting change | Resources are in sync, these aren't shown in the sync view. |
| Conflicting Folder |
A folder that is a conflicting change is an outgoing
folder deletion has children that are incoming or conflicting. The folder
state will be adjusting depending on the operations performed on the
children. |
A folder that is a conflicting addition indicates
that an unshared local folder already exists remotely. Operations performed
on the folder or any of its childen will adjust the local folder state
to match that of the remote. |
N/A |
The sync view provides an easy way of performing tasks that are much more difficult to accomplish by using the CVS command line client. In addition, text files can be visually merged within the sync view.
There are two categories of conflicting changes that will appear in the sync view:
For conflicting files that can be automatically merged, the Override
and Update operation in the sync view will ask to either perform
the merge or simply replace the local file with the remote
revision. For manual merge files the Override and Update operation
will replace the local file with the remote revision.
If the file with the manual-merge is a text
file you can use the diff editors in the lower part of the
sync view to resolve the conflicting changes. You can either
use the Copy Right to Left buttons or simply copy and paste in
the editors to resolve the conflicts. Any changes must be saved (see
Saving files
below).
When CVS performs merges with the update command it saves .# backup files of the working copy of a files before the merge. The update command from the sync view will not create these files, instead use local history to retrieve a copy of the file before the merge.
When you select a file in the sync view's top pane the local, remote,
and if applicable, the ancestor file contents are shown
in the bottom half of the view. You can edit the local file
at anytime (either directly or using the sync view copy actions) and when
the save action (context menu or if prompted to save) is performed
the file will be saved to disk at that moment. They aren't buffered
and saved at a later time.
Files that have been edited and save in the sync view will remain
in the view until the user performs a Confirm Merge operation on the
file which indicates that the conflict has been resolved.
| Parallel Development with branches: |
top
|
The desire to create a branch can be the result of several scenarios. In one common secenario, a designer may decide to create a branch after making modifications to one or more projects shared with HEAD. They would like to store the modifications in the repository but doing so may leave the project(s) in an unstable or otherwise undesirable state. By creating a branch, the designer can store the modifications in the repository without affecting the state of the project(s) in HEAD. At a later time, when modifications on the branch have reached a stable state, the designer can merge the modifications into HEAD.
Another common scenario involves adding critical bug fixes to a version of a project that is included in an official release of a product. All important versions of a project stored in CVS should be tagged so that product releases based on the project versions can be recreated easily. Assuming that version tagging was performed, a designer can load the code base of a released product by loading the corresponding versions of the projects that constitute the product release. Patches can then be created to fix any critical bugs in the product release. Once created, these modifications need to be stored in the repository so future critical bug fixes to the product release will be made on top of the actual code in the product release. However, CVS does not allow modifications made to loaded versions to be committed back into the repository. Also, it would be inappropriate to store these changes in HEAD as the development in HEAD may be months ahead of the version in the product release (although the bug fixes should be made in HEAD as well, if appropriate). In this situation, the designer can create a banch off the project version and commit the modifications to the branch. The project branch should still be versioned for every official patch release so that the designer can keep track of what code is in each release.
More information on banching can be found in Open Source Development
with CVS, 2nd Edition.
Both of the scenarios described above begin with a local working copy of a project shared with a CVS repository. Creating a branch on a local working copy typically consists of three operations:
In Eclipse, the CVS branch action (available in the Team context menu of resources in the navigator) presents a wizard that can perform all three of these operations. It requires the specification of a branch tag and optionally allows the specification of a version tag that acts as the starting point when merging the branch back to HEAD (the user will be required to provide a version tag unless they already have a version loaded). Also, it provides the option of starting to work in the branch. Enabling this option will update the local working copy to be shared with the branch. Subsequent synchronization operations will be performed against the branch. Resources subsequently commited will not effect other developers working in HEAD until the branch is merged with HEAD.
At some point, a designer will wish to merge the modifications they have made in a branch back into HEAD (or another branch depending on how a development group has decided to share work). This merge is complicated by the fact that other developers may have made modifications in the target branch (usually HEAD) that overlap with the modifications made in the source branch. Merging is perfomed by loading the target branch into the local workspace and then merging the source branch into the target. Therefore, merging one branch with another involves similar resource states as described in the section on synchronization except that the states are resticted to those involving incoming and conflicting resource modifications.
Merging is performed using the merge wizard. To perform a merge:
Upon finish, the designer is presented with a merge editor that behaves similarily to the synchronize view with the exception that ony incoming changes and conflicts are considered. Once the merge in complete, the designer should then perform any tests to ensure that the code still works before synchronizing and committing the modifications to the target branch.
In the repositories view, the contents of HEAD or another branch can be viewed. When a repository entry is expanded, several categories are shown including HEAD and Branches. Expanding HEAD shows the root level folders of the repository. Further expanding a particular project will show the resource revisions that are associated with the project in HEAD. Expanding the Branches category shows a list of all known branches. Like expanding HEAD, expanding one of these branches shows the root level folders of the repository and further expansion will lead to the revisions contained in that branch. It should be noted that folders are considered to be in HEAD and all branches. For this reason, a folder may appear empty in the repositories view. This could be an empty folder or a folder that contains resources in another branch (or version). Projects can be checked out from a branch just as they can be checked out from HEAD.
Initially, Eclipse may not know about branches that are define for a repository or project. A designer can define branches manually from the context menu of the Branches category entry using the Define Branch operation or can auto-discover branch and version tags using the Configure Branches and Versions operation available from the context menu of any foldr in the Repositories view.
The Repository View can also be used to move branch tags to a different
base version of a project in the same way a version tag can be moved
(see Moving Tags
).
Websites
Books
Open Source Development with CVS, 2nd Edition, by Karl Fogel and Moshe
Bar, Coriolis Technology Press, 2001
(portions available
on-line
)
| Tags and Project Versions |
top
|
Tags are used in CVS to group a set of resource revisions for later retrieval. Hence, tags are often used to identify the versions of a particular project or set of projects. In Eclipse, tagging can be performed on projects, folders or files. However, the repositories view only shows tags at the project level (and refers to them as versions).
Tags are also used in CVS to identify branches, as described in the previous section.
Tagging is performed by selecting the Team/Tag item from a resource's context menu. The tag is then applied to the remote resource revisions corresponding to the resources that exist in the local workspace. The user should commit any local changes if they desire those changes to be included in the tagged set of resources.
By default, a tag can only be applied to a set of resources if the tag hasn't been previously applied to any of the resources being tagged. However, the user may choose to force the tag to be moved to the resource revisions in the current line up. The ability to move tags is available in the Repositories view using the Tag with Existing operation.
Tags are shown in the repositories view on a per project basis. Expanding the Versions category shows the list of projects and expanding a project shows the list of versions defined for that project. Version names can be manually added for a project or can be auto-discovered by performing an Configure Branches and Versions operation on a file in the project (in HEAD). Expanding a version will show the folders and resource revisions for the resources in the version. As mentioned previously, folders are considered to be in all branches and versions even if they are empty.
The repository view allows a version of a project to be checked out in the same mannor as projects can be checked out from branches. However, changes made to a version cannot be committed back to the repository. To commit changes to a version, the user must create a branch off the version (as described in the previous section).
It is possible to revert the resources in HEAD or a branch to the contents of resource revisions from a particular version. This is done using the Compare editors. First, load a project, folder or file from HEAD or the branch to be reverted. Then perform a Compare With/Branch or Version on the resource(s) to be reverted. The Compare editor can then be used to copy remote contents into the local resources and to save these changes.
Tagging can be performed from the repositories view by selecting a remote resource(s) and performing a Tag as Version operation.
| Modules |
top
|
CVS sometimes referes to all remote folders as modules. However, CVS also supports the definition of modules which do not necessarily correspond directly to a remote folder. This section describebs these modules.
By default, the Repositories view lists the folders that exist in a repository. The view can be toggled to show the modules that are defined in the CVSROOT/modules file by using the drop down menu in the title bar of the view. In Show Modules mode, only module definitions are shown and can be checked out. Once a module is checked out, the local copy of a module is treated no differently than other CVS projects.
Modules are defined in the CVSROOT/modules file. See the CVS documentation for more information about defining modules.
| Ignoring Resources |
top
|
In most cases, newly created resources that are children of a folder that is under CVS control are eventually placed under CVS control and committed to the repository. However, in some cases, it may be the user's desire to exclude certain files from CVS control. For example, files and folders that are the output of a build process are often not stored in the repository since they can be derived from the files that are in the repository. For this reason, CVS requires new resources to be explicitly added to CVS control before they can be committed. Although CVS will not commit a resource until it has been added to CVS control, CVS will still consider the file during some operations. For instance, these resources will appear in the Synchronize view as outgoing additions.
Excluding a resource entirely from CVS operations is referred to as ignoring that resource. Ignoring a resource prevents the resource from appearing in the Synchronize view or from being added when an ancestor is added. The Team/Add to Version Control opetion can be performed on a new folder and this will add all non-ignored children to CVS control. Also, ignored resources are not decorated by the CVS decorators.
One of the mechanisms that CVS provides for ignoring resources is the .cvsignore file. When a .cvsignore file exists in a folder that is under CVS control, CVS will ignore all resources which reside in that folder whose names match one of the patterns in the .cvsignore file. The Add to .cvsignore operation is available from the Team menu and in the Synchronize view and can be performed on newly created resources that are not under CVS control. This operation presents the user with a dialog that will aid them in adding the desired pattern to the proper .cvsignore file. The user can choose to add the file name as is, add the *.ext pattern (where ext is the extension of the selected file or files) or specify their own pattern. Patterns consist of valid file/folder name characters as well as the wildcards "*" (which matches any string of one or more characters) and "?" (which matches any single character).
An ignored resource can still be explicitly added to CVS control using
the Add to Version Control operation. This is supported because there are
several global mechanisms for ignoring resources. For one, CVS has a set of
standard file name patterns that are ignored (see the CVS documentation for
a complete list). There is also a CVSROOT/cvsignores file that defines global
ignores for a repository (Eclipse currently does not honor these ignores).
There are also Eclipse derived resources and an Eclipse ignore facility, described
in the sections that follow.
Tools in Eclipse that generate derived resources will mark the resources as derived. The Eclipse CVS client will automatically ignore any resource that has been marked as derived. For example, using the JDT to compile java code will result in th creation of *.class files. These files are marked as derived by JDT and are therefore ignored by CVS.
Eclipse also provides a mechanism for specifying a set of file patterns
that will be automaticaly ignored. This is useful if a user is using an external
tool which generates derived resources which do not get marked internall as
derived by Eclipse. The ignored file patterns can be specified on the Team/Ignored
Resources preference page. Patterns follow the usual format, consisting of
valid file name characters and the wildcards * and ?. An entered pattern
can be enabled or disabled on the preferecne page as well.
| top |