summaryrefslogtreecommitdiffstats
path: root/documentation/dev-manual
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/dev-manual
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/dev-manual')
-rw-r--r--documentation/dev-manual/dev-manual-newbie.xml269
-rw-r--r--documentation/dev-manual/dev-manual-start.xml6
2 files changed, 6 insertions, 269 deletions
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>