Typical Workflow
Table of Contents
Introduction
Client/server source control systems generally fall into two categories:
- The first is called "checkout-edit-checkin" (or "server-side state"), where the system requires that you notify the system before you begin editing the file. Visual Source Safe and Team Explorer work in this way.
- The second is called "edit-merge-commit" (or "client-side state"), where the system allows you to just start editing files without notifying the system ahead of time. Because you don't need to contact the server when you begin editing files, this allows you to work completely offline from the server until the time when you're ready to commit your source code to the server. The CodePlex Client works in this way.
In an edit-merge-commit system, many of the commands in the system do not require a connection to the server to complete. As a general rule, when you look at the help for a CodePlex Client command, if it does not offer an option for specifying your username and password, it doesn't connect to the server (and thus can be performed while offline).
This is a streamlined introduction to the way you will typically use the CodePlex Client. Many of the commands shown here have many options that we do not cover in this introduction. For in-depth help on a specific command, type:
cpc help [commandname]
Listing Projects
The
listprojects command can be used to list which projects in which you have commit rights. Issue the command along with your CodePlex username:
cpc listprojects johndoe
Getting Your First Copy of The Source Code
From the command prompt, make a directory to hold the source code and change to that directory:
C:
md \MyProject
cd \MyProject
Then issue the
checkout command:
cpc checkout MyProjectName
This will get your first copy of the source code into the current directory. If you've never used cpc before, it will prompt you for your CodePlex username and password.
You should see messages similar to these:
A .
A Branches
A EULA.rtf
A Main
A Main\ObjectBuilder
A Main\ObjectBuilder.sln
A Main\ObjectBuilder\Builder.cs
A Main\ObjectBuilder\BuilderBase.cs
A Main\ObjectBuilder\BuilderContext.cs
A Main\ObjectBuilder\BuilderPolicyKey.cs
A Main\ObjectBuilder\BuilderStage.cs
[...]
Editing Files
Since CodePlex Client is an edit-merge-commit style system, you don't need to take any explicit steps to begin working. All the files are already writable. Just go ahead and start editing!
Adding Files
If you want to add items, use the
add command:
cpc add filename
This will schedule the add to happen during your next commit. If you change your mind before you commit, you can
revert your change.
You do not need a connection to the server to issue this command.See also: Using Syncup
Deleting Files
If you want to delete items, use the
delete command:
cpc delete filename
This will schedule the delete to happen during your next commit. Deleted files will be removed from your filesystem. If you change your mind before you commit, you can
revert your change.
You do not need a connection to the server to issue this command.See also: Using Syncup
Undoing Changes
If you've made a change you wish to undo, use the
revert command:
cpc revert filename
The actions for revert depend on the item's current status. If the item has been scheduled for add, it reverts back to the unversioned state. If the item has been scheduled for delete, it reverts back to the unmodified state (and the file is restored). If the file has been modified, it reverts back to the unmodified state (and the original file contents are restored).
You do not need a connection to the server to issue this command.
Getting Status on Your Changes
The
status command will tell you the status of changes on your system:
cpc status
You will see output similar to this:
A .tfs-ignore
M Main\ObjectBuilder\Builder.cs
? Main\ObjectBuilder\Builder.cs.new
A Samples\DependencyContainer
! Samples\DependencyContainer\DepedencyContainer
? Samples\DependencyContainer\DependencyContainer
M Samples\DependencyContainer\DependencyContainer.sln
? Samples\DependencyContainer\DependencyContainer.Tests
? Samples\DependencyContainer\Samples
The letter describes the state of the item. For a list of the status codes, type "cpc help status".
You can also get a GUI version of the status command:
cpc status /gui
Which will show a window similar to this:

From this status window, you can perform CodePlex Client operations by right clicking on items in the list. Additionally, you can double click a file in the
Modified state to get a diff of that file, and you can double click a file in the
Conflicted state to perform a merge of that file. For diff and merge to work, you must have a diff/merge tool installed and properly configured. For more information, see
the description of the .exe.config file.
You do not need a connection to the server to issue this command.
Updating Your Code
The
update command will update your copy of the source code to the latest version stored on the server:
cpc update
This command will show status as it updates your local copies of files to be in sync with the server versions. For a list of the status codes provided by update, type "cpc help update".
Resolving Conflicts
When you update a file that you have edited, it's possible that someone else may have committed a change to that file since your last update. When this happens you may end up in a conflicted state. This means the system could not automatically merge your changes with the other changes on the server.
The best way to resolve conflicts is to use the status GUI (
cpc status /gui) and double click your conflicted file(s) to run your
configured merge tool. If you save your merge changes, the system will automatically prompt you to mark the file as resolved when you're finished.
If you choose to merge the files by hand, you can use the
resolve command to mark a file as resolved:
cpc resolve filename
Note: You will not be able to commit when you're in the conflicted state. Use the status GUI (or the resolve command) to help you resolve your conflicts.You do not need a connection to the server to issue this command.
Using Syncup
When working, you will typically want to be able to edit, add, and delete files without worrying about running cpc commands to make sure the files are properly scheduled for add or delete. The
syncup command will prepare you for a commit operation by figuring out what add and delete operations should be performed.
It does this in three phases:
- Delete: If an item was previously under source control, but has been deleted from the file system, the item is scheduled to be deleted from source control.
- Update: An update command is run to get your files up to date.
- Add: If an item exists on the file system, but is not under source control, the item is scheduled to be added to source control. You will be prompted before adding each item.
The syncup process uses an ignore file which is described in the
the description of the .exe.config file.
Committing Your Changes
When you're ready to send your source code into the server, use the
commit command:
cpc commit
Committing requires a commit message. If you don't specify the commit message from the command line (using the /message option), then cpc will open notepad with a temporary text file for you to provide your commit message (it will also show you a list of files that will be committed). For more information, see
cpc help commit.
A commit GUI is also available, which can be launched with the /gui switch:
cpc commit /gui
Which will show a window similar to this:
