Changeset 7e91a8f in rtems-docs


Ignore:
Timestamp:
Dec 3, 2018, 5:01:40 PM (5 months ago)
Author:
Marçal Comajoan Cara <mcomajoancara@…>
Branches:
master
Children:
eb34b90
Parents:
f4782c9
git-author:
Marçal Comajoan Cara <mcomajoancara@…> (12/03/18 17:01:40)
git-committer:
Joel Sherrill <joel@…> (12/18/18 00:45:49)
Message:

eng/vc-users: Convert wiki page to Rest (GCI 2018)

Converted https://devel.rtems.org/wiki/Developer/Git/Users
to Rest, and TBDs and wiki TODOs into comments. Also changed http
links to https (the ones that are possible), corrected typos, updated
learning resources links and added formattings.

This work was part of GCI 2018.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • eng/vc-users.rst

    rf4782c9 r7e91a8f  
    88********************************
    99
    10 TBD - Convert https://devel.rtems.org/wiki/Developer/Git/Users to Rest
    11 TBD - and insert here.
     10.. COMMENT: TBD - Convert https://devel.rtems.org/wiki/Developer/Git/Users to
     11.. COMMENT: TBD - Rest and insert here.
     12
     13.. COMMENT: TBD - Managing a (private/public) Git mirror, using GitHub,
     14.. COMMENT: TBD - submitting pull requests...
     15
     16Browse the Git Repository Online
     17--------------------------------
     18
     19You can browse all available repositories online by
     20accessing https://git.rtems.org/.
     21
     22Using the Git Repository
     23------------------------
     24
     25The following examples demonstrate how to use the RTEMS' Git repos. These
     26examples are provided for the main rtems module, but they are also valid
     27for the other modules.
     28
     29First, we need to obtain our own local copy of the RTEMS Git repository:
     30
     31.. code-block:: shell
     32
     33  git clone git://git.rtems.org/rtems.git rtems
     34
     35This command will create a folder named rtems in the current directory. This
     36folder will contain a full-featured RTEMS' Git repository and the current HEAD
     37revision checked out. Since all the history is available we can check out any
     38release of RTEMS. Major RTEMS releases are available as separate branches in
     39the repo.
     40
     41To see all available remote branches issue the following command:
     42
     43.. code-block:: shell
     44
     45  git branch -r
     46
     47We can check out one of those remote branches (e.g. rtems-4.10 branch) using
     48the command:
     49
     50.. code-block:: shell
     51
     52  git checkout -b rtems410 origin/4.10
     53
     54This will create a local branch named "rtems410", containing the rtems-4.10
     55release, that will track the remote branch "rtems-4-10-branch" in origin
     56(​git://git.rtems.org/rtems.git). The ``git branch`` command prints a list of
     57the current local branches, indicating the one currently checked out.
     58
     59If you want to switch between local branches:
     60
     61.. code-block:: shell
     62
     63  git checkout <branch-name>
     64
     65With time your local repository will diverge from the main RTEMS repository. To
     66keep your local copy up to date you need to issue:
     67
     68.. code-block:: shell
     69
     70  git pull origin
     71
     72This command will update all your local branches with any new code revisions
     73available on the central repository.
     74
     75Making Changes
     76--------------
     77
     78Git allows you to make changes in the RTEMS source tree and track those changes
     79locally. We recommend you make all your changes in local branches. If you are
     80working on a few different changes or a progression of changes it is best to
     81use a local branch for each change.
     82
     83A branch for each change lets your repo's master branch track the upstream
     84RTEMS' master branch without interacting with any of the changes you are
     85working on. A completed change is emailed to the developer's list for review
     86and this can take time. While this is happening the upstream's master branch
     87may be updated and you may need to rebase your work and test again if you are
     88required to change or update your patch. A local branch isolates a specific
     89change from others and helps you manage the process.
     90
     91First, you need to clone the repository:
     92
     93.. code-block:: shell
     94
     95  git clone git://git.rtems.org/rtems.git rtems
     96
     97Or if you already cloned it before, then you might want to update to the latest
     98version before making your changes:
     99
     100.. code-block:: shell
     101
     102  cd rtems
     103  git pull
     104
     105Create a local branch to make your changes in, in this example, the change is
     106``faster-context-switch``:
     107
     108.. code-block:: shell
     109
     110  git checkout -b faster-context-switch
     111
     112Next, make your changes to files. If you add, delete ormove/rename files you
     113need to inform Git
     114
     115.. code-block:: shell
     116
     117  git add /some/new/file
     118  git rm /some/old/file
     119  git mv /some/old/file /some/new/file
     120
     121When you're satisfied with the changes you made, commit them (locally)
     122
     123.. code-block:: shell
     124
     125  git commit -a
     126
     127The ``-a`` flag commits all the changes that were made, but you can also
     128control which changes to commit by individually adding files as you modify
     129them by using. You can also specify other options to commit, such as a message
     130with the ``-m`` flag.
     131
     132.. code-block:: shell
     133
     134  git add /some/changed/files
     135  git commit
     136
     137Create a patch from your branch, in this case, we have two commits we want to
     138send for review:
     139
     140.. code-block:: shell
     141
     142  git format-patch -2
     143
     144 There are new changes pushed to the RTEMS' master branch and our local branch
     145 needs to be updated:
     146
     147.. code-block:: shell
     148
     149  git checkout master
     150  git pull
     151  git checkout faster-context-switch
     152  git rebase master
     153
     154Working with Branches
     155---------------------
     156
     157Branches facilitate trying out new code and creating patches.
     158
     159The previous releases of RTEMS are available through remote branches. To check
     160out a remote branch, first query the Git repository for the list of branches:
     161
     162.. code-block:: shell
     163
     164  git branch -r
     165
     166Then check out the desired remote branch, for example:
     167
     168.. code-block:: shell
     169
     170  git checkout -b rtems410 origin/4.10
     171
     172Or if you have previously checked out the remote branch then you should see it
     173in your local branches:
     174
     175.. code-block:: shell
     176
     177  git branch
     178
     179You can change to an existing local branch easily:
     180
     181.. code-block:: shell
     182
     183  git checkout rtems410
     184
     185You can also create a new branch and switch to it:
     186
     187.. code-block:: shell
     188
     189  git branch temporary
     190  git checkout temporary
     191
     192Or more concisely:
     193
     194.. code-block:: shell
     195
     196  git checkout -b temporary
     197
     198If you forget which branch you are on
     199
     200.. code-block:: shell
     201
     202  git branch
     203
     204shows you by placing a * next to the current one.
     205
     206When a branch is no longer useful you can delete it.
     207
     208.. code-block:: shell
     209
     210  git checkout master
     211  git branch -d temporary
     212
     213If you have unmerged changes in the old branch Git complains and you need to
     214use ``-D`` instead of ``-d``.
     215
     216Viewing Changes
     217---------------
     218
     219To view all changes since the last commit:
     220
     221.. code-block:: shell
     222
     223  git diff HEAD
     224
     225To view all changes between the current branch and another branch, say master:
     226
     227.. code-block:: shell
     228
     229  git diff master..HEAD
     230
     231To view descriptions of committed changes:
     232
     233.. code-block:: shell
     234
     235  git log
     236
     237Or view the changeset for some file (or directory):
     238
     239.. code-block:: shell
     240
     241  git log /some/file
     242
     243To view the changesets made between two branches:
     244
     245.. code-block:: shell
     246
     247  git log master..HEAD
     248
     249Or for a more brief description use shortlog:
     250
     251.. code-block:: shell
     252
     253  git shortlog master..HEAD
     254
     255Reverting Changes
     256-----------------
     257
     258To remove all (uncommitted) changes on a branch
     259
     260.. code-block:: shell
     261
     262  git checkout -f
     263
     264Or to selectively revert (uncommited) files, for example if you
     265accidentally deleted ./some/file
     266
     267.. code-block:: shell
     268
     269  git checkout -- ./some/file
     270
     271or
     272
     273.. code-block:: shell
     274
     275  git checkout HEAD ./some/file
     276
     277To remove commits there are two useful options, reset and revert. ``git reset``
     278should only be used on local branches that no one else is accessing remotely.
     279``git revert`` is cleaner and is the right way to revert changes that have
     280already been pushed/pulled remotely.
     281
     282git reset
     283---------
     284
     285``git reset`` is a powerful and tricky command that should only be used on
     286local (un-pushed) branches): A good description of what it enables to do can be
     287found ​here. The following are a few useful examples. Note that adding a ~
     288after HEAD refers to the most recent commit, and you can add a number after
     289the ~ to refer to commits even further back; HEAD by itself refers to the
     290current working directory (changes since the last commit).
     291
     292.. code-block:: shell
     293
     294  git reset HEAD~
     295
     296Will undo the last commit and unstage those changes. Your working directory
     297will remain the same, therefore a ``git status`` will yield any changes you
     298made plus the changes made in your last commit. This can be used to fix the
     299last commit. You will need to add the files again.
     300
     301.. code-block:: shell
     302
     303  git reset --soft HEAD~
     304
     305Will just undo the last commit. The changes from the last commit will still be
     306staged (just as if you finished git adding them). This can be used to amend the
     307last commit (e.g. You forgot to add a file to the last commit).
     308
     309.. code-block:: shell
     310
     311  git reset --hard HEAD~
     312
     313Will revert everything, including the working directory, to the previous
     314commit. This is dangerous and can lead to you losing all your changes; the
     315``--hard`` flag ignores errors.
     316
     317.. code-block:: shell
     318
     319  git reset HEAD
     320
     321Will unstage any change. This is used to revert a wrong ``git add``. (e.g. You
     322added a file that shouldn't be there, but you haven't 'committed')
     323
     324Will revert your working directory to a HEAD state. You will lose any change
     325you made to files after the last commit. This is used when you just want to
     326destroy all changes you made since the last commit.
     327
     328git revert
     329----------
     330
     331``git revert`` does the same as reset but creates a new commit with the
     332reverted changes instead of modifying the local repository directly.
     333
     334.. code-block:: shell
     335
     336  git revert HEAD
     337
     338This will create a new commit which undoes the change in HEAD. You will be
     339given a chance to edit the commit message for the new commit.
     340
     341Merging Changes
     342---------------
     343
     344Suppose you commit changes in two different branches, branch1 and branch2,
     345and want to create a new branch containing both sets of changes:
     346
     347.. code-block:: shell
     348
     349  git checkout -b merged
     350  git merge branch1
     351  git merge branch2
     352
     353Or you might want to bring the changes in one branch into the other:
     354
     355.. code-block:: shell
     356
     357  git checkout branch1
     358  git merge branch2
     359
     360And now that branch2 is merged you might get rid of it:
     361
     362.. code-block:: shell
     363
     364  git branch -d branch2
     365
     366If you have done work on a branch, say branch1, and have gone out-of-sync
     367with the remote repository, you can pull the changes from the remote repo and
     368then merge them into your branch:
     369
     370.. code-block:: shell
     371
     372  git checkout master
     373  git pull
     374  git checkout branch1
     375  git merge master
     376
     377If all goes well the new commits you pulled into your master branch will be
     378merged into your branch1, which will now be up-to-date. However, if branch1
     379has not been pushed remotely then rebasing might be a good alternative to
     380merging because the merge generates a commit.
     381
     382Rebasing
     383--------
     384
     385An alternative to the merge command is rebase, which replays the changes
     386(commits) on one branch onto another. ``git rebase`` finds the common ancestor
     387of the two branches, stores each commit of the branch you’re on to temporary
     388files and applies each commit in order.
     389
     390For example
     391
     392.. code-block:: shell
     393
     394  git checkout branch1
     395  git rebase master
     396
     397or more concisely
     398
     399.. code-block:: shell
     400
     401  git rebase master branch1
     402
     403will bring the changes of master into branch1, and then you can fast-forward
     404master to include branch1 quite easily
     405
     406.. code-block:: shell
     407
     408  git checkout master
     409  git merge branch1
     410
     411Rebasing makes a cleaner history than merging; the log of a rebased branch
     412looks like a linear history as if the work was done serially rather than in
     413parallel. A primary reason to rebase is to ensure commits apply cleanly on a
     414remote branch, e.g. when submitting patches to RTEMS that you create by working
     415on a branch in a personal repository. Using rebase to merge your work with the
     416remote branch eliminates most integration work for the committer/maintainer.
     417
     418There is one caveat to using rebase: Do not rebase commits that you have pushed
     419to a public repository. Rebase abandons existing commits and creates new ones
     420that are similar but different. If you push commits that others pull down, and
     421then you rewrite those commits with ``git rebase`` and push them up again, the
     422others will have to re-merge their work and trying to integrate their work
     423into yours can become messy.
     424
     425Accessing a developer's repository
     426----------------------------------
     427
     428RTEMS developers with Git commit access have personal repositories
     429on https://git.rtems.org/ that can be cloned to view cutting-edge
     430development work shared there.
     431
     432Creating a Patch
     433----------------
     434
     435Before submitting a patch read about `Contributing
     436<https://devel.rtems.org/wiki/Developer/Contributing>`_ to RTEMS and the
     437`Commit Message <https://devel.rtems.org/wiki/Developer/Git#GitCommits>`_
     438formatting we require.
     439
     440The recommended way to create a patch is to branch the Git repository master
     441and use one commit for each logical change. Then you can use
     442``git format-patch`` to turn your commits into patches and easily submit them.
     443
     444.. code-block:: shell
     445
     446  git format-patch master
     447
     448Creates a separate patch for each commit that has been made between the master
     449branch and the current branch and writes them in the current directory. Use the
     450``-o`` flag to redirect the files to a different directory.
     451
     452If you are re-submitting a patch that has previously been reviewed, you should
     453specify a version number for your patch, for example, use
     454
     455.. code-block:: shell
     456
     457  git format-patch -v2 ...
     458
     459to indicate the second version of a patch, ``-v3`` for a third, and so forth.
     460
     461Patches created using ``git format-patch`` are formatted so they can be emailed
     462and rely on having Git configured with your name and email address, for example
     463
     464.. code-block:: shell
     465
     466  git config --global user.name "Your Name"
     467  git config --global user.email name@domain.com
     468
     469Please use a real name, we do not allow pseudonyms or anonymous contributions.
     470
     471Submitting a Patch
     472------------------
     473
     474Using ``git send-email`` you can easily contribute your patches. You will need
     475to install ``git send-email`` first:
     476
     477.. code-block:: shell
     478
     479  sudo yum install git-email
     480
     481or
     482
     483.. code-block:: shell
     484
     485  sudo dnf install git-email
     486
     487or
     488
     489.. code-block:: shell
     490
     491  sudo apt install git-email
     492
     493Then you will need to configure an SMTP server. You could install one on your
     494localhost, or you can connect to a mail server such as Gmail.
     495
     496Configuring git send-email to use Gmail
     497---------------------------------------
     498
     499Configure Git to use Gmail:
     500
     501.. code-block:: shell
     502
     503  git config --global sendemail.smtpserver smtp.gmail.com
     504  git config --global sendemail.smtpserverport 587
     505  git config --global sendemail.smtpencryption tls
     506  git config --global sendemail.smtpuser your_email@gmail.com
     507
     508It will ask for your password each time you use ``git send-email``. Optionally
     509you can also put it in your ``git config``:
     510
     511.. code-block:: shell
     512
     513  git config --global sendemail.smtppass your_password
     514
     515Sending Email
     516-------------
     517
     518To send your patches just
     519
     520.. code-block:: shell
     521
     522  git send-email /path/to/patch --to devel@rtems.org
     523
     524To send multiple related patches (if you have more than one commit in your
     525branch) specify a path to a directory containing all of the patches created by
     526``git format-patch``. ``git send-email`` has some useful options such as:
     527
     528* ``--annotate`` to show/edit your patch
     529* ``--cover-letter`` to prepend a summary
     530* ``--cc=<address>`` to cc someone
     531
     532You can configure the to address:
     533
     534.. code-block:: shell
     535
     536  git config --global sendemail.to devel@rtems.org
     537
     538So all you need is:
     539
     540.. code-block:: shell
     541
     542  git send-email /path/to/patch
     543
     544Troubleshooting
     545---------------
     546
     547Some restrictive corporate firewalls block access through the Git protocol
     548(​git://). If you are unable to reach the server ​git://git.rtems.org/ you can
     549try accessing through http. To clone the rtems repository using the http
     550protocol use the following command:
     551
     552.. code-block:: shell
     553
     554  git clone http://git.rtems.org/rtems/ rtems
     555
     556This access through http is slower (way slower!) than through the git protocol,
     557therefore, the Git protocol is preferred.
     558
     559Manage Your Code
     560----------------
     561
     562You may prefer to keep your application and development work in a Git
     563repository for all the good reasons that come with version control.
     564For public repositories, you may like to try `GitHub <https://github.com/>`_
     565or `BitBucket <https://bitbucket.org/>`_. RTEMS maintains
     566`mirrors on GitHub <https://github.com/RTEMS>`_ which can make synchronizing
     567with upstream changes relatively simple. If you need to keep your work private,
     568you can use one of those services with private repositories or manage your own
     569server. The details of setting up a server are outside the scope of this
     570document, but if you have a server with SSH access you should be able to `find
     571instructions
     572<https://git-scm.com/book/en/v2/Git-on-the-Server-Setting-Up-the-Server>`_ on
     573how to set up Git access. Once you have git configured on the server, adding
     574repositories is a snap.
     575
     576Private Servers
     577---------------
     578
     579In the following, replace @USER@ with your username on your server, @REPO@ with
     580the name of your repository, and @SERVER@ with your server's name or address.
     581
     582To push a mirror to your private server, first create a bare repository on your
     583server.
     584
     585.. code-block:: shell
     586
     587  cd /home/@USER@
     588  mkdir git
     589  mkdir git/@REPO@.git
     590  cd git/@REPO@.git
     591  git --bare init
     592
     593Now from your client machine (e.g. your work laptop/desktop), push a git,
     594perhaps one you cloned from elsewhere, or one that you made locally with
     595``git init``, by adding a remote and pushing:
     596
     597.. code-block:: shell
     598
     599  git remote add @SERVER@ ssh://@SERVER@/home/@USER@/git/@REPO@.git
     600  git push @SERVER@ master
     601
     602You can replace the @SERVER@ with another name for your remote if you like.
     603And now you can push other branches that you might have created. Now you can
     604push and pull between your client and your server. Use SSH keys to authenticate
     605with your server if you want to save on password typing; remember to put a
     606passphrase on your SSH key if there is a risk the private key file might get
     607compromised.
     608
     609The following is an example scenario that might be useful for RTEMS users that
     610uses a slightly different approach than the one just outlined:
     611
     612.. code-block:: shell
     613
     614  ssh @SERVER@
     615  mkdir git
     616  git clone --mirror git://git.rtems.org/rtems.git
     617  ## Add your ssh key to ~/.ssh/authorized_keys
     618  exit
     619  git clone ssh://@SERVER@/home/@USER@/git/rtems.git
     620  cd rtems
     621  git remote add upstream git://git.rtems.org/rtems.git
     622  git fetch upstream
     623  git pull upstream master
     624  git push
     625  ## If you want to track RTEMS on your personal master branch,
     626  ## you should only push changes to origin/master that you pull
     627  ## from upstream. The basic workflow should look something like:
     628  git checkout master
     629  git pull upstream master
     630  git push
     631  git checkout -b anewbranch
     632  ## Repeat: do work, git commit -a
     633  git push origin anewbranch
     634
     635  ## delete a remote branch
     636  git push origin :anewbranch
     637  ## delete a local branch
     638  git branch -d anewbranch
     639
     640Learn more about Git
     641--------------------
     642
     643Links to the sites with good Git information:
     644
     645* http://gitready.com/ - An excellent resource from beginner to very advanced.
     646* http://progit.org/book/ - Covers Git basics and some advanced features.
     647  Includes some useful workflow examples.
     648* https://lab.github.com/ - Learn to use Git and GitHub while doing a series of
     649  projects.
     650* https://git-scm.com/docs - The official Git reference.
Note: See TracChangeset for help on using the changeset viewer.