p4 jobs
Synopsis
List jobs known to the Perforce versioning service.
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 lists all
jobs stored in Perforce. You can limit the output of the command by
specifying various criteria with options and arguments. If you specify a
file pattern, the jobs listed will be limited to those linked to
changelists affecting particular files. The -e
option 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
option, 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 31
characters, unless the -l
(long) option 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 can contain revision specifiers or a revision range.
Options
|
List only those jobs that match the criteria specified by
|
|
Include jobs fixed by changelists that affect files integrated into the named files. |
|
Output the full description of each job. |
|
Include only the first |
|
Display jobs in reverse alphabetical order by job name. |
|
Rebuild the job table and re-index each job. Re-indexing the table is necessary either when upgrading from version 98.2 or earlier, or when upgrading from 99.1 to 2001.1 or higher and you wish to search your body of existing jobs for strings containing punctuation. |
|
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 |
|
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 text. Job fields of type bulk
are not
indexed for searching.
Text matching is case-insensitive. All alphanumeric strings (including words including embedded punctuation) separated by whitespace are indexed as words.
The jobview '
can be used to find
jobs that contain all of word1
word2
...
wordN
'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 (boolean OR), 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 token, including
both alphanumeric characters and punctuation.
The wildcard "*
" allows for partial word matches. The
jobview
"
"
matches "fieldname
=string*string
", "stringy
",
"stringlike
", and so on.
Date fields can be matched by expressing the jobview date as
or yyyy
/mm
/dd
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).
Regular expression matching is supported by the regular expression
matching operator (~=
).
To search for words containing characters that are job search expression
operators, escape the characters with a backslash (\
)
character. To match the backslash character, escape it with an
additional backlash (\\
).
The behavior of these operators depends on the type of job field you're comparing against:
Field Type |
Use of Comparison Operators in Jobviews |
---|---|
|
The equality operator ( The relational operators perform comparisons in ASCII order. |
|
The equality operator ( The relational operators are of limited use here, because they match the job if any word in the specified field matches the provided value.
For example, if a job has a |
|
As for field type |
|
The equality operator ( |
|
Dates are matched chronologically. If a specific time is not
provided, the operators |
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 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 lastmax
jobs in alphanumeric order, not themax
most recent jobs, but if you're using Perforce's default job naming scheme (jobs numbered likejob001394
), alphanumeric job order is 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 "
"; any non-null value forfield
=*field
matches. -
When querying for jobs using the
-e
option, be aware of your operating system and command shell's behavior for parsing, quoting, and escaping special characters, particularly when using wildcards, logical operators, and parentheses.jobview
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 matches 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 "
" matches any non-null value forfield
=*field
, (and thejob
field can be assumed not to be null), you can search for jobs with null-valued fields with "job=* ^
"field
=* -
You cannot currently search on space-delimited fields with conditionals. For example, instead of using p4 jobs -e "field=word1 word2", you must use p4 jobs -e "field=word1 field=word2".
Examples
p4 jobs //depot/proj/file#1 |
List all jobs attached to changelists that include
revisions of |
p4 jobs -i //depot/proj/file |
List all jobs attached to changelists that include revisions of
|
p4 jobs -e gui |
List all jobs that contain the word |
p4 jobs -e "gui Submitted-By=joe" |
List all jobs that contain the word |
p4 jobs -e "gui ^Submitted-By=joe" |
List all jobs that contain the word |
p4 jobs -e "window*" |
List all jobs containing the word " |
p4 jobs -e window.c |
List all jobs referring to |
p4 jobs -e "job=* ^unwanted" |
List all jobs not containing the word
|
p4 jobs -e "(fast|quick)&date>1998/03/14" |
List all jobs that contain the word |
p4 jobs -e "fast|quick" //depot/proj/... |
List all jobs that have the word |