|
Synopsis
List jobs known to the Perforce server
Syntax
p4 [g-opts] jobs [-e jobview] [-i] [-l] [-r] [-m max] [file[rev] ...]
p4 jobs -R
Description
When called without any arguments, p4 jobs will list all jobs stored on the server. You can limit the output of the command by specifying various criteria with flags and arguments. If you specify a file pattern or, the jobs listed will be limited to those linked to changelists affecting particular files. The -e flag can be used to further limit the listed jobs to jobs containing certain words.
Jobs are listed in alphanumeric order (or, if you use the -r flag, in reverse alphanumeric order) by name, one job per line. The format of each line is:
jobname on date by user *status* description
The description is limited to the first 30 characters, unless the -l (long) flag is used.
If any of the date, user, status, or description fields have been removed by the Perforce superuser with p4 jobspec, the corresponding value will be missing from each job's output.
To limit the list of jobs to those that have been fixed by changelists that affected particular files, use p4 jobs filespec. The files or file patterns provided may contain revision specifiers or a revision range.
Options
|
-e jobview
|
List only those jobs that match the criteria specified by jobview. Please see the Usage Notes below for a discussion of job views.
|
|
-i files...
|
Include jobs fixed by changelists that affect files integrated into the named files.
|
|
-l
|
Output the full description of each job
|
|
-m max
|
Include only the first max jobs, sorted alphanumerically. If used with the -r flag, the last max jobs are included.
|
|
-r
|
Display jobs in reverse alphabetical order by job name.
|
|
-R
|
Rebuild the job table and reindex each job. Reindexing the table is necessary only when upgrading from version 98.2 or earlier to version 98.3 or higher and only needs to be performed once.
|
|
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
|
|---|
|
Yes
|
Yes
|
list
|
Job Views
Use p4 jobs -e jobview to limit the list of jobs to those that contain particular words. You can specify that the search terms be matched only in particular fields, or anywhere in the text of the job. You can use jobviews to match jobs by values in date fields, though there are fewer options for dates than there are for straight text.
Text matching is case-insensitive. Each word is treated individually; phrases are not matched. Use alphanumeric text only, with no punctuation. (Punctuation is ignored in jobviews.)
The jobview `word1 word2 ... wordN' can be used to find jobs that contain all of word1 through wordN in any of the job's fields. Spaces between search terms in jobviews act as boolean AND operations. To find jobs that contain any of the terms, separate the terms with the "|" character. Ampersands (&) can be used as boolean ANDs as well; the boolean operators bind in the order &, |, space (highest precedence to lowest precedence). Use parentheses to change the grouping order.
Search results can be narrowed by matching values within specific fields with the jobview syntax"fieldname=value". The value must be a single alphanumeric word.
The wildcard "*" allows for partial word matches. The jobview "fieldname=string*" matches "string", "stringy", "stringlike", and so on.
Date fields can be matched by expressing the jobview date as yyyy/mm/dd or yyyy/mm/dd:hh:mm:ss. If a specific time is not provided, the equality operator (=) matches the entire day.
The usual comparison operators (=, >, <, >=, and <=) are available.
Additionally, you can use the NOT operator (^) to negate the sense of some comparisons. (See Limitations, below, for details).
The behavior of these operators depends on the type of job field you're comparing against:
Field Type
|
Use of Comparison Operators in Jobviews
|
|---|
|
word
|
The equality operator (=) must match the value in the word field exactly.
The inequality operators perform comparisons in ASCII order.
|
|
text
|
The equality operator (=) matches the job if the word given as the value is found anywhere in the specified field.
The inequality operators are of limited use here, since they'll match the job if any word in the specified field matches the provided value.
For example, if a job has a text field ShortDescription that contains only the phrase gui bug, and the jobview is "ShortDesc<filter", the job will match the jobview, because bug<filter .
|
|
line
|
As for field type text, above.
|
|
select
|
The equality operator (=) matches a job if the value of the named field is the specified word. The inequality operators perform comparisons in ASCII order.
|
|
date
|
Dates are matched chronologically. If a specific time is not provided, the operators =, <=, and >= will match the entire day.
|
If you're not sure of a field's type, run p4 jobspec -o, which outputs the job specification used at your site. The p4 jobspec field called Fields: contains the job fields' names and datatypes. See p4 jobspec for a discussion of the different field types.
Other Usage Notes
- The p4 user form has a JobView: field that allows a jobview to be linked to a particular user. After a user enters a jobview into this field, any changelists he creates will automatically list jobs that match the jobview in this field. The jobs that are fixed by the changelist can be left in the form, and the jobs that aren't should be deleted.
- p4 jobs sorts its output alphanumerically by job name, which also happens to be the chronological order in which the jobs were entered. If you use job names other than the standard Perforce names, this ordering may not help much.
- The -m max -r construct displays the last max jobs in alphanumeric order, not the max most recent jobs, but if you're using Perforce's default job naming scheme (e.g., job001394), alphanumeric job order will be identical to order by entry date.
- You can use the * wildcard to determine if a text field contains a value or not by checking for the jobview "field=*"; any non-null value for field will match.
Limitations
- Jobviews cannot be used to search for jobs containing null-valued fields. In other words, if a field has been deleted from an existing job, then the field is not indexed, and there is no jobview that will match this "deleted field" value.
- The jobview NOT operator (^) can be used only after an AND within the jobview. Thus, the jobviews "gui ^name=joe" and "gui&^name=joe" are valid, while the jobviews "gui|^name=joe" and "^name=joe" are not.
- The * wildcard is a useful way of getting around both of these limitations.
- For instance, to obtain all jobs without the string "unwanted", query for `job=* ^unwanted". All jobs will be selected by the first portion of the jobview and logically ANDed with all jobs NOT containing the string "unwanted".
- Likewise, because the jobview "field=*" matches any non-null value for field, (and the job field can be assumed not to be null), you can search for jobs with null-valued fields with "job=* ^field=*"
- When searching, punctuation in field contents in jobviews is ignored. (Punctuation in field names, however, is accepted.)
- The following query, for instance, will return counterintuitive results, because the period in "99.2" and the underscore and hyphen in "firstnm_hyphenated-surname" will be ignored:
p4 jobs -e "release=99.2 owner=firstnm_hyphenated-surname"
p4 jobs -e "owner=firstnm*name"
- To work around this limitation, use the following jobview:
p4 jobs -e "release=99 release=2 owner=firstnm owner=hyphenated owner=surname"
- (Astute observers will note that this query will also return jobs with owner=hyphenated-surname_firstnm, and release=99.4.2, but in most cases, this issue rarely arises.)
- The underlying technical reason for this limitation and the associated workarounds is that strings are broken at non-alpha characters before being indexed by the job system. Changing this would result in a requirement for a reindexing of the data upon upgrading the server. A cleaner solution to this limitation is anticipated in a future release.
Examples
|
p4 jobs //depot/proj/foo#1
|
List all jobs attached to changelists that included revisions of //depot/proj/foo.
|
|
p4 jobs -i //depot/proj/foo
|
List all jobs attached to changelists that included revisions of //depot/proj/foo or revisions of files that were integrated into //depot/proj/foo
|
|
p4 jobs -e gui
|
List all jobs that contain the word gui in any field.
|
|
p4 jobs -e 'gui Submitted-By=joe'
|
List all jobs that contain the word gui in any field and the word joe in the Submitted-By: field.
|
|
p4 jobs -e 'gui ^Submitted-By=joe'
|
List all jobs that contain the word gui in any field and any value other than joe in the Submitted-By: field.
|
|
p4 jobs -e `window*'
|
List all jobs containing the word "window", "windows", "windowing", in any field. The quotation marks are used to prevent the local shell from expanding the "*" on the command line.
|
|
p4 jobs -e `job=* ^unwanted'
|
List all jobs not containing the word unwanted in any field.
|
|
p4 jobs -e
'(fast|quick)&date>1998/03/14'
|
List all jobs that contain the word fast or quick in any field, and have a date: field pointing to a date on or after 3/14/98.
|
|
p4 jobs -e
'fast|quick' //depot/proj/...
|
List all jobs that have the word fast or quick in any field, and that are linked to changelists that affected files under //depot/proj.
|
Related Commands
|
To create or edit an existing job
|
p4 job
|
|
To attach a job to a particular changelist, indicating that the job is fixed by that changelist
|
p4 fix
|
|
To list all jobs and changelists that have been linked together
|
p4 fixes
|
|
To view all the information about a particular changelist, including the jobs linked to the changelist
|
p4 describe
|
|
To change the format of the jobs used on your server (superuser only)
|
p4 jobspec
|
|
To read information about the format of jobs used on your site (any user)
|
p4 jobspec -o
|
|
To set a default jobview that will include jobs matching the jobview in all new changelists
|
p4 user
|
|