Working With Repositories¶

zendev can keep track of all the repositories associated with a project. Groups of repositories are described by simple JSON manifests that can be added to an environment. zendev can then help you navigate to repositories on the filesystem, clone new repos, pull down changes and rebase your feature branches, push your existing changes, etc.

Manifests¶

A manifest is a JSON file of this structure:

{
    "repos": {
        "<PATH>": {
          "repo": "<OWNER>/<REPONAME>",
          "ref": "<BRANCH>"
        },
        ...
    }
}

PATH is the path relative to your environment’s source root where the repository should be cloned. OWNER and REPONAME are the GitHub repository owner and name, respectively. BRANCH is the branch that should be checked out.

Both the Zenoss build system and zendev use the same manifest structure; it effectively makes portable the source tree necessary to build or develop a project.

The manifests representing the Zenoss and Control Plane projects live in the GitHub repository zenoss/platform-build, in the manifests directory. This repository is checked out as a part of every zendev environment, and can be found in $(zendev root)/build.

Adding Manifests¶

You can add a manifest to a zendev environment with the add command:

# Add a local manifest
zendev add /path/to/manifest.json

# Add a remote manifest
zendev add http://host/manifest2.json

Navigating Source¶

zendev provides a utility allowing you to cd directly to any repository described in the added manifests using regex matching. This is (appropriately) provided by the cd command. For example:

# cd to $(zendev root)/src/golang/src/github.com/zenoss/serviced
zendev cd serviced

# cd to $(zendev root)/src/golang/src/github.com/zenoss/metricshipper
zendev cd shipper

# cd to $(zendev root)/src/zenpacks/ZenPacks.zenoss.LDAPMonitor
zendev cd ldap

cdz is an alias for zendev cd installed by the zendev bootstrap.

Adding Repositories¶

Repositories can be added from the environment using the addrepo command.

# adds the github repo ZenPacks.zenoss.LDAPMonitor
# the first arg is the destination path
# the second arg is the repo on github
# the third arg is an optional branch or git ref
zendev addrepo zenpacks/ZenPacks.zenoss.LDAPMonitor zenoss/ZenPacks.zenoss.LDAPMonitor [branch]

Removing Repositories¶

Repositories can be removed from the environment using the rm command, again using regex matching:

# Removes, e.g., src/zenpacks/ZenPacks.zenoss.LDAPMonitor
zendev rm ldap

Generating Manifests¶

Although simple to create by hand, manifests can be generated using the freeze command, which will output your environment’s current repository state as a manifest, including current branches. Simply issue the command:

zendev freeze > mynewmanifest.json

This enables you to describe the branches necessary to, e.g., build a particular release or feature sandbox that may have changes spanning several repositories.

Pulling/Pushing Changes¶

zendev sync will clone any repositories that haven’t been cloned yet, and pull any changes from and push any locally committed changes to GitHub. Repositories can be specified like most other commands, using string matching. Default is to sync all repositories.

Status¶

zendev prints a table describing current branch and change status for specified (or all) repositories as a result of the status command:

# Default: print status for repositories with uncommitted changes
zendev status

# Print status for repositories matching one or more strings
zendev status metric ldap

# Print status for all repositories
zendev status -a

Tagging Manifests¶

Repository states can be tagged and then restored later. To save the state of your environment (committed code only), use zendev tag:

zendev tag myniftyfeature

It can then be restored by you or another person:

zendev restore myniftyfeature

If you want your tagged environment to be frozen to a particular commit (instead of a branch), you can pass --strict:

zendev tag --strict nightly-build-123

Tags can be removed just as easily (tags are global to all zendev users; be a good citizen):

zendev tag -D myniftyfeature

Or you can override a tag with your current state:

zendev tag --force myniftyfeature

You can see the changes between two tags across all repos with zendev changelog:

# Show difference between a tag and current state
zendev changelog from-tag

# Show difference between two tags
zendev changelog from-tag to-tag

Finally, you can list all tags with zendev tag --list.

Cloning Directly From a Manifest¶

You don’t have to have an environment set up to turn a manifest into a source tree. You can use zendev clone.

# Clone from a local manifest to ./src
zendev clone ./src -m /path/to/manifest.json ./src

# Clone from a remote manifest
zendev clone ./src -m http://host/manifest.json ./src

# Clone only the last commit from several manifests
zendev clone --shallow ./src -m /path/to/manifest1.json -m /path/to/manifest2.json

# Clone from a manifest tag
zendev clone --shallow ./src -t develop