|
Synopsis
Edit the jobs template
Syntax
p4 [g-opts] jobspec p4 [g-opts] jobspec [-i] p4 [g-opts] jobspec -o
Description
Perforce jobs can be used right out of the box, but it's often desirable to change the format of jobs to suit the needs of your site. The p4 jobspec command presents the Perforce superuser with a form in which job fields can be edited, created, deleted, and refined.
Please do not confuse the names of the fields in the p4 jobspec form with the names of the fields within a job. The fields in the p4 jobspec form are used to store information about the fields in the p4 jobs form.
Form Fields
Field Name
|
Description
|
---|
Fields:
|
A list of fields that will appear in your site's jobs, listed one per line. Each line has five parts: code name type length persistence.
- code: a unique integer that identifies the field internally to Perforce. The code must be between 101 and 199. Codes 101 to 105 have additional restrictions; please see the Usage Notes below for more details.
- name: the name of the field. This can be changed at any time, while the code should not change once jobs have been created.
- datatype: the datatype of the field. Possible values are:
- word: a single arbitrary word
- date: a date/time field
- select: one of a fixed set of words
- line: one line of text
- text: a block of text, starting on the line underneath the fieldname.
- length: recommended length for display boxes in GUI clients accessing this field. Use a value of 0 to let the client choose its own value.
- persistence: does the field being described have a default value? Is it required? Is it read-only? Possible values are:
- optional: field can take any value or can be deleted
- default: a default value is provided; it can be changed or erased.
- required: a default value is provided; it can be changed but the field can't be left empty.
- once: read-only; the field value is set once to a default value and is never changed.
- always: read-only; the field's value is set to a new default when the job is edited. This is useful only with the $now and $user variables; it allows you to change the date a job was modified and the name of the modifying user.
|
Values-fieldname:
|
Lists valid values for select fields. There should be one of these for each select field, with fieldname replaced by the name of the field. For example, a select field foo would have a corresponding Values-foo field.
Values are entered on a single line, separated by a slash (/), and with no spaces (e.g. bug/request/problem).
|
Preset-fieldname:
|
Contains the default values for each field that has a persistence of default, required, once, or always. Any one-line string can be used, or one of three built-in variables:
- $user: the user who created the job
- $now: the current date
- $blank: the phrase <enter description here>
- When users enter jobs, any fields in your jobspec with a preset of $blank must be filled in by the user before the job will be added to the system.
|
Comments:
|
Textual comments that will appear at the top of each p4 job form. Each line must begin with the comment character #.
See the Usage Notes, below, for special considerations for these comments when any of your users will enter jobs through P4Win, the Perforce Windows GUI client.
|
Options
-o
|
Write the jobspec form to standard output.
|
-i
|
Read the jobspec form from standard input.
|
g_opts
|
See the Global Options section.
|
Usage Notes
Can File Arguments Use Revision Specifier?
|
Can File Arguments Use Revision Range?
|
Minimal Access Level Required
|
---|
N/A
|
N/A
|
super, or list to use the -o flag
|
- Certain field codes have special significance to Perforce. We strongly recommend leaving the default fields 101 through 105 in the jobs system, and using p4 jobspec only to add new fields (i.e., 106 and above) to your jobs. Do not change the names or types of the following fields for any reason:
- 101: the job name. Required.
- 102: the job status. Optional; if present, p4 submit and p4 fix will set its value to closed, even if closed is not one of the status values.
- 103: the user who created the job.
- 104: the date the job was created.
- 105: the job description. Optional, but if not present, p4 change and p4 submit will no longer be able to display the job text.
- Jobspec editing is perhaps best learned by example. The jobspecs chapter of the Perforce System Administrator's Guide contains sample jobspecs; it's available at our Web site (http://www.perforce.com).
- The Comments: field is the only thing Perforce will display to your users to tell them how to fill in the form. Please make sure your comments are complete and understandable.
- The first line of each field's comment is also used by P4Win, the Perforce Windows GUI, to display ToolTips. It is therefore a good idea to make sure the first line of each field's comment can be read on its own.
Related Commands
To create, edit, or view a job
|
p4 job
|
To attach a job to a changelist
|
p4 fix
|
To list jobs
|
p4 jobs
|
To list jobs attached to specific changelists or changelists attached to specific jobs
|
p4 fixes
|
|