p4 jobs

List jobs known to the Helix Core Server.

Syntax

p4 [g-opts] jobs [-e jobview] [-i -l -r] [-m max] [file[rev] ...]
p4 [g-opts] jobs -R

Syntax conventions

Description

When called without any arguments, p4 jobs lists all jobs stored in Helix Server. 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 Helix Server 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

`-e jobview`	List only those jobs that match the criteria specified by jobview. See 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` option, the last `max` jobs are included.
`-r`	Display jobs in reverse alphabetical order by job name.
`-R`	Rebuild the job table and re-index each job.
`g-opts`	See Global options.

Usage Notes

Can File Arguments Use Revision Specifier? Can File Arguments Use Revision Range? Minimal Access Level Required

Can File Arguments Use Revision Specifier?	Can File Arguments Use Revision Range?	Minimal Access Level Required
Yes	Yes	`list` available to an operator user

Yes

list

available to an operator user

The command returns no output if there is no object to report on.

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 job views 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 job view 'word1 word2 ... wordN' can be used to find jobs that contain the complete set of word1 through wordN.

Examples:

p4 jobs -e "ReportedDate=2018/09/14 OwnedBy=mgaria FixVerifiedBy=jsmith"
p4 jobs -e "ReportedDate=2018/09/14 mgaria jsmith"
p4 jobs -e "25* path QA closed job004* 2014* limit*"

To find jobs that contain all of the terms (boolean AND), separate the terms with the ampersand (&) or a space character.

To find jobs that contain any of the terms (boolean OR), separate the terms with the “|” character.

Boolean operator precedence
highest	whatever is in parentheses ()
	& for AND
	\| for OR
lowest	space for AND

Search results can be narrowed by matching values within specific fields with the job view syntax "fieldname=value". The value must be a single token, including both alphanumeric characters and punctuation.

The wildcard "*" allows for partial word matches. The job view "fieldname=string*" matches "string", "stringy", "stringlike", and so on.

Date fields can be matched by expressing the job view 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).

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 Job Views
`word`	The equality operator (`=`) must match the value in the word field exactly. The relational 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 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 `text` field `ShortDescription` that contains only the phrase `gui bug`, and the job view is "`ShortDesc<filter`", the job matches the job view, 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 relational operators perform comparisons in ASCII order.
`date`	Dates are matched chronologically. If a specific time is not provided, the operators `=`, `<=`, and `>=` 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 job view to be linked to a particular user. After a user enters a job view into this field, any changelists he creates automatically list jobs that match the job view in this field. The jobs that are fixed by the changelist can be left in the form, and the jobs that are not 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 Helix Server 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 are using the default Helix Server job naming scheme (jobs numbered like job001394), 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 job view "field=*"; any non-null value for field matches.
When querying for jobs using the -e jobview 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.

Limitations

Job views 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 job view that matches this "deleted field" value.
The job view NOT operator (^) can be used only after an AND within the job view. Thus, the job views "gui ^name=joe" and "gui&^name=joe" are valid, while the job views "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 job view and logically ANDed with all jobs NOT containing the string "unwanted".

Likewise, because the job view "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=*"
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 `//depot/proj/file`.
`p4 jobs -i //depot/proj/file`	List all jobs attached to changelists that include revisions of `//depot/proj/file` or revisions of files that were integrated into `//depot/proj/file`.
`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`", "`window.c`", "`Windows`", in any field. The quotation marks are used to prevent the local shell from expanding the "`*`" on the command line.
`p4 jobs -e window.c`	List all jobs referring to `window.c` in any field.
`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 at your site (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 job view that includes jobs matching the job view in all new changelists	`p4 user`