Working with Flare projects that are bound to Perforce

Introduction

Here’s the long-promised second post about using Perforce source control with Flare.  This post describes how to edit, add and delete Flare files that are under Perforce control (moving or renaming files is much more complicated, so will be the subject of a separate post). I hope this helps someone.

Before we start, here are a few disclaimers. This post only applies to Flare and Perforce. I’ve not used other source control systems with Flare, and I know that some of them work quite differently. Also, there may be other (and possibly better) ways of doing some of the things I describe here. I’m just describing the things that work well for me. If you know of better ways, please let me know in the comments. Finally, I’m now using Flare 9.1.2, which has far better Perforce support than earlier versions of Flare, and is far more robust. If you are using an earlier version of Flare, you may notice some differences. I first used Perforce with Flare 7, so I’ll try to mention any significant differences where possible. If you are a Perforce user, I’d strongly recommend upgrading to at least Flare 9.1.2 as soon as possible.

Prerequisites

Some of the things I describe here need a basic understanding of Perforce, as a few operations are better done directly in Perforce rather than Flare. I’m assuming you’re familiar with the concepts of checking in and checking out files, and the Perforce depot, workspaces and changelists. I’m also assuming you are using the Perforce Windows client, P4V.

Before you can access Perforce functions directly from Flare, you need to bind the Flare project to Perforce. Once this has been done (it only needs to be done once for the project, then anyone can use it), from your Perforce workspace, open the bound project in Flare and specify the Perforce connection details. When you are asked if you want to build the source control cache, select No (selecting Yes usually hangs Flare). If you are asked if you want to get the latest versions of the files, select No (selecting Yes usually hangs Flare).

Suggested preparation

If you think your workspace may not contain the latest versions of the project files, and you want them, get them directly into your workspace now using P4V.

Since you have not been able to build the source control cache, Flare may not be aware of the latest Perforce status of the project files. To remedy this, in Project Organizer, select the Project folder, right-click and select Source Control > Refresh. In Content Explorer, select the Content folder and repeat. You can do this at any time for any folder, subfolder or file, if you suspect Flare and Perforce are out of sync (for example, Flare may think a file is checked out, and hence writable, but it isn’t).

Editing Files within Flare

Edit your project files as normal. If your project is bound to Perforce, when Flare tries to save your changes, you will usually see a progress window, saying that Flare is checking out the file.

You won’t see a checkout message if the file is already checked out, or if Flare and Perforce are out of sync and Flare thinks the file is checked out, but it isn’t really. In the latter case, you will see an error message saying Flare can’t save the file. This is a job for Source Control > Refresh, then try to save the file again, and you will see the checkout message as usual.

The file will be checked out into your default changelist. I strongly recommend that you create a Perforce named changelist for each group of related changes (I often find myself working on several concurrent and distinct changes within the same Flare project and need to check them in separately). So, periodically, in P4V, inspect your default changelist, and move the checked out files in it into the correct named changelist.

Editing files outside Flare

Sometimes, I need to edit a file outside Flare (for example, I use Notepad++ to edit my stylesheets). If you do this, to avoid losing your changes, remember to check the file out immediately using P4V if it is not already checked out. Depending on the program you use to make the edits, you may find you can’t save the file until it is checked out, or the program may offer to make the file writable for you and save it, but this won’t check the file out in Perforce.

Checking in edited files

When I am ready to check in my changes, I always perform the check-in directly from P4V, not Flare. This is because it gives me much more control over the check-in. In earlier versions of Flare, I found that although Flare shows you the standard Perforce check-in dialog box, you can’t get too clever with the options available to you in this dialog box, as Flare has quite specific requirements as to what options it can cope with. And, in any case, I will never be checking in from the default change list, as I will have already organised my checked out files into named changelists as required.

Not surprisingly, when you check in a file directly from P4V, Flare will still think it is checked out, so you may need to do Source Control > Refresh before you are able to save any more changes to that file. 

Adding files to a Flare project

The recommended steps to add a file to a Flare project depend on whether the file you are adding is an existing file, or has been created as a new file within Flare.

If you add an existing file to the project by copying it into the project area (for example, if you may do this if you add an image, or an existing stylesheet) you must add it to Perforce manually. You can do this within Flare (Source Control > Add), but I prefer to do it directly from P4V, because I can specify the changelist to use, whereas Flare will include it in the default changelist. Also, if you select Source Control > Add, by default, Flare will check the file in immediately, unless you remember to select the Keep Checked Out option. That probably isn’t what you want. And, even worse, Flare will bury this file in a long list of all the files in your project that Flare thinks should be checked in (usually incorrectly, especially if you use global project linking).

If you create a new item within Flare, Flare may or may not automatically add it to your default Perforce changelist. For example, in Flare 9.1.2, if you create a new snippet, Flare adds it automatically, but if you create a new topic, it seems that Flare doesn’t.

There is a possible further complication if you create a new item within Flare 9 or later. When you name the item, if the name includes a space, and you inadvertently hold down Shift while typing Space (as you might, for example, if the character immediately before or after the space is upper case), the filename will include not a space character (ASCII 32) but a non-breaking space character (ASCII 160). Believe me, this is going to cause all sorts of problems for you later. This isn’t a Perforce-specific issue, but it will need to be fixed, and will then become a Perforce-specific issue, as renaming Flare files that are in Perforce is complicated and is a whole blog post of its own. So far as I know, accidentally including non-breaking spaces in Flare filenames isn’t a problem before Flare 9.

So, in all cases, as soon as you know you have added a new file to your Flare project, get into the habit of making sure that it is in a suitable changelist waiting to be checked into Perforce. And, if the file has been created from within Flare, check that it does not include any non-breaking spaces in the file name. I cannot stress this last point strongly enough, as this can cause no end of hard-to-find and hard-to-fix problems later.

Deleting files from a Flare project

I never, ever, ever, delete Perforce files directly from Flare. Flare doesn’t do a very good job of actioning the deletion in Perforce (in Flare 7 at least, Flare would hang if you selected the option to delete the file from source control). To make matters worse, once Flare has deleted the file from your workspace, you won’t be able to delete it directly in P4V, since Perforce needs the file in your workspace in order to delete it.

So, when I want to delete a file, I simply check that nothing in my Flare project references it (in Flare, right-click on the file, then select View Links). Then, in P4V, I delete the file, assigning the deletion action to the appropriate changelist.

Moving and renaming files in the Flare project

This is absolutely horrendous and not to be undertaken lightly, so is the subject of a separate post (coming soon). You usually need to perform the move or rename from within Flare, to ensure any links to the moved or renamed files are updated correctly. And, if you are moving files, even if nothing else links to them yet, because of the bizarre way that Flare implements links to other files, you also need to do the move within Flare to ensure that any links within the moved files are updated correctly.

Flare does not send the correct messages to Perforce for moves and renames (this may be a more general problem with the Microsoft SCC API, not a Flare problem as such) so you will definitely have to pick up the pieces in P4V later. But in order to move or rename a file from P4V, the old file must still exist in the workspace, and the new file must not yet exist. This won’t be the case if you have already carried out the move or rename within Flare, so you need some fancy footwork to get round this.

My recommendation is to work in a way that minimises the need to move or rename files. Be sure you are happy with your file names and project folder decomposition before you check in newly created files. If you have to move or rename files, find somewhere quiet and interruption-free, turn off all distractions, prepare yourself to follow the instructions carefully, then check the results thoroughly.

And finally . . .

If this has helped you, please let me know. If you have questions, feel free to ask them, and I’ll try to help. And, if you have better ways of using Flare with Perforce, please do tell me. I’d be really interested to discover more.