As mentioned briefly in the previous section and also in the "Workflows" section, the Yocto Project maintains source repositories at http://git.yoctoproject.org/cgit.cgi. If you look at this web-interface of the repositories, each item is a separate Git repository.
Git repositories use branching techniques that track content change (not files) within a project (e.g. a new feature or updated documentation). Creating a tree-like structure based on project divergence allows for excellent historical information over the life of a project. This methodology also allows for an environment from which you can do lots of local experimentation on projects as you develop changes or new features.
A Git repository represents all development efforts for a given
project.
For example, the Git repository poky
contains
all changes and developments for Poky over the course of its
entire life.
That means that all changes that make up all releases are captured.
The repository maintains a complete history of changes.
You can create a local copy of any repository by "cloning" it
with the git clone
command.
When you clone a Git repository, you end up with an identical
copy of the repository on your development system.
Once you have a local copy of a repository, you can take steps to
develop locally.
For examples on how to clone Git repositories, see the
"Working With Yocto Project Source Files"
section in the Yocto Project Development Tasks Manual.
It is important to understand that Git tracks content change and
not files.
Git uses "branches" to organize different development efforts.
For example, the poky
repository has
several branches that include the current "sumo"
branch, the "master" branch, and many branches for past
Yocto Project releases.
You can see all the branches by going to
http://git.yoctoproject.org/cgit.cgi/poky/ and
clicking on the
[...]
link beneath the "Branch" heading.
Each of these branches represents a specific area of development. The "master" branch represents the current or most recent development. All other branches represent offshoots of the "master" branch.
When you create a local copy of a Git repository, the copy has the same set of branches as the original. This means you can use Git to create a local working area (also called a branch) that tracks a specific development branch from the upstream source Git repository. in other words, you can define your local Git environment to work on any development branch in the repository. To help illustrate, consider the following example Git commands:
$ cd ~ $ git clone git://git.yoctoproject.org/poky $ cd poky $ git checkout -b sumo origin/sumo
In the previous example after moving to the home directory, the
git clone
command creates a
local copy of the upstream poky
Git repository.
By default, Git checks out the "master" branch for your work.
After changing the working directory to the new local repository
(i.e. poky
), the
git checkout
command creates
and checks out a local branch named "sumo", which
tracks the upstream "origin/sumo" branch.
Changes you make while in this branch would ultimately affect
the upstream "sumo" branch of the
poky
repository.
It is important to understand that when you create and checkout a local working branch based on a branch name, your local environment matches the "tip" of that particular development branch at the time you created your local branch, which could be different from the files in the "master" branch of the upstream repository. In other words, creating and checking out a local branch based on the "sumo" branch name is not the same as cloning and checking out the "master" branch if the repository. Keep reading to see how you create a local snapshot of a Yocto Project Release.
Git uses "tags" to mark specific changes in a repository.
Typically, a tag is used to mark a special point such as the final
change before a project is released.
You can see the tags used with the poky
Git
repository by going to
http://git.yoctoproject.org/cgit.cgi/poky/ and
clicking on the
[...]
link beneath the "Tag" heading.
Some key tags for the poky
are
jethro-14.0.3
,
morty-16.0.1
,
pyro-17.0.0
, and
sumo-20.0.0
.
These tags represent Yocto Project releases.
When you create a local copy of the Git repository, you also have access to all the tags in the upstream repository. Similar to branches, you can create and checkout a local working Git branch based on a tag name. When you do this, you get a snapshot of the Git repository that reflects the state of the files when the change was made associated with that tag. The most common use is to checkout a working branch that matches a specific Yocto Project release. Here is an example:
$ cd ~ $ git clone git://git.yoctoproject.org/poky $ cd poky $ git fetch --all --tags --prune $ git checkout tags/pyro-17.0.0 -b my-pyro-17.0.0
In this example, the name of the top-level directory of your
local Yocto Project repository is poky
.
After moving to the poky
directory, the
git fetch
command makes all the upstream
tags available locally in your repository.
Finally, the git checkout
command
creates and checks out a branch named "my-pyro-17.0.0" that is
based on the specific change upstream in the repository
associated with the "pyro-17.0.0" tag.
The files in your repository now exactly match that particular
Yocto Project release as it is tagged in the upstream Git
repository.
It is important to understand that when you create and
checkout a local working branch based on a tag, your environment
matches a specific point in time and not the entire development
branch (i.e. the "tip" of the branch).