[p4] Usefulness of "file spec" integrations

[Robert Cowham]

I sometimes mention to users that the word "branch" is used in 3 ways:

- as the verb "to branch" which "copies" files in a codeline to a different
codeline.

- as a noun meaning a codeline

- as a noun meaning the Perforce entity more fully called a branch spec.

The perforce "integrate" command will both branch (in verb sense above) and
propagate changes between codelines (merge). Steve's definition below is
very good.

Running the integrate command specifying (via -b flag on command line) a
perforce branch spec with N view mappings is just a short hand for the
equivalent N filespec integrations using the source/target pairings in the
branch spec (if no exclude lines present).

Note that creating a branch spec does not of course do the integrate, i.e.
it doesn't create the new codeline. It is like declaring the intention to
create the new codeline. Very similar to creating a new client workspace
spec - after creation you starting syncing it and then using it.

The other thing is that if you delete the branch spec, the integrates that
were done with it remain done (again like submitted changelists remain
submitted even when the client workspace has been deleted).

Advantages of branch specs include:

- multiple lines (to achieve the equivalent in filespec integration requires
N commands)
- avoidance of typos - very easy to accidentally create a new codeline
instead of propagating changes due to a typo in target files
- 2-way usage (with reverse option)
- useful description 
- possible exclude view options - this is hard to do with filespec
integration - you have to integrate and revert - easy to forget.
- train your users to not propagate changes (via integrate) if a branch spec
doesn't exist. Thus you can then delete branch specs for old (retired)
codelines, and avoid any accidental updates (this is also achievable via
protections etc).

Advantages of filespec integration:

- quicker for one time operations
- available via drag-and-drop in P4v (though this can also be dangerous - if
you drop on wrong place)

Does that help?

Personally while I think the functionality available in Perforce is very
good in this area, I do think that the terminology used (and names of
commands and entities) is not as clear as it could be (don't get me on to
the "yours/theirs" stuff in resolving integrates!). For reasons of backwards
compatibility on the command line (API), they aren't going to change it (as
far as I know). Note though that P4V now talks about workspaces whereas the
underlying command is "p4 client", so there is movement towards better
terminology.

It is not an easy thing to decide how to handle this. Perforce are to be
congratulated for the backwards compatibility thing (1997 clients talk
happily to 2007 servers for the basics!), but the downside is that some less
than optimal early decisions hang in there confusing a whole new set of
people (and of course one hopes that the number of users keeps increasing so
that the problem keeps getting bigger not smaller!).

Robert

> An integration in Perforce is a means of migrating changes 
> from one part of the repository to another. If the target of 
> the integration does not yet exist, you are "branching" (i.e. 
> creating new content, which can also be used as a micro-scale 
> copy operation). If not, it's a "merge" (i.e. setting up for resolve).
> 
> Ok, I think this clears things up for me. It's too bad this 
> paragraph isn't at the start of one of the chapters. :-)