| commit | 115b41f702ad76ca137eb3fc6f7ab42a2b04fc33 | [log] [tgz] |
|---|---|---|
| author | Nicolas Lacasse <nlacasse@google.com> | Mon Feb 29 14:57:49 2016 -0800 |
| committer | Nicolas Lacasse <nlacasse@google.com> | Mon Feb 29 14:57:49 2016 -0800 |
| tree | f73203f08ec804fec52eab00f738fc06231d93cf | |
| parent | f95ddf59c0b184acd69b3d5e751866434dba9a2e [diff] |
jiri: Add JIRI_ROOT/.jiri_root/bin to path when building a new jirix. The jiri tool invokes subcommands based on the PATH. In almost all cases, those subcommands should be the ones installed in $JIRI_ROOT/.jiri_root/bin. When running the jiri *script*, this directory is prepended to the PATH. This CL adds similar behavior to the jiri *binary*, for users who run the binary directly, rather than running the script. Change-Id: Ie2c4796f3490d18b6dddd3e2c4bd9d81ab042642
“Jiri integrates repositories intelligently”
Jiri is a tool for multi-repo development. It supports:
Jiri is open-source. See the contributor guidelines here.
This section explains how to get started with jiri.
First we “bootstrap” jiri so that it can sync and build itself.
Then we create and import a new manifest, which specifies how jiri should manage your projects.
You can get jiri up-and-running in no time with the help of the bootstrap script.
First, pick a jiri root directory. All projects will be synced to subdirectories of the root.
export MY_ROOT=$HOME/myroot
Execute the jiri_bootstrap script, which will fetch and build the jiri tool, and initialize the root directory.
curl -s https://raw.githubusercontent.com/vanadium/go.jiri/master/scripts/bootstrap_jiri | bash -s "$MY_ROOT"
The jiri command line tool will be installed in $MY_ROOT/.jiri_root/scripts/jiri, so add that to your PATH.
export PATH="$MY_ROOT"/.jiri_root/scripts:$PATH
Next, use the jiri import command to import the “minimal” manifest from the vanadium manifest repo. This manifest includes only the projects needed to build the jiri tool itself.
You can see the minimal manifest here. For more information on manifests, read the manifest docs.
cd "$MY_ROOT" jiri import minimal https://vanadium.googlesource.com/manifest
You should now have a file in the root directory called .jiri_manifest, which will contain a single import.
Finally, run jiri update, which will sync all local projects to the revisions listed in the manifest (which in this case will be HEAD).
jiri update
You should now see the jiri project and dependencies in $MY_ROOT/release/go/src/v.io, and the vanadium manifest repo in $MY_ROOT/manifest.
Running jiri update again will sync the local repos to the remotes, and rebuild the jiri tool.
Now that jiri is able to sync and build itself, we must tell it how to manage your projects.
In order for jiri to manage a set of projects, those projects must be listed in a manifest, and that manifest must be hosted in a git repo.
If you already have a manifest hosted in a git repo, you can import that manifest the same way we imported the “minimal” manifest.
For example, if your manifest is called “my_manifest” and is in a repo hosted at “https://github.com/my_org/manifests”, then you can import that manifest as follows.
jiri import my_manifest https://github.com/my_org/manifests
The rest of this section walks through how to create a manifest from scratch, host it from a local git repo, and get jiri to manage it.
Suppose that the project you want jiri to manage is the “Hello-World” repo located at https://github.com/Test-Octowin/Hello-World.
First we‘ll create a new git repo to host the manifest we’ll be writing.
mkdir -p /tmp/my_manifest_repo cd /tmp/my_manifest_repo git init
Next we'll create a manifest and commit it to the manifest repo.
The manifest file will include the Hello-World repo as well as the manifest repo itself.
cat <<EOF > my_manifest
<?xml version="1.0" encoding="UTF-8"?>
<manifest>
<projects>
<project name="Hello-World"
remote="https://github.com/Test-Octowin/Hello-World"
path="helloworld"/>
<project name="manifest"
remote="/tmp/my_manifest_repo"
path="manifest"/>
</projects>
</manifest>
EOF
git add my_manifest
git commit -m "Add my_manifest."
This manifest contains a single project with the name “Hello-World” and the remote of the repo. The path attribute tells jiri to sync this repo inside the helloworld directory.
Normally we would want to push this repo to some remote to make it accessible to other users who want to sync the same projects. For now, however, we'll just refer to the repo by its path in the local filesystem.
Now we just need to import that new manifest and jiri update. Since we don't want the new manifest repo to conflict with the minimal manifest repo, we must pass the -path flag to the import statement.
cd "$MY_ROOT" jiri import -path="my_manifest_repo" my_manifest /tmp/my_manifest_repo jiri update
You should now see the Hello-World repo in $MY_ROOT/helloworld, and your manifest repo in $MY_ROOT/my_manifest_repo.
The jiri help command will print help documentation about the jiri tool and its subcommands.
For general documentation, including a list of subcommands, run jiri help. To find documentation about a specific topic or subcommand, run jiri help <command>.
You can read all the command-line documentation in a single page here: http://godoc.org/v.io/jiri.
TODO(nlacasse): There's a pretty good description of the filesystem layout at jiri help filesystem. Do we want to keep those docs there, or move them here? Maybe figure out a way to include them in both places but only have a single copy in source control.
TODO(nlacasse): There's a brief description of manifests in jiri help manifest, but it needs a lot of improvement. Do we want to keep those docs there, or move them here? Maybe figure out a way to include them in both places but only have a single copy in source control.
TODO(nlacasse): Write me.
TODO(nlacasse): Write me.
Gerrit is a collaborative code-review tool used by many open source projects.
One of the peculiarities of Gerrit is that it expects a changelist to be represented by a single commit. This constrains the way developers may use git to work on their changes. In particular, they must use the --amend flag with all but the first git commit operation and they need to use git rebase to sync their pending code change with the remote master. See Android‘s repo command reference or Go’s contributing instructions for examples of how intricate the workflow for resolving conflicts between the pending code change and the remote master is.
The jiri cl command enables interaction with Gerrit without having to use such a complex and error-prone workflow. With jiri cl, users commit as often as they want on feature branches, and jiri cl handles the hard work of squashing all commits into a single commit and sending to Gerrit.
The rest of this section describes common development operations using jiri cl. The term “CL” (short for “ChangeList”) refers to a set of code changes uploaded for review.
The “master” branch of each local repository is reserved for tracking its remote counterpart. All development should take place on a non-master “feature” branch. Once the code is reviewed and approved, it is merged into the remote master via the Gerrit code review system. The change can then be merged into the local master branch with jiri update.
TODO(nlacasse): dje is changing this behavior. The plan is that “master” will be the default reserved branch for each repo, but that can be overridden with the localbranch attribute in the manifest. Update this section once this change lands.
jiri update
jiri cl new <branch-name>
git add <file1> <file2> ... <fileN>
git commit
jiri update
git checkout <branch-name>
jiri cl sync
git add <file1> <file2> ... <fileN>git commitgit checkout <branch-name>
jiri cl mail
If the CL upload is successful, this will print the URL of the CL hosted on Gerrit. You can add reviewers and comments through the Gerrit web UI at that URL.
Note that there are many useful flags for jiri cl. You can learn about them by running jiri cl --help.
git checkout <branch-name>
jiri cl mail
jiri cl mail
jiri updatejiri cl cleanup <branch-name>Note that deleting the feature branch with git branch -d <branch-name> won't work in general because the git history on the local feature branch differs from the history on the remote master. The local feature branch might have many small commits, while the remote will have the same changes squashed into a single commit. This difference in the history will prevent git from letting you do git branch -d <branch-name>. You can use git branch -D <branch-name>, but that can potentially cause you to lose work if the branch has not been merged into master yet. For this reason, we recommend using jiri cl cleanup to delete the feature branch safely.
TODO(nlacasse): Answer these.
Jiří is a very popular boys name in the Czech Republic.
We pronounce “jiri” like “yiree”.
The actual Czech name Jiří is pronounced something like “yirzhee”.