summaryrefslogtreecommitdiffstats
path: root/documentation/dev-manual
diff options
context:
space:
mode:
authorScott Rifenbark <srifenbark@gmail.com>2017-06-15 14:14:21 -0700
committerRichard Purdie <richard.purdie@linuxfoundation.org>2017-06-22 09:16:44 +0100
commit98ba0cd4769cb6213ca71dca1d874b673fb7844f (patch)
treeff69b3d6a31795289901b094de9e7d583f1a4e5f /documentation/dev-manual
parentf2db665b7877a3640b180af46d1a2c260ede7210 (diff)
downloadpoky-98ba0cd4769cb6213ca71dca1d874b673fb7844f.tar.gz
dev-manual: Created "Working With Git Repositories" section
Fixes [YOCTO #11630] This new section has three new procedures for now: 1) cloning the poky repository, 2) checking out a branch based on an upstream repository branch name, and 3) checking out a branch based on an upstream tag name. More to be added for other key repositories. (From yocto-docs rev: 4cbcd952ba395b19be5374470a95630a4bc6ffa7) Signed-off-by: Scott Rifenbark <srifenbark@gmail.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation/dev-manual')
-rw-r--r--documentation/dev-manual/dev-manual-start.xml204
1 files changed, 204 insertions, 0 deletions
diff --git a/documentation/dev-manual/dev-manual-start.xml b/documentation/dev-manual/dev-manual-start.xml
index df622f93b9..11b536a8df 100644
--- a/documentation/dev-manual/dev-manual-start.xml
+++ b/documentation/dev-manual/dev-manual-start.xml
@@ -286,6 +286,210 @@
286 </para> 286 </para>
287</section> 287</section>
288 288
289<section id='working-with-git-repositories'>
290 <title>Working With Git Repositories</title>
291
292 <para>
293 This section contains procedures for establishing Git repositories
294 local to your development system.
295 You use these local repositories to work on projects.
296 <note>
297 For concepts and introductory information about Git as it is used
298 in the Yocto Project, see the
299 "<ulink url='&YOCTO_DOCS_REF_URL;#git'>Git</ulink>"
300 section in the Yocto Project Reference Manual.
301 </note>
302 </para>
303
304 <section id='cloning-the-poky-repository'>
305 <title>Cloning the <filename>poky</filename> Repository</title>
306
307 <para>
308 Follow these steps to create a local version of the
309 upstream
310 <ulink url='&YOCTO_DOCS_REF_URL;#poky'><filename>poky</filename></ulink>
311 Git repository.
312 <orderedlist>
313 <listitem><para>
314 <emphasis>Set Your Directory:</emphasis>
315 Be in the directory where you want to create your local
316 copy of poky.
317 </para></listitem>
318 <listitem><para>
319 <emphasis>Clone the Repository:</emphasis>
320 The following command clones the repository and uses
321 the default name "poky" for your local repository:
322 <literallayout class='monospaced'>
323 $ git clone git://git.yoctoproject.org/poky
324 Cloning into 'poky'...
325 remote: Counting objects: 367178, done.
326 remote: Compressing objects: 100% (88161/88161), done.
327 remote: Total 367178 (delta 272761), reused 366942 (delta 272525)
328 Receiving objects: 100% (367178/367178), 133.26 MiB | 6.40 MiB/s, done.
329 Resolving deltas: 100% (272761/272761), done.
330 Checking connectivity... done.
331 </literallayout>
332 Once the repository is created, you can change to that
333 directory and check its status and list its branches:
334 <literallayout class='monospaced'>
335 $ cd ~/poky
336 $ git status
337 On branch master
338 Your branch is up-to-date with 'origin/master'.
339 nothing to commit, working directory clean
340 $ git branch
341 * master
342 </literallayout>
343 Your local repository of poky is identical to the
344 upstream poky repository at the time from which it was
345 cloned.
346 By default, Git creates the "master" branch and checks
347 it out.
348 </para></listitem>
349 </orderedlist>
350 </para>
351 </section>
352
353 <section id='checking-out-by-branch-in-poky'>
354 <title>Checking Out by Branch in Poky</title>
355
356 <para>
357 When you clone the upstream poky repository, you have access to
358 all its development branches.
359 Each development branch in a repository is unique as it forks
360 off the repositories "master" branch.
361 To see and use the files of any branch locally, you need to
362 know the branch name and then checkout the branch.
363 <orderedlist>
364 <listitem><para>
365 <emphasis>Switch to the Poky Directory:</emphasis>
366 If you have a local poky Git repository, switch to that
367 directory.
368 If you do not have the local copy of poky, see the
369 "<link linkend='cloning-the-poky-repository'>Cloning the <filename>poky</filename> Repository</link>"
370 section.
371 </para></listitem>
372 <listitem><para>
373 <emphasis>Determine Existing Branch Names:</emphasis>
374 <literallayout class='monospaced'>
375 $ git branch -a
376 * master
377 remotes/origin/1.1_M1
378 remotes/origin/1.1_M2
379 remotes/origin/1.1_M3
380 remotes/origin/1.1_M4
381 remotes/origin/1.2_M1
382 remotes/origin/1.2_M2
383 remotes/origin/1.2_M3
384 .
385 .
386 .
387 remotes/origin/master-next
388 remotes/origin/master-next2
389 remotes/origin/morty
390 remotes/origin/pinky
391 remotes/origin/purple
392 remotes/origin/pyro
393 </literallayout>
394 </para></listitem>
395 <listitem><para>
396 <emphasis>Checkout the Branch:</emphasis>
397 Checkout the branch in which you want to work.
398 For example, to access the files for the Yocto Project
399 2.3 Release (Pyro), use the following command:
400 <literallayout class='monospaced'>
401 $ git checkout -b origin/pyro
402 Switched to a new branch 'origin/pyro'
403 </literallayout>
404 The previous command checks out the "pyro" branch and
405 reports that the branch is tracking the upstream
406 "origin/pyro" branch.</para>
407
408 <para>The following command displays the branches
409 that are now part of your local poky repository.
410 The asterisk character indicates the branch that is
411 currently checked out for work:
412 <literallayout class='monospaced'>
413 $ git branch
414 master
415 * origin/pyro
416 </literallayout>
417 </para></listitem>
418 </orderedlist>
419 </para>
420 </section>
421
422 <section id='checkout-out-by-tag-in-poky'>
423 <title>Checking Out by Tag in Poky</title>
424
425 <para>
426 Similar to branches, the upstream repository has tags used
427 to mark significant commits such as a completed release or
428 stage of a release.
429 You might want to set up a local branch based on one of those
430 points in the repository.
431 The process is similar to checking out by branch name except you
432 use tag names.
433 <orderedlist>
434 <listitem><para>
435 <emphasis>Switch to the Poky Directory:</emphasis>
436 If you have a local poky Git repository, switch to that
437 directory.
438 If you do not have the local copy of poky, see the
439 "<link linkend='cloning-the-poky-repository'>Cloning the <filename>poky</filename> Repository</link>"
440 section.
441 </para></listitem>
442 <listitem><para>
443 <emphasis>Fetch the Tag Names:</emphasis>
444 To checkout the branch based on a tag name, you need to
445 fetch the upstream tags into your local repository:
446 <literallayout class='monospaced'>
447 $ git fetch --tags
448 $
449 </literallayout>
450 </para></listitem>
451 <listitem><para>
452 <emphasis>List the Tag Names:</emphasis>
453 You can list the tag names now:
454 <literallayout class='monospaced'>
455 $ git tag
456 1.1_M1.final
457 1.1_M1.rc1
458 1.1_M1.rc2
459 1.1_M2.final
460 1.1_M2.rc1
461 .
462 .
463 .
464 yocto-2.2
465 yocto-2.2.1
466 yocto-2.3
467 yocto_1.5_M5.rc8
468 </literallayout>
469 </para></listitem>
470 <listitem><para>
471 <emphasis>Checkout the Branch:</emphasis>
472 <literallayout class='monospaced'>
473 $ git checkout tags/2.2_M2 -b my_yocto_2.2_M2
474 Switched to a new branch 'my_yocto_2.2_M2'
475 $ git branch
476 master
477 * my_yocto_2.2_M2
478 </literallayout>
479 The previous command creates and checks out a local
480 branch named "my_yocto_2.2_M2", which is based on
481 the commit in the upstream poky repository that has
482 the same tag.
483 The files you have available locally when you are
484 checked out to that branch are a snapshot of the
485 "morty" development branch at the point where
486 milestone two was reached.
487 </para></listitem>
488 </orderedlist>
489 </para>
490 </section>
491</section>
492
289<section id='building-images'> 493<section id='building-images'>
290 <title>Building Images</title> 494 <title>Building Images</title>
291 495