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:

status-window.png

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:
  1. 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.
  2. Update: An update command is run to get your files up to date.
  3. 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:

commit-window.png

Last edited Sep 3, 2007 at 11:54 AM by BradWilson, version 3

Comments

senfo Dec 6, 2009 at 7:33 PM 
Could you please include instructions for creating a patch?

YordanGeorgiev Oct 26, 2008 at 10:10 AM 
@ECHO ON
::CPC_CHEATCHEAT.CMD
::ADDS NEW PROJECT TO THE CODEPLEX FROM SCRATCH


:: SEE HELP , check that cpc in in PATH ENV variable
cpc
PAUSE
ECHO If you want to interrupt this batch file press Ctrl + C in any time
::LETS TRY SOME HELP
cpc help add
pause
::MAKE THE DIRECTORY FOR YOUR PROJECTS
mkdir D:\MyProjects
pause
::COPY ALL THE STUFF
ROBOCOPY D:\MyProjectToPublish D:\MyProjects\ /MIR /W:1
pause
echo if you do not have the ROBOCOPY command UNCOMMENT THE NEXT LINE
::XCOPY /S /E /Y /I D:\MyProjectToPublish D:\MyProjects\
pause
::REGISTER THE PROJECT TO CODEPLEX
cpc checkout MyProjectToPublish
pause
::ADD A WHOLE FOLDER OF THE PROJECT
cpc add /e MyProjectToPublish
pause
::CHECK THE CURRENT STATUS
cpc status
pause
::commit the added files to the codeplex
cpc commit /message "Just checking if cpc works with batch ..." /username MyUserName /password MySecretPass
pause

sandeepnahta Dec 28, 2007 at 4:54 PM 
Unable to checkout "pstfsconnector" project .. all other projects getting checkedout properly... any idea ?

coffeeCoder Dec 21, 2007 at 1:40 AM 
Umm manpages r helpful.

coffeeCoder Dec 21, 2007 at 1:09 AM 
yikes!!

Koro Nov 3, 2007 at 8:18 PM 
Same thing happens for me when trying to commit! "cpc commit" fails, and SvnBridge just exits.

intelitech Nov 3, 2007 at 3:31 AM 
Looks simple and straightfoward, however I'm stuck on the commit stage. I've got few files to be added and clearly the files are pending. At the stage of commit, both in command and GUI mode, I provide valid description and then I'm asked for a username/password. I'm sure I'm providing correct credentials. I can see the project being listed for the account I'm using and I cannot be wrong on the password either. The error message I'm getting is: "error: Attempted to perform an unauthorised operation". Any clues?

BradWilson Sep 3, 2007 at 11:56 AM 
CombatWombat, thanks. :)

cawoodm, sorry, just command line for the moment. Our effort right now is focused on SvnBridge, which should open up more options for clients (including things like Ankh, VisualSVN, and TortoiseSVN). Plus, I fixed the broken link. Thanks!

PandaWood, when issuing the delete command, files are removed from the file system (although folders are not, because of the _tfs tracking folder that needs to stick around until the commit is finished).

PandaWood Aug 25, 2007 at 4:28 PM 
When I issue a 'delete' the files are *not* removed from the filesystem - suggest you change this text

cawoodm Jul 7, 2007 at 10:26 AM 
Broken link here:
The syncup process uses an ignore file which is described in the *the description of the .exe.config file.*

cawoodm Jul 7, 2007 at 10:23 AM 
Any GUI for all this or a plugin for Visual Studio?

CombatWombat Jun 13, 2007 at 2:01 AM 
Nice mix of Subversion and TortoiseSVN.