Skip to content

Checkout a git revision

Clones the repository Clarive hosts into the job directory and checks out the revision the job carries. It belongs to the older job model, the one where a job was built from named revisions rather than from changesets, and it reads that older list.

Read the next section before you place it. In a job built from changesets, which is how jobs are built today, the list this op reads is empty and the op does nothing at all. The current equivalents are Checkout Job Items for the changed files, Checkout Job Environment (all repos) for whole repositories, and Clone Job Repositories when you want the top revision of each repository.

each entry in the job content list is it a git revision? no logged as debug, then skipped yes delete the target directory if it exists clone the hosted repository into it check out the revision by name

No configuration

The op has no form. Drop it into a job rule and it runs with the job's own content list as its only input. The op-level settings in the rule designer still apply: Name, Enabled, Run Forward, Run Rollback, Error Handling and Return Key behave as they do on any op.

Return Key is worth ignoring here. The op returns nothing, so the key it writes into the stash holds an empty value.

What it does per revision

Every entry in the job's content list is examined, including the dependency entries. Each one is dumped to the job log at debug level before its type is tested, so an entry that is not a git revision leaves that one line behind and nothing else.

For each git revision entry:

  • The target directory is <job root>/<project name>/<repository name>. Note the repository name, not its Relative path, which is what Checkout Job Items uses. The two ops do not necessarily write to the same place.
  • An existing directory at that address is deleted outright before the clone. Anything an earlier op wrote there is gone, with no confirmation and no backup.
  • The directory is then created again along with any parent that is missing, the job root included, so the op does not need the job directory to be there already.
  • The clone source is the repository Clarive hosts on its own disk, so what you get is whatever Clarive has synchronised. No external remote is contacted.
  • The clone is complete. The .git directory stays in place, unlike Checkout Job Items, which leaves only the working files. There is no shallow option, so a repository with a long history is copied in full every time.
  • The revision name is then checked out. It is used exactly as recorded on the revision resource, so a tag name, a branch name or a commit id all work, whichever the revision holds.
  • The checkout is always a plain checkout. The revision is never merged into the environment branch, whatever the job type.

Logging, failure and rollback

One line per revision is written at info level: the cloning line, which names the project, the repository, the path the clone is read from and the destination directory. The rest is written at debug level, and the job log hides debug entries unless you open it in debug mode. That debug output is the content entry itself, one line for every tag in the repository, the job root path on a line of its own, and a line repeating the project, repository, source path and revision. A repository carrying a few hundred tags therefore puts a few hundred lines into the log for each revision it checks out. None of it is configurable.

A revision name the repository cannot resolve fails the checkout and errors the job. The clone that runs first is not checked at all, so a clone that fails is not reported where it happens. The job carries on to the checkout and errors there instead, on a directory that has nothing in it. Set Error Handling to trap or ignore errors when the job should survive a failed checkout.

The clone step calls the git found on the Clarive server's path, not the Git binary configured in the Git settings. On a server where the two differ, the clone uses the one on the path.

There is no undo. Left at its defaults the op runs again during a rollback pass, which wipes and re-clones the same directories rather than putting anything back. Untick Run Rollback when that is not what you want.

Combining with other ops

In an older revision-based job, this op comes first and Fill job elements comes after it. That pairing is what produces the element list the job log shows.

In a job built from changesets, reach for Load Job Items into Stash followed by Checkout Job Items. If you need the .git directory in the job directory, which is the one thing this op gives you that the changeset checkout does not, run Run command or local script with your own clone command instead, or use Clone Job Repositories.

Once the files are on disk, Git Timesync can restore the commit dates the clone overwrote, and Ship File Remotely can move them to a target server.

Example

There is nothing to fill in. A revision-based job rule places the op between the step that creates the job directory and the step that builds the element list.

Checkout a git revision      (no fields)
  Fill job elements
  Run command or local script    mvn -q package