summaryrefslogtreecommitdiffstats
path: root/documentation/getting-started/eclipse/html/getting-started/repositories-tags-and-branches.html
diff options
context:
space:
mode:
Diffstat (limited to 'documentation/getting-started/eclipse/html/getting-started/repositories-tags-and-branches.html')
-rw-r--r--documentation/getting-started/eclipse/html/getting-started/repositories-tags-and-branches.html173
1 files changed, 173 insertions, 0 deletions
diff --git a/documentation/getting-started/eclipse/html/getting-started/repositories-tags-and-branches.html b/documentation/getting-started/eclipse/html/getting-started/repositories-tags-and-branches.html
new file mode 100644
index 0000000000..d813948375
--- /dev/null
+++ b/documentation/getting-started/eclipse/html/getting-started/repositories-tags-and-branches.html
@@ -0,0 +1,173 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>2.4.1. Repositories, Tags, and Branches</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="Getting Started With Yocto Project">
8<link rel="up" href="git.html" title="2.4. Git">
9<link rel="prev" href="git.html" title="2.4. Git">
10<link rel="next" href="basic-commands.html" title="2.4.2. Basic Commands">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="2.4.1. Repositories, Tags, and Branches">
13<div class="titlepage"><div><div><h3 class="title">
14<a name="repositories-tags-and-branches"></a>2.4.1. Repositories, Tags, and Branches</h3></div></div></div>
15<p>
16 As mentioned briefly in the previous section and also in the
17 "<a class="link" href="workflows.html" title="2.3. Workflows">Workflows</a>" section,
18 the Yocto Project maintains source repositories at
19 <a class="ulink" href="http://git.yoctoproject.org/cgit.cgi" target="_self">http://git.yoctoproject.org/cgit.cgi</a>.
20 If you look at this web-interface of the repositories, each item
21 is a separate Git repository.
22 </p>
23<p>
24 Git repositories use branching techniques that track content
25 change (not files) within a project (e.g. a new feature or updated
26 documentation).
27 Creating a tree-like structure based on project divergence allows
28 for excellent historical information over the life of a project.
29 This methodology also allows for an environment from which you can
30 do lots of local experimentation on projects as you develop
31 changes or new features.
32 </p>
33<p>
34 A Git repository represents all development efforts for a given
35 project.
36 For example, the Git repository <code class="filename">poky</code> contains
37 all changes and developments for Poky over the course of its
38 entire life.
39 That means that all changes that make up all releases are captured.
40 The repository maintains a complete history of changes.
41 </p>
42<p>
43 You can create a local copy of any repository by "cloning" it
44 with the <code class="filename">git clone</code> command.
45 When you clone a Git repository, you end up with an identical
46 copy of the repository on your development system.
47 Once you have a local copy of a repository, you can take steps to
48 develop locally.
49 For examples on how to clone Git repositories, see the
50 "<a class="link" href="../dev-manual/working-with-yocto-project-source-files.html" target="_self">Working With Yocto Project Source Files</a>"
51 section in the Yocto Project Development Tasks Manual.
52 </p>
53<p>
54 It is important to understand that Git tracks content change and
55 not files.
56 Git uses "branches" to organize different development efforts.
57 For example, the <code class="filename">poky</code> repository has
58 several branches that include the current "sumo"
59 branch, the "master" branch, and many branches for past
60 Yocto Project releases.
61 You can see all the branches by going to
62 <a class="ulink" href="http://git.yoctoproject.org/cgit.cgi/poky/" target="_self">http://git.yoctoproject.org/cgit.cgi/poky/</a> and
63 clicking on the
64 <code class="filename"><a class="ulink" href="http://git.yoctoproject.org/cgit.cgi/poky/refs/heads" target="_self">[...]</a></code>
65 link beneath the "Branch" heading.
66 </p>
67<p>
68 Each of these branches represents a specific area of development.
69 The "master" branch represents the current or most recent
70 development.
71 All other branches represent offshoots of the "master" branch.
72 </p>
73<p>
74 When you create a local copy of a Git repository, the copy has
75 the same set of branches as the original.
76 This means you can use Git to create a local working area
77 (also called a branch) that tracks a specific development branch
78 from the upstream source Git repository.
79 in other words, you can define your local Git environment to
80 work on any development branch in the repository.
81 To help illustrate, consider the following example Git commands:
82 </p>
83<pre class="literallayout">
84 $ cd ~
85 $ git clone git://git.yoctoproject.org/poky
86 $ cd poky
87 $ git checkout -b sumo origin/sumo
88 </pre>
89<p>
90 In the previous example after moving to the home directory, the
91 <code class="filename">git clone</code> command creates a
92 local copy of the upstream <code class="filename">poky</code> Git repository.
93 By default, Git checks out the "master" branch for your work.
94 After changing the working directory to the new local repository
95 (i.e. <code class="filename">poky</code>), the
96 <code class="filename">git checkout</code> command creates
97 and checks out a local branch named "sumo", which
98 tracks the upstream "origin/sumo" branch.
99 Changes you make while in this branch would ultimately affect
100 the upstream "sumo" branch of the
101 <code class="filename">poky</code> repository.
102 </p>
103<p>
104 It is important to understand that when you create and checkout a
105 local working branch based on a branch name,
106 your local environment matches the "tip" of that particular
107 development branch at the time you created your local branch,
108 which could be different from the files in the "master" branch
109 of the upstream repository.
110 In other words, creating and checking out a local branch based on
111 the "sumo" branch name is not the same as
112 cloning and checking out the "master" branch if the repository.
113 Keep reading to see how you create a local snapshot of a Yocto
114 Project Release.
115 </p>
116<p>
117 Git uses "tags" to mark specific changes in a repository.
118 Typically, a tag is used to mark a special point such as the final
119 change before a project is released.
120 You can see the tags used with the <code class="filename">poky</code> Git
121 repository by going to
122 <a class="ulink" href="http://git.yoctoproject.org/cgit.cgi/poky/" target="_self">http://git.yoctoproject.org/cgit.cgi/poky/</a> and
123 clicking on the
124 <code class="filename"><a class="ulink" href="http://git.yoctoproject.org/cgit.cgi/poky/refs/tags" target="_self">[...]</a></code>
125 link beneath the "Tag" heading.
126 </p>
127<p>
128 Some key tags for the <code class="filename">poky</code> are
129 <code class="filename">jethro-14.0.3</code>,
130 <code class="filename">morty-16.0.1</code>,
131 <code class="filename">pyro-17.0.0</code>, and
132 <code class="filename">sumo-20.0.0</code>.
133 These tags represent Yocto Project releases.
134 </p>
135<p>
136 When you create a local copy of the Git repository, you also
137 have access to all the tags in the upstream repository.
138 Similar to branches, you can create and checkout a local working
139 Git branch based on a tag name.
140 When you do this, you get a snapshot of the Git repository that
141 reflects the state of the files when the change was made associated
142 with that tag.
143 The most common use is to checkout a working branch that matches
144 a specific Yocto Project release.
145 Here is an example:
146 </p>
147<pre class="literallayout">
148 $ cd ~
149 $ git clone git://git.yoctoproject.org/poky
150 $ cd poky
151 $ git fetch --all --tags --prune
152 $ git checkout tags/pyro-17.0.0 -b my-pyro-17.0.0
153 </pre>
154<p>
155 In this example, the name of the top-level directory of your
156 local Yocto Project repository is <code class="filename">poky</code>.
157 After moving to the <code class="filename">poky</code> directory, the
158 <code class="filename">git fetch</code> command makes all the upstream
159 tags available locally in your repository.
160 Finally, the <code class="filename">git checkout</code> command
161 creates and checks out a branch named "my-pyro-17.0.0" that is
162 based on the specific change upstream in the repository
163 associated with the "pyro-17.0.0" tag.
164 The files in your repository now exactly match that particular
165 Yocto Project release as it is tagged in the upstream Git
166 repository.
167 It is important to understand that when you create and
168 checkout a local working branch based on a tag, your environment
169 matches a specific point in time and not the entire development
170 branch (i.e. the "tip" of the branch).
171 </p>
172</div></body>
173</html>
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2024-05-01 07:30:22 +0000