summaryrefslogtreecommitdiffstats
path: root/documentation
diff options
context:
space:
mode:
authorScott Rifenbark <srifenbark@gmail.com>2017-06-15 11:41:25 -0700
committerRichard Purdie <richard.purdie@linuxfoundation.org>2017-06-22 09:16:44 +0100
commitfcb53beee46fd5b3b600232bef4d6bf7e76ef49e (patch)
treea045ccf00653b0ea5671294bb50df5a5f679b9b2 /documentation
parentc7969c64bb1d8b667efc3c3abe48f9e1bec1d1f2 (diff)
downloadpoky-fcb53beee46fd5b3b600232bef4d6bf7e76ef49e.tar.gz
documentation: Moved "Git" section to the ref-manual
Fixes [YOCTO #11630] The "Git" section in the dev-manual is really about concepts. There are a couple of examples that might or not might be allowed to ultimately stay. I have moved the section to the ref-manual. If those examples get replicated in the new dev-manual, I will update the "Git" section further. For now, however, these remain in this moved section. (From yocto-docs rev: 2e4b87fdab29c13ce0d2314e50c93e37404b6f7e) Signed-off-by: Scott Rifenbark <srifenbark@gmail.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation')
-rw-r--r--documentation/bsp-guide/bsp.xml2
-rw-r--r--documentation/dev-manual/dev-manual-newbie.xml269
-rw-r--r--documentation/dev-manual/dev-manual-start.xml6
-rw-r--r--documentation/kernel-dev/kernel-dev-concepts-appx.xml6
-rw-r--r--documentation/kernel-dev/kernel-dev-examples.xml4
-rw-r--r--documentation/ref-manual/introduction.xml4
-rw-r--r--documentation/ref-manual/migration.xml2
-rw-r--r--documentation/ref-manual/ref-development-environment.xml356
-rw-r--r--documentation/ref-manual/usingpoky.xml2
-rw-r--r--documentation/sdk-manual/sdk-extensible.xml2
-rw-r--r--documentation/yocto-project-qs/yocto-project-qs.xml2
11 files changed, 373 insertions, 282 deletions
diff --git a/documentation/bsp-guide/bsp.xml b/documentation/bsp-guide/bsp.xml
index 7dc7ad37d9..f9fcf10105 100644
--- a/documentation/bsp-guide/bsp.xml
+++ b/documentation/bsp-guide/bsp.xml
@@ -1144,7 +1144,7 @@
1144 1144
1145 <para> 1145 <para>
1146 Designed to have a command interface somewhat like 1146 Designed to have a command interface somewhat like
1147 <ulink url='&YOCTO_DOCS_DEV_URL;#git'>Git</ulink>, each 1147 <ulink url='&YOCTO_DOCS_REF_URL;#git'>Git</ulink>, each
1148 tool is structured as a set of sub-commands under a 1148 tool is structured as a set of sub-commands under a
1149 top-level command. 1149 top-level command.
1150 The top-level command (<filename>yocto-bsp</filename> 1150 The top-level command (<filename>yocto-bsp</filename>
diff --git a/documentation/dev-manual/dev-manual-newbie.xml b/documentation/dev-manual/dev-manual-newbie.xml
index c2147b39e7..97e2590763 100644
--- a/documentation/dev-manual/dev-manual-newbie.xml
+++ b/documentation/dev-manual/dev-manual-newbie.xml
@@ -167,7 +167,7 @@
167 with the OpenEmbedded build system is advisable. 167 with the OpenEmbedded build system is advisable.
168 Of the SCMs BitBake supports, the 168 Of the SCMs BitBake supports, the
169 Yocto Project team strongly recommends using 169 Yocto Project team strongly recommends using
170 <link linkend='git'>Git</link>. 170 <ulink url='&YOCTO_DOCS_REF_URL;#git'>Git</ulink>.
171 Git is a distributed system that is easy to backup, 171 Git is a distributed system that is easy to backup,
172 allows you to work remotely, and then connects back to the 172 allows you to work remotely, and then connects back to the
173 infrastructure. 173 infrastructure.
@@ -306,7 +306,7 @@
306 This section summarizes the key recommendations described in the 306 This section summarizes the key recommendations described in the
307 previous sections: 307 previous sections:
308 <itemizedlist> 308 <itemizedlist>
309 <listitem><para>Use <link linkend='git'>Git</link> 309 <listitem><para>Use <ulink url='&YOCTO_DOCS_REF_URL;#git'>Git</ulink>
310 as the source control system.</para></listitem> 310 as the source control system.</para></listitem>
311 <listitem><para>Maintain your Metadata in layers that make sense 311 <listitem><para>Maintain your Metadata in layers that make sense
312 for your situation. 312 for your situation.
@@ -354,269 +354,6 @@
354 </section> 354 </section>
355</section> 355</section>
356 356
357<section id='git'>
358 <title>Git</title>
359
360 <para>
361 The Yocto Project makes extensive use of Git,
362 which is a free, open source distributed version control system.
363 Git supports distributed development, non-linear development, and can handle large projects.
364 It is best that you have some fundamental understanding of how Git tracks projects and
365 how to work with Git if you are going to use the Yocto Project for development.
366 This section provides a quick overview of how Git works and provides you with a summary
367 of some essential Git commands.
368 </para>
369
370 <para>
371 For more information on Git, see
372 <ulink url='http://git-scm.com/documentation'></ulink>.
373 If you need to download Git, go to <ulink url='http://git-scm.com/download'></ulink>.
374 </para>
375
376 <section id='repositories-tags-and-branches'>
377 <title>Repositories, Tags, and Branches</title>
378
379 <para>
380 As mentioned earlier in the section
381 "<ulink url='&YOCTO_DOCS_REF_URL;#yocto-project-repositories'>Yocto Project Source Repositories</ulink>",
382 the Yocto Project maintains source repositories at
383 <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink>.
384 If you look at this web-interface of the repositories, each item is a separate
385 Git repository.
386 </para>
387
388 <para>
389 Git repositories use branching techniques that track content change (not files)
390 within a project (e.g. a new feature or updated documentation).
391 Creating a tree-like structure based on project divergence allows for excellent historical
392 information over the life of a project.
393 This methodology also allows for an environment from which you can do lots of
394 local experimentation on projects as you develop changes or new features.
395 </para>
396
397 <para>
398 A Git repository represents all development efforts for a given project.
399 For example, the Git repository <filename>poky</filename> contains all changes
400 and developments for Poky over the course of its entire life.
401 That means that all changes that make up all releases are captured.
402 The repository maintains a complete history of changes.
403 </para>
404
405 <para>
406 You can create a local copy of any repository by "cloning" it with the Git
407 <filename>clone</filename> command.
408 When you clone a Git repository, you end up with an identical copy of the
409 repository on your development system.
410 Once you have a local copy of a repository, you can take steps to develop locally.
411 For examples on how to clone Git repositories, see the
412 "<link linkend='getting-setup'>Getting Set Up</link>" section.
413 </para>
414
415 <para>
416 It is important to understand that Git tracks content change and
417 not files.
418 Git uses "branches" to organize different development efforts.
419 For example, the <filename>poky</filename> repository has
420 several branches that include the current
421 <filename>&DISTRO_NAME_NO_CAP;</filename> branch, the
422 <filename>master</filename> branch, and many branches for past
423 Yocto Project releases.
424 You can see all the branches by going to
425 <ulink url='&YOCTO_GIT_URL;/cgit.cgi/poky/'></ulink> and
426 clicking on the
427 <filename><ulink url='&YOCTO_GIT_URL;/cgit.cgi/poky/refs/heads'>[...]</ulink></filename>
428 link beneath the "Branch" heading.
429 </para>
430
431 <para>
432 Each of these branches represents a specific area of development.
433 The <filename>master</filename> branch represents the current or most recent
434 development.
435 All other branches represent offshoots of the <filename>master</filename>
436 branch.
437 </para>
438
439 <para>
440 When you create a local copy of a Git repository, the copy has the same set
441 of branches as the original.
442 This means you can use Git to create a local working area (also called a branch)
443 that tracks a specific development branch from the source Git repository.
444 in other words, you can define your local Git environment to work on any development
445 branch in the repository.
446 To help illustrate, here is a set of commands that creates a local copy of the
447 <filename>poky</filename> Git repository and then creates and checks out a local
448 Git branch that tracks the Yocto Project &DISTRO; Release (&DISTRO_NAME;) development:
449 <literallayout class='monospaced'>
450 $ cd ~
451 $ git clone git://git.yoctoproject.org/poky
452 $ cd poky
453 $ git checkout -b &DISTRO_NAME_NO_CAP; origin/&DISTRO_NAME_NO_CAP;
454 </literallayout>
455 In this example, the name of the top-level directory of your local
456 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
457 is "poky" and the name of that local working area (local branch)
458 you just created and checked out is "&DISTRO_NAME_NO_CAP;".
459 The files in your local repository now reflect the same files that
460 are in the "&DISTRO_NAME_NO_CAP;" development branch of the
461 Yocto Project's "poky" upstream repository.
462 It is important to understand that when you create and checkout a
463 local working branch based on a branch name,
464 your local environment matches the "tip" of that development branch
465 at the time you created your local branch, which could be
466 different from the files at the time of a similarly named release.
467 In other words, creating and checking out a local branch based on
468 the "&DISTRO_NAME_NO_CAP;" branch name is not the same as
469 cloning and checking out the "master" branch.
470 Keep reading to see how you create a local snapshot of a Yocto
471 Project Release.
472 </para>
473
474 <para>
475 Git uses "tags" to mark specific changes in a repository.
476 Typically, a tag is used to mark a special point such as the final
477 change before a project is released.
478 You can see the tags used with the <filename>poky</filename> Git
479 repository by going to
480 <ulink url='&YOCTO_GIT_URL;/cgit.cgi/poky/'></ulink> and
481 clicking on the
482 <filename><ulink url='&YOCTO_GIT_URL;/cgit.cgi/poky/refs/tags'>[...]</ulink></filename>
483 link beneath the "Tag" heading.
484 </para>
485
486 <para>
487 Some key tags are
488 <filename>dizzy-12.0.0</filename>,
489 <filename>fido-13.0.0</filename>,
490 <filename>jethro-14.0.0</filename>, and
491 <filename>&DISTRO_NAME_NO_CAP;-&POKYVERSION;</filename>.
492 These tags represent Yocto Project releases.
493 </para>
494
495 <para>
496 When you create a local copy of the Git repository, you also have access to all the
497 tags.
498 Similar to branches, you can create and checkout a local working Git branch based
499 on a tag name.
500 When you do this, you get a snapshot of the Git repository that reflects
501 the state of the files when the change was made associated with that tag.
502 The most common use is to checkout a working branch that matches a specific
503 Yocto Project release.
504 Here is an example:
505 <literallayout class='monospaced'>
506 $ cd ~
507 $ git clone git://git.yoctoproject.org/poky
508 $ cd poky
509 $ git checkout -b my-&DISTRO_NAME_NO_CAP;-&POKYVERSION; &DISTRO_NAME_NO_CAP;-&POKYVERSION;
510 </literallayout>
511 In this example, the name of the top-level directory of your local Yocto Project
512 Files Git repository is <filename>poky</filename>.
513 And, the name of the local branch you have created and checked out is
514 <filename>my-&DISTRO_NAME_NO_CAP;-&POKYVERSION;</filename>.
515 The files in your repository now exactly match the Yocto Project &DISTRO;
516 Release tag (<filename>&DISTRO_NAME_NO_CAP;-&POKYVERSION;</filename>).
517 It is important to understand that when you create and checkout a local
518 working branch based on a tag, your environment matches a specific point
519 in time and not the entire development branch.
520 </para>
521 </section>
522
523 <section id='basic-commands'>
524 <title>Basic Commands</title>
525
526 <para>
527 Git has an extensive set of commands that lets you manage changes and perform
528 collaboration over the life of a project.
529 Conveniently though, you can manage with a small set of basic operations and workflows
530 once you understand the basic philosophy behind Git.
531 You do not have to be an expert in Git to be functional.
532 A good place to look for instruction on a minimal set of Git commands is
533 <ulink url='http://git-scm.com/documentation'>here</ulink>.
534 If you need to download Git, you can do so
535 <ulink url='http://git-scm.com/download'>here</ulink>, although
536 any reasonably current Linux distribution should already have an
537 installable package for Git.
538 </para>
539
540 <para>
541 If you do not know much about Git, you should educate
542 yourself by visiting the links previously mentioned.
543 </para>
544
545 <para>
546 The following list briefly describes some basic Git operations as a way to get started.
547 As with any set of commands, this list (in most cases) simply shows the base command and
548 omits the many arguments they support.
549 See the Git documentation for complete descriptions and strategies on how to use these commands:
550 <itemizedlist>
551 <listitem><para><emphasis><filename>git init</filename>:</emphasis> Initializes an empty Git repository.
552 You cannot use Git commands unless you have a <filename>.git</filename> repository.</para></listitem>
553 <listitem><para><emphasis><filename>git clone</filename>:</emphasis>
554 Creates a local clone of a Git repository.
555 During collaboration, this command allows you to create a
556 local Git repository that is on equal footing with a fellow
557 developer’s Git repository.
558 </para></listitem>
559 <listitem><para><emphasis><filename>git add</filename>:</emphasis> Stages updated file contents
560 to the index that
561 Git uses to track changes.
562 You must stage all files that have changed before you can commit them.</para></listitem>
563 <listitem><para><emphasis><filename>git commit</filename>:</emphasis> Creates a "commit" that documents
564 the changes you made.
565 Commits are used for historical purposes, for determining if a maintainer of a project
566 will allow the change, and for ultimately pushing the change from your local Git repository
567 into the project’s upstream (or master) repository.</para></listitem>
568 <listitem><para><emphasis><filename>git status</filename>:</emphasis> Reports any modified files that
569 possibly need to be staged and committed.</para></listitem>
570 <listitem><para><emphasis><filename>git checkout</filename> <replaceable>branch-name</replaceable>:</emphasis> Changes
571 your working branch.
572 This command is analogous to "cd".</para></listitem>
573 <listitem><para><emphasis><filename>git checkout –b</filename> <replaceable>working-branch</replaceable>:</emphasis> Creates
574 a working branch on your local machine where you can isolate work.
575 It is a good idea to use local branches when adding specific features or changes.
576 This way if you do not like what you have done you can easily get rid of the work.</para></listitem>
577 <listitem><para><emphasis><filename>git branch</filename>:</emphasis> Reports
578 existing local branches and
579 tells you the branch in which you are currently working.</para></listitem>
580 <listitem><para><emphasis><filename>git branch -D</filename> <replaceable>branch-name</replaceable>:</emphasis>
581 Deletes an existing local branch.
582 You need to be in a local branch other than the one you are deleting
583 in order to delete <replaceable>branch-name</replaceable>.</para></listitem>
584 <listitem><para><emphasis><filename>git pull</filename>:</emphasis> Retrieves information
585 from an upstream Git
586 repository and places it in your local Git repository.
587 You use this command to make sure you are synchronized with the repository
588 from which you are basing changes (.e.g. the master branch).</para></listitem>
589 <listitem><para><emphasis><filename>git push</filename>:</emphasis>
590 Sends all your committed local changes to an upstream Git
591 repository (e.g. a contribution repository).
592 The maintainer of the project draws from these repositories
593 when adding changes to the project’s master repository or
594 other development branch.
595 </para></listitem>
596 <listitem><para><emphasis><filename>git merge</filename>:</emphasis> Combines or adds changes from one
597 local branch of your repository with another branch.
598 When you create a local Git repository, the default branch is named "master".
599 A typical workflow is to create a temporary branch for isolated work, make and commit your
600 changes, switch to your local master branch, merge the changes from the temporary branch into the
601 local master branch, and then delete the temporary branch.</para></listitem>
602 <listitem><para><emphasis><filename>git cherry-pick</filename>:</emphasis> Choose and apply specific
603 commits from one branch into another branch.
604 There are times when you might not be able to merge all the changes in one branch with
605 another but need to pick out certain ones.</para></listitem>
606 <listitem><para><emphasis><filename>gitk</filename>:</emphasis> Provides a GUI view of the branches
607 and changes in your local Git repository.
608 This command is a good way to graphically see where things have diverged in your
609 local repository.</para></listitem>
610 <listitem><para><emphasis><filename>git log</filename>:</emphasis> Reports a history of your changes to the
611 repository.</para></listitem>
612 <listitem><para><emphasis><filename>git diff</filename>:</emphasis> Displays line-by-line differences
613 between your local working files and the same files in the upstream Git repository that your
614 branch currently tracks.</para></listitem>
615 </itemizedlist>
616 </para>
617 </section>
618</section>
619
620<section id='submitting-a-defect-against-the-yocto-project'> 357<section id='submitting-a-defect-against-the-yocto-project'>
621 <title>Submitting a Defect Against the Yocto Project</title> 358 <title>Submitting a Defect Against the Yocto Project</title>
622 359
@@ -862,7 +599,7 @@
862 </para></listitem> 599 </para></listitem>
863 <listitem><para> 600 <listitem><para>
864 <emphasis>Search by File:</emphasis> 601 <emphasis>Search by File:</emphasis>
865 Using <link linkend='git'>Git</link>, you can enter the 602 Using <ulink url='&YOCTO_DOCS_REF_URL;#git'>Git</ulink>, you can enter the
866 following command to bring up a short list of all commits 603 following command to bring up a short list of all commits
867 against a specific file: 604 against a specific file:
868 <literallayout class='monospaced'> 605 <literallayout class='monospaced'>
diff --git a/documentation/dev-manual/dev-manual-start.xml b/documentation/dev-manual/dev-manual-start.xml
index 4dbcc7e34a..df622f93b9 100644
--- a/documentation/dev-manual/dev-manual-start.xml
+++ b/documentation/dev-manual/dev-manual-start.xml
@@ -87,7 +87,7 @@
87 The documentation refers to this set of locally installed files 87 The documentation refers to this set of locally installed files
88 as the <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>. 88 as the <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>.
89 You create your Source Directory by using 89 You create your Source Directory by using
90 <link linkend='git'>Git</link> to clone a local copy 90 <ulink url='&YOCTO_DOCS_REF_URL;#git'>Git</ulink> to clone a local copy
91 of the upstream <filename>poky</filename> repository, 91 of the upstream <filename>poky</filename> repository,
92 or by downloading and unpacking a tarball of an official 92 or by downloading and unpacking a tarball of an official
93 Yocto Project release. 93 Yocto Project release.
@@ -110,7 +110,7 @@
110 The command creates the local repository in a directory 110 The command creates the local repository in a directory
111 named <filename>poky</filename>. 111 named <filename>poky</filename>.
112 For information on Git used within the Yocto Project, see 112 For information on Git used within the Yocto Project, see
113 the "<link linkend='git'>Git</link>" section. 113 the "<ulink url='&YOCTO_DOCS_REF_URL;#git'>Git</ulink>" section.
114 <literallayout class='monospaced'> 114 <literallayout class='monospaced'>
115 $ git clone git://git.yoctoproject.org/poky 115 $ git clone git://git.yoctoproject.org/poky
116 Cloning into 'poky'... 116 Cloning into 'poky'...
@@ -241,7 +241,7 @@
241 <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink>.</para> 241 <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink>.</para>
242 242
243 <para>Using 243 <para>Using
244 <link linkend='git'>Git</link> to create a local clone of the 244 <ulink url='&YOCTO_DOCS_REF_URL;#git'>Git</ulink> to create a local clone of the
245 upstream repository can be helpful if you are working with 245 upstream repository can be helpful if you are working with
246 BSPs. 246 BSPs.
247 Typically, you set up the <filename>meta-intel</filename> 247 Typically, you set up the <filename>meta-intel</filename>
diff --git a/documentation/kernel-dev/kernel-dev-concepts-appx.xml b/documentation/kernel-dev/kernel-dev-concepts-appx.xml
index ac91749cd6..8ecd04d32c 100644
--- a/documentation/kernel-dev/kernel-dev-concepts-appx.xml
+++ b/documentation/kernel-dev/kernel-dev-concepts-appx.xml
@@ -107,7 +107,7 @@
107 The features are tagged and organized by way of a branching strategy implemented by the 107 The features are tagged and organized by way of a branching strategy implemented by the
108 source code manager (SCM) Git. 108 source code manager (SCM) Git.
109 For information on Git as applied to the Yocto Project, see the 109 For information on Git as applied to the Yocto Project, see the
110 "<ulink url='&YOCTO_DOCS_DEV_URL;#git'>Git</ulink>" section in the 110 "<ulink url='&YOCTO_DOCS_REF_URL;#git'>Git</ulink>" section in the
111 Yocto Project Development Manual. 111 Yocto Project Development Manual.
112 </para> 112 </para>
113 <para> 113 <para>
@@ -235,8 +235,8 @@
235 <para> 235 <para>
236 You can find documentation on Git at <ulink url='http://git-scm.com/documentation'></ulink>. 236 You can find documentation on Git at <ulink url='http://git-scm.com/documentation'></ulink>.
237 You can also get an introduction to Git as it applies to the Yocto Project in the 237 You can also get an introduction to Git as it applies to the Yocto Project in the
238 "<ulink url='&YOCTO_DOCS_DEV_URL;#git'>Git</ulink>" 238 "<ulink url='&YOCTO_DOCS_REF_URL;#git'>Git</ulink>"
239 section in the Yocto Project Development Manual. 239 section in the Yocto Project Reference Manual.
240 These referenced sections overview Git and describe a minimal set of 240 These referenced sections overview Git and describe a minimal set of
241 commands that allows you to be functional using Git. 241 commands that allows you to be functional using Git.
242 <note> 242 <note>
diff --git a/documentation/kernel-dev/kernel-dev-examples.xml b/documentation/kernel-dev/kernel-dev-examples.xml
index 9d9aef6d06..3ea217f3c4 100644
--- a/documentation/kernel-dev/kernel-dev-examples.xml
+++ b/documentation/kernel-dev/kernel-dev-examples.xml
@@ -241,8 +241,8 @@
241 You can find Git documentation at 241 You can find Git documentation at
242 <ulink url='http://git-scm.com/documentation'></ulink>. 242 <ulink url='http://git-scm.com/documentation'></ulink>.
243 You can find a simple overview of using Git with the Yocto Project in the 243 You can find a simple overview of using Git with the Yocto Project in the
244 "<ulink url='&YOCTO_DOCS_DEV_URL;#git'>Git</ulink>" 244 "<ulink url='&YOCTO_DOCS_REF_URL;#git'>Git</ulink>"
245 section of the Yocto Project Development Manual. 245 section of the Yocto Project Reference Manual.
246 </para> 246 </para>
247 247
248 <section id='change-inspection-kernel-changes-commits'> 248 <section id='change-inspection-kernel-changes-commits'>
diff --git a/documentation/ref-manual/introduction.xml b/documentation/ref-manual/introduction.xml
index 1fc01fe38a..9e6c751987 100644
--- a/documentation/ref-manual/introduction.xml
+++ b/documentation/ref-manual/introduction.xml
@@ -1035,8 +1035,8 @@
1035 1035
1036 <para>For more information on concepts related to Git 1036 <para>For more information on concepts related to Git
1037 repositories, branches, and tags, see the 1037 repositories, branches, and tags, see the
1038 "<ulink url='&YOCTO_DOCS_DEV_URL;#repositories-tags-and-branches'>Repositories, Tags, and Branches</ulink>" 1038 "<link linkend='repositories-tags-and-branches'>Repositories, Tags, and Branches</link>"
1039 section in the Yocto Project Development Manual. 1039 section.
1040 </para></listitem> 1040 </para></listitem>
1041 <listitem><para><emphasis>Task:</emphasis> 1041 <listitem><para><emphasis>Task:</emphasis>
1042 A unit of execution for BitBake (e.g. 1042 A unit of execution for BitBake (e.g.
diff --git a/documentation/ref-manual/migration.xml b/documentation/ref-manual/migration.xml
index a3dc1ee1f6..b90a7d1213 100644
--- a/documentation/ref-manual/migration.xml
+++ b/documentation/ref-manual/migration.xml
@@ -1748,7 +1748,7 @@
1748 1748
1749 <para> 1749 <para>
1750 The minimum 1750 The minimum
1751 <ulink url='&YOCTO_DOCS_DEV_URL;#git'>Git</ulink> version required 1751 <link linkend='git'>Git</link> version required
1752 on the build host is now 1.7.8 because the 1752 on the build host is now 1.7.8 because the
1753 <filename>--list</filename> option is now required by 1753 <filename>--list</filename> option is now required by
1754 BitBake's Git fetcher. 1754 BitBake's Git fetcher.
diff --git a/documentation/ref-manual/ref-development-environment.xml b/documentation/ref-manual/ref-development-environment.xml
index 08e790b7a2..234800df69 100644
--- a/documentation/ref-manual/ref-development-environment.xml
+++ b/documentation/ref-manual/ref-development-environment.xml
@@ -256,6 +256,360 @@
256 </para> 256 </para>
257</section> 257</section>
258 258
259<section id='git'>
260 <title>Git</title>
261
262 <para>
263 The Yocto Project makes extensive use of Git, which is a
264 free, open source distributed version control system.
265 Git supports distributed development, non-linear development,
266 and can handle large projects.
267 It is best that you have some fundamental understanding
268 of how Git tracks projects and how to work with Git if
269 you are going to use the Yocto Project for development.
270 This section provides a quick overview of how Git works and
271 provides you with a summary of some essential Git commands.
272 </para>
273
274 <para>
275 For more information on Git, see
276 <ulink url='http://git-scm.com/documentation'></ulink>.
277 If you need to download Git, it is recommended that you add Git
278 to your system through your distribution's "software store"
279 (e.g. for Ubuntu, use the Ubuntu Software feature).
280 For the Git download page, see
281 <ulink url='http://git-scm.com/download'></ulink>.
282 </para>
283
284 <section id='repositories-tags-and-branches'>
285 <title>Repositories, Tags, and Branches</title>
286
287 <para>
288 As mentioned briefly in the previous section and also in the
289 "<link linkend='workflows'>Workflows</link>" section,
290 the Yocto Project maintains source repositories at
291 <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink>.
292 If you look at this web-interface of the repositories, each item
293 is a separate Git repository.
294 </para>
295
296 <para>
297 Git repositories use branching techniques that track content
298 change (not files) within a project (e.g. a new feature or updated
299 documentation).
300 Creating a tree-like structure based on project divergence allows
301 for excellent historical information over the life of a project.
302 This methodology also allows for an environment from which you can
303 do lots of local experimentation on projects as you develop
304 changes or new features.
305 </para>
306
307 <para>
308 A Git repository represents all development efforts for a given
309 project.
310 For example, the Git repository <filename>poky</filename> contains
311 all changes and developments for Poky over the course of its
312 entire life.
313 That means that all changes that make up all releases are captured.
314 The repository maintains a complete history of changes.
315 </para>
316
317 <para>
318 You can create a local copy of any repository by "cloning" it
319 with the <filename>git clone</filename> command.
320 When you clone a Git repository, you end up with an identical
321 copy of the repository on your development system.
322 Once you have a local copy of a repository, you can take steps to
323 develop locally.
324 For examples on how to clone Git repositories, see the
325 "<ulink url='&YOCTO_DOCS_DEV_URL;#getting-setup'>Getting Set Up</ulink>"
326 section in the Yocto Project Development Manual.
327 </para>
328
329 <para>
330 It is important to understand that Git tracks content change and
331 not files.
332 Git uses "branches" to organize different development efforts.
333 For example, the <filename>poky</filename> repository has
334 several branches that include the current "&DISTRO_NAME_NO_CAP;"
335 branch, the "master" branch, and many branches for past
336 Yocto Project releases.
337 You can see all the branches by going to
338 <ulink url='&YOCTO_GIT_URL;/cgit.cgi/poky/'></ulink> and
339 clicking on the
340 <filename><ulink url='&YOCTO_GIT_URL;/cgit.cgi/poky/refs/heads'>[...]</ulink></filename>
341 link beneath the "Branch" heading.
342 </para>
343
344 <para>
345 Each of these branches represents a specific area of development.
346 The "master" branch represents the current or most recent
347 development.
348 All other branches represent offshoots of the "master" branch.
349 </para>
350
351 <para>
352 When you create a local copy of a Git repository, the copy has
353 the same set of branches as the original.
354 This means you can use Git to create a local working area
355 (also called a branch) that tracks a specific development branch
356 from the upstream source Git repository.
357 in other words, you can define your local Git environment to
358 work on any development branch in the repository.
359 To help illustrate, consider the following example Git commands:
360 <literallayout class='monospaced'>
361 $ cd ~
362 $ git clone git://git.yoctoproject.org/poky
363 $ cd poky
364 $ git checkout -b &DISTRO_NAME_NO_CAP; origin/&DISTRO_NAME_NO_CAP;
365 </literallayout>
366 In the previous example after moving to the home directory, the
367 <filename>git clone</filename> command creates a
368 local copy of the upstream <filename>poky</filename> Git repository.
369 By default, Git checks out the "master" branch for your work.
370 After changing the working directory to the new local repository
371 (i.e. <filename>poky</filename>), the
372 <filename>git checkout</filename> command creates
373 and checks out a local branch named "&DISTRO_NAME_NO_CAP;", which
374 tracks the upstream "origin/&DISTRO_NAME_NO_CAP;" branch.
375 Changes you make while in this branch would ultimately affect
376 the upstream "&DISTRO_NAME_NO_CAP;" branch of the
377 <filename>poky</filename> repository.
378 </para>
379
380 <para>
381 It is important to understand that when you create and checkout a
382 local working branch based on a branch name,
383 your local environment matches the "tip" of that particular
384 development branch at the time you created your local branch,
385 which could be different from the files in the "master" branch
386 of the upstream repository.
387 In other words, creating and checking out a local branch based on
388 the "&DISTRO_NAME_NO_CAP;" branch name is not the same as
389 cloning and checking out the "master" branch if the repository.
390 Keep reading to see how you create a local snapshot of a Yocto
391 Project Release.
392 </para>
393
394 <para>
395 Git uses "tags" to mark specific changes in a repository.
396 Typically, a tag is used to mark a special point such as the final
397 change before a project is released.
398 You can see the tags used with the <filename>poky</filename> Git
399 repository by going to
400 <ulink url='&YOCTO_GIT_URL;/cgit.cgi/poky/'></ulink> and
401 clicking on the
402 <filename><ulink url='&YOCTO_GIT_URL;/cgit.cgi/poky/refs/tags'>[...]</ulink></filename>
403 link beneath the "Tag" heading.
404 </para>
405
406 <para>
407 Some key tags for the <filename>poky</filename> are
408 <filename>jethro-14.0.3</filename>,
409 <filename>morty-16.0.1</filename>,
410 <filename>pyro-17.0.0</filename>, and
411 <filename>&DISTRO_NAME_NO_CAP;-&POKYVERSION;</filename>.
412 These tags represent Yocto Project releases.
413 </para>
414
415 <para>
416 When you create a local copy of the Git repository, you also
417 have access to all the tags in the upstream repository.
418 Similar to branches, you can create and checkout a local working
419 Git branch based on a tag name.
420 When you do this, you get a snapshot of the Git repository that
421 reflects the state of the files when the change was made associated
422 with that tag.
423 The most common use is to checkout a working branch that matches
424 a specific Yocto Project release.
425 Here is an example:
426 <literallayout class='monospaced'>
427 $ cd ~
428 $ git clone git://git.yoctoproject.org/poky
429 $ cd poky
430 $ git fetch --all --tags --prune
431 $ git checkout tags/pyro-17.0.0 -b my-pyro-17.0.0
432 </literallayout>
433 In this example, the name of the top-level directory of your
434 local Yocto Project repository is <filename>poky</filename>.
435 After moving to the <filename>poky</filename> directory, the
436 <filename>git fetch</filename> command makes all the upstream
437 tags available locally in your repository.
438 Finally, the <filename>git checkout</filename> command
439 creates and checks out a branch named "my-pyro-17.0.0" that is
440 based on the specific change upstream in the repository
441 associated with the "pyro-17.0.0" tag.
442 The files in your repository now exactly match that particular
443 Yocto Project release as it is tagged in the upstream Git
444 repository.
445 It is important to understand that when you create and
446 checkout a local working branch based on a tag, your environment
447 matches a specific point in time and not the entire development
448 branch (i.e. the "tip" of the branch).
449 </para>
450 </section>
451
452 <section id='basic-commands'>
453 <title>Basic Commands</title>
454
455 <para>
456 Git has an extensive set of commands that lets you manage changes
457 and perform collaboration over the life of a project.
458 Conveniently though, you can manage with a small set of basic
459 operations and workflows once you understand the basic
460 philosophy behind Git.
461 You do not have to be an expert in Git to be functional.
462 A good place to look for instruction on a minimal set of Git
463 commands is
464 <ulink url='http://git-scm.com/documentation'>here</ulink>.
465 </para>
466
467 <para>
468 If you do not know much about Git, you should educate
469 yourself by visiting the links previously mentioned.
470 </para>
471
472 <para>
473 The following list of Git commands briefly describes some basic
474 Git operations as a way to get started.
475 As with any set of commands, this list (in most cases) simply shows
476 the base command and omits the many arguments they support.
477 See the Git documentation for complete descriptions and strategies
478 on how to use these commands:
479 <itemizedlist>
480 <listitem><para>
481 <emphasis><filename>git init</filename>:</emphasis>
482 Initializes an empty Git repository.
483 You cannot use Git commands unless you have a
484 <filename>.git</filename> repository.
485 </para></listitem>
486 <listitem><para>
487 <emphasis><filename>git clone</filename>:</emphasis>
488 Creates a local clone of a Git repository that is on
489 equal footing with a fellow developer’s Git repository
490 or an upstream repository.
491 </para></listitem>
492 <listitem><para>
493 <emphasis><filename>git add</filename>:</emphasis>
494 Locally stages updated file contents to the index that
495 Git uses to track changes.
496 You must stage all files that have changed before you
497 can commit them.
498 </para></listitem>
499 <listitem><para>
500 <emphasis><filename>git commit</filename>:</emphasis>
501 Creates a local "commit" that documents the changes you
502 made.
503 Only changes that have been staged can be committed.
504 Commits are used for historical purposes, for determining
505 if a maintainer of a project will allow the change,
506 and for ultimately pushing the change from your local
507 Git repository into the project’s upstream repository.
508 </para></listitem>
509 <listitem><para>
510 <emphasis><filename>git status</filename>:</emphasis>
511 Reports any modified files that possibly need to be
512 staged and gives you a status of where you stand regarding
513 local commits as compared to the upstream repository.
514 </para></listitem>
515 <listitem><para>
516 <emphasis><filename>git checkout</filename> <replaceable>branch-name</replaceable>:</emphasis>
517 Changes your working branch.
518 This command is analogous to "cd".
519 </para></listitem>
520 <listitem><para><emphasis><filename>git checkout –b</filename> <replaceable>working-branch</replaceable>:</emphasis>
521 Creates and checks out a working branch on your local
522 machine that you can use to isolate your work.
523 It is a good idea to use local branches when adding
524 specific features or changes.
525 Using isolated branches facilitates easy removal of
526 changes if they do not work out.
527 </para></listitem>
528 <listitem><para><emphasis><filename>git branch</filename>:</emphasis>
529 Displays the existing local branches associated with your
530 local repository.
531 The branch that you have currently checked out is noted
532 with an asterisk character.
533 </para></listitem>
534 <listitem><para>
535 <emphasis><filename>git branch -D</filename> <replaceable>branch-name</replaceable>:</emphasis>
536 Deletes an existing local branch.
537 You need to be in a local branch other than the one you
538 are deleting in order to delete
539 <replaceable>branch-name</replaceable>.
540 </para></listitem>
541 <listitem><para>
542 <emphasis><filename>git pull</filename>:</emphasis>
543 Retrieves information from an upstream Git repository
544 and places it in your local Git repository.
545 You use this command to make sure you are synchronized with
546 the repository from which you are basing changes
547 (.e.g. the "master" branch).
548 </para></listitem>
549 <listitem><para>
550 <emphasis><filename>git push</filename>:</emphasis>
551 Sends all your committed local changes to the upstream Git
552 repository that your local repository is tracking
553 (e.g. a contribution repository).
554 The maintainer of the project draws from these repositories
555 to merge changes (commits) into the appropriate branch
556 of project's upstream repository.
557 </para></listitem>
558 <listitem><para>
559 <emphasis><filename>git merge</filename>:</emphasis>
560 Combines or adds changes from one
561 local branch of your repository with another branch.
562 When you create a local Git repository, the default branch
563 is named "master".
564 A typical workflow is to create a temporary branch that is
565 based off "master" that you would use for isolated work.
566 You would make your changes in that isolated branch,
567 stage and commit them locally, switch to the "master"
568 branch, and then use the <filename>git merge</filename>
569 command to apply the changes from your isolated branch
570 into the currently checked out branch (e.g. "master").
571 After the merge is complete and if you are done with
572 working in that isolated branch, you can safely delete
573 the isolated branch.
574 </para></listitem>
575 <listitem><para>
576 <emphasis><filename>git cherry-pick</filename>:</emphasis>
577 Choose and apply specific commits from one branch
578 into another branch.
579 There are times when you might not be able to merge
580 all the changes in one branch with
581 another but need to pick out certain ones.
582 </para></listitem>
583 <listitem><para>
584 <emphasis><filename>gitk</filename>:</emphasis>
585 Provides a GUI view of the branches and changes in your
586 local Git repository.
587 This command is a good way to graphically see where things
588 have diverged in your local repository.
589 <note>
590 You need to install the <filename>gitk</filename>
591 package on your development system to use this
592 command.
593 </note>
594 </para></listitem>
595 <listitem><para>
596 <emphasis><filename>git log</filename>:</emphasis>
597 Reports a history of your commits to the repository.
598 This report lists all commits regardless of whether you
599 have pushed them upstream or not.
600 </para></listitem>
601 <listitem><para>
602 <emphasis><filename>git diff</filename>:</emphasis>
603 Displays line-by-line differences between a local
604 working file and the same file as understood by Git.
605 This command is useful to see what you have changed
606 in any given file.
607 </para></listitem>
608 </itemizedlist>
609 </para>
610 </section>
611</section>
612
259<section id='yocto-project-repositories'> 613<section id='yocto-project-repositories'>
260 <title>Yocto Project Source Repositories</title> 614 <title>Yocto Project Source Repositories</title>
261 615
@@ -290,7 +644,7 @@
290 <link linkend='source-directory'>Source Directory</link> 644 <link linkend='source-directory'>Source Directory</link>
291 and the files for supported BSPs 645 and the files for supported BSPs
292 (e.g., <filename>meta-intel</filename>) is to use 646 (e.g., <filename>meta-intel</filename>) is to use
293 <ulink url='&YOCTO_DOCS_DEV_URL;#git'>Git</ulink> to create a local copy of 647 <link linkend='git'>Git</link> to create a local copy of
294 the upstream repositories. 648 the upstream repositories.
295 </para></listitem> 649 </para></listitem>
296 <listitem><para> 650 <listitem><para>
diff --git a/documentation/ref-manual/usingpoky.xml b/documentation/ref-manual/usingpoky.xml
index 9fb74172b5..c81818840a 100644
--- a/documentation/ref-manual/usingpoky.xml
+++ b/documentation/ref-manual/usingpoky.xml
@@ -1110,7 +1110,7 @@
1110 Enabling build history as previously described 1110 Enabling build history as previously described
1111 causes the build process to collect build 1111 causes the build process to collect build
1112 output information and commit it to a local 1112 output information and commit it to a local
1113 <ulink url='&YOCTO_DOCS_DEV_URL;#git'>Git</ulink> repository. 1113 <link linkend='git'>Git</link> repository.
1114 <note> 1114 <note>
1115 Enabling build history increases your build times slightly, 1115 Enabling build history increases your build times slightly,
1116 particularly for images, and increases the amount of disk 1116 particularly for images, and increases the amount of disk
diff --git a/documentation/sdk-manual/sdk-extensible.xml b/documentation/sdk-manual/sdk-extensible.xml
index 44cb94722f..415cf679ee 100644
--- a/documentation/sdk-manual/sdk-extensible.xml
+++ b/documentation/sdk-manual/sdk-extensible.xml
@@ -240,7 +240,7 @@
240 <para> 240 <para>
241 The <filename>devtool</filename> command line is organized 241 The <filename>devtool</filename> command line is organized
242 similarly to 242 similarly to
243 <ulink url='&YOCTO_DOCS_DEV_URL;#git'>Git</ulink> in that it has a 243 <ulink url='&YOCTO_DOCS_REF_URL;#git'>Git</ulink> in that it has a
244 number of sub-commands for each function. 244 number of sub-commands for each function.
245 You can run <filename>devtool --help</filename> to see all the 245 You can run <filename>devtool --help</filename> to see all the
246 commands. 246 commands.
diff --git a/documentation/yocto-project-qs/yocto-project-qs.xml b/documentation/yocto-project-qs/yocto-project-qs.xml
index 527fcd86cc..b069b3d459 100644
--- a/documentation/yocto-project-qs/yocto-project-qs.xml
+++ b/documentation/yocto-project-qs/yocto-project-qs.xml
@@ -378,7 +378,7 @@
378 Yocto Project is getting a Yocto Project release. 378 Yocto Project is getting a Yocto Project release.
379 It is recommended that you get the latest Yocto Project release 379 It is recommended that you get the latest Yocto Project release
380 by setting up (cloning in 380 by setting up (cloning in
381 <ulink url='&YOCTO_DOCS_DEV_URL;#git'>Git</ulink> terms) a 381 <ulink url='&YOCTO_DOCS_REF_URL;#git'>Git</ulink> terms) a
382 local copy of the <filename>poky</filename> Git repository on 382 local copy of the <filename>poky</filename> Git repository on
383 your build host and then checking out the latest release. 383 your build host and then checking out the latest release.
384 Doing so allows you to easily update to newer Yocto Project 384 Doing so allows you to easily update to newer Yocto Project