Changeset 7e91a8f in rtems-docs

Dec 3, 2018, 5:01:40 PM (5 months ago)
Marçal Comajoan Cara <mcomajoancara@…>
Marçal Comajoan Cara <mcomajoancara@…> (12/03/18 17:01:40)
Joel Sherrill <joel@…> (12/18/18 00:45:49)

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

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.

1 edited


  • eng/vc-users.rst

    rf4782c9 r7e91a8f  
    10 TBD - Convert to Rest
    11 TBD - and insert here.
     10.. COMMENT: TBD - Convert to
     11.. COMMENT: TBD - Rest and insert here.
     13.. COMMENT: TBD - Managing a (private/public) Git mirror, using GitHub,
     14.. COMMENT: TBD - submitting pull requests...
     16Browse the Git Repository Online
     19You can browse all available repositories online by
     22Using the Git Repository
     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.
     29First, we need to obtain our own local copy of the RTEMS Git repository:
     31.. code-block:: shell
     33  git clone git:// rtems
     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.
     41To see all available remote branches issue the following command:
     43.. code-block:: shell
     45  git branch -r
     47We can check out one of those remote branches (e.g. rtems-4.10 branch) using
     48the command:
     50.. code-block:: shell
     52  git checkout -b rtems410 origin/4.10
     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:// The ``git branch`` command prints a list of
     57the current local branches, indicating the one currently checked out.
     59If you want to switch between local branches:
     61.. code-block:: shell
     63  git checkout <branch-name>
     65With time your local repository will diverge from the main RTEMS repository. To
     66keep your local copy up to date you need to issue:
     68.. code-block:: shell
     70  git pull origin
     72This command will update all your local branches with any new code revisions
     73available on the central repository.
     75Making Changes
     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.
     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.
     91First, you need to clone the repository:
     93.. code-block:: shell
     95  git clone git:// rtems
     97Or if you already cloned it before, then you might want to update to the latest
     98version before making your changes:
     100.. code-block:: shell
     102  cd rtems
     103  git pull
     105Create a local branch to make your changes in, in this example, the change is
     108.. code-block:: shell
     110  git checkout -b faster-context-switch
     112Next, make your changes to files. If you add, delete ormove/rename files you
     113need to inform Git
     115.. code-block:: shell
     117  git add /some/new/file
     118  git rm /some/old/file
     119  git mv /some/old/file /some/new/file
     121When you're satisfied with the changes you made, commit them (locally)
     123.. code-block:: shell
     125  git commit -a
     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.
     132.. code-block:: shell
     134  git add /some/changed/files
     135  git commit
     137Create a patch from your branch, in this case, we have two commits we want to
     138send for review:
     140.. code-block:: shell
     142  git format-patch -2
     144 There are new changes pushed to the RTEMS' master branch and our local branch
     145 needs to be updated:
     147.. code-block:: shell
     149  git checkout master
     150  git pull
     151  git checkout faster-context-switch
     152  git rebase master
     154Working with Branches
     157Branches facilitate trying out new code and creating patches.
     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:
     162.. code-block:: shell
     164  git branch -r
     166Then check out the desired remote branch, for example:
     168.. code-block:: shell
     170  git checkout -b rtems410 origin/4.10
     172Or if you have previously checked out the remote branch then you should see it
     173in your local branches:
     175.. code-block:: shell
     177  git branch
     179You can change to an existing local branch easily:
     181.. code-block:: shell
     183  git checkout rtems410
     185You can also create a new branch and switch to it:
     187.. code-block:: shell
     189  git branch temporary
     190  git checkout temporary
     192Or more concisely:
     194.. code-block:: shell
     196  git checkout -b temporary
     198If you forget which branch you are on
     200.. code-block:: shell
     202  git branch
     204shows you by placing a * next to the current one.
     206When a branch is no longer useful you can delete it.
     208.. code-block:: shell
     210  git checkout master
     211  git branch -d temporary
     213If you have unmerged changes in the old branch Git complains and you need to
     214use ``-D`` instead of ``-d``.
     216Viewing Changes
     219To view all changes since the last commit:
     221.. code-block:: shell
     223  git diff HEAD
     225To view all changes between the current branch and another branch, say master:
     227.. code-block:: shell
     229  git diff master..HEAD
     231To view descriptions of committed changes:
     233.. code-block:: shell
     235  git log
     237Or view the changeset for some file (or directory):
     239.. code-block:: shell
     241  git log /some/file
     243To view the changesets made between two branches:
     245.. code-block:: shell
     247  git log master..HEAD
     249Or for a more brief description use shortlog:
     251.. code-block:: shell
     253  git shortlog master..HEAD
     255Reverting Changes
     258To remove all (uncommitted) changes on a branch
     260.. code-block:: shell
     262  git checkout -f
     264Or to selectively revert (uncommited) files, for example if you
     265accidentally deleted ./some/file
     267.. code-block:: shell
     269  git checkout -- ./some/file
     273.. code-block:: shell
     275  git checkout HEAD ./some/file
     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.
     282git reset
     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).
     292.. code-block:: shell
     294  git reset HEAD~
     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.
     301.. code-block:: shell
     303  git reset --soft HEAD~
     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).
     309.. code-block:: shell
     311  git reset --hard HEAD~
     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.
     317.. code-block:: shell
     319  git reset HEAD
     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')
     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.
     328git revert
     331``git revert`` does the same as reset but creates a new commit with the
     332reverted changes instead of modifying the local repository directly.
     334.. code-block:: shell
     336  git revert HEAD
     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.
     341Merging Changes
     344Suppose you commit changes in two different branches, branch1 and branch2,
     345and want to create a new branch containing both sets of changes:
     347.. code-block:: shell
     349  git checkout -b merged
     350  git merge branch1
     351  git merge branch2
     353Or you might want to bring the changes in one branch into the other:
     355.. code-block:: shell
     357  git checkout branch1
     358  git merge branch2
     360And now that branch2 is merged you might get rid of it:
     362.. code-block:: shell
     364  git branch -d branch2
     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:
     370.. code-block:: shell
     372  git checkout master
     373  git pull
     374  git checkout branch1
     375  git merge master
     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.
     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.
     390For example
     392.. code-block:: shell
     394  git checkout branch1
     395  git rebase master
     397or more concisely
     399.. code-block:: shell
     401  git rebase master branch1
     403will bring the changes of master into branch1, and then you can fast-forward
     404master to include branch1 quite easily
     406.. code-block:: shell
     408  git checkout master
     409  git merge branch1
     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.
     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.
     425Accessing a developer's repository
     428RTEMS developers with Git commit access have personal repositories
     429on that can be cloned to view cutting-edge
     430development work shared there.
     432Creating a Patch
     435Before submitting a patch read about `Contributing
     436<>`_ to RTEMS and the
     437`Commit Message <>`_
     438formatting we require.
     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.
     444.. code-block:: shell
     446  git format-patch master
     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.
     452If you are re-submitting a patch that has previously been reviewed, you should
     453specify a version number for your patch, for example, use
     455.. code-block:: shell
     457  git format-patch -v2 ...
     459to indicate the second version of a patch, ``-v3`` for a third, and so forth.
     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
     464.. code-block:: shell
     466  git config --global "Your Name"
     467  git config --global
     469Please use a real name, we do not allow pseudonyms or anonymous contributions.
     471Submitting a Patch
     474Using ``git send-email`` you can easily contribute your patches. You will need
     475to install ``git send-email`` first:
     477.. code-block:: shell
     479  sudo yum install git-email
     483.. code-block:: shell
     485  sudo dnf install git-email
     489.. code-block:: shell
     491  sudo apt install git-email
     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.
     496Configuring git send-email to use Gmail
     499Configure Git to use Gmail:
     501.. code-block:: shell
     503  git config --global sendemail.smtpserver
     504  git config --global sendemail.smtpserverport 587
     505  git config --global sendemail.smtpencryption tls
     506  git config --global sendemail.smtpuser
     508It will ask for your password each time you use ``git send-email``. Optionally
     509you can also put it in your ``git config``:
     511.. code-block:: shell
     513  git config --global sendemail.smtppass your_password
     515Sending Email
     518To send your patches just
     520.. code-block:: shell
     522  git send-email /path/to/patch --to
     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:
     528* ``--annotate`` to show/edit your patch
     529* ``--cover-letter`` to prepend a summary
     530* ``--cc=<address>`` to cc someone
     532You can configure the to address:
     534.. code-block:: shell
     536  git config --global
     538So all you need is:
     540.. code-block:: shell
     542  git send-email /path/to/patch
     547Some restrictive corporate firewalls block access through the Git protocol
     548(​git://). If you are unable to reach the server ​git:// you can
     549try accessing through http. To clone the rtems repository using the http
     550protocol use the following command:
     552.. code-block:: shell
     554  git clone rtems
     556This access through http is slower (way slower!) than through the git protocol,
     557therefore, the Git protocol is preferred.
     559Manage Your Code
     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 <>`_
     565or `BitBucket <>`_. RTEMS maintains
     566`mirrors on GitHub <>`_ 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
     572<>`_ on
     573how to set up Git access. Once you have git configured on the server, adding
     574repositories is a snap.
     576Private Servers
     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.
     582To push a mirror to your private server, first create a bare repository on your
     585.. code-block:: shell
     587  cd /home/@USER@
     588  mkdir git
     589  mkdir git/@REPO@.git
     590  cd git/@REPO@.git
     591  git --bare init
     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:
     597.. code-block:: shell
     599  git remote add @SERVER@ ssh://@SERVER@/home/@USER@/git/@REPO@.git
     600  git push @SERVER@ master
     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
     609The following is an example scenario that might be useful for RTEMS users that
     610uses a slightly different approach than the one just outlined:
     612.. code-block:: shell
     614  ssh @SERVER@
     615  mkdir git
     616  git clone --mirror 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://
     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
     635  ## delete a remote branch
     636  git push origin :anewbranch
     637  ## delete a local branch
     638  git branch -d anewbranch
     640Learn more about Git
     643Links to the sites with good Git information:
     645* - An excellent resource from beginner to very advanced.
     646* - Covers Git basics and some advanced features.
     647  Includes some useful workflow examples.
     648* - Learn to use Git and GitHub while doing a series of
     649  projects.
     650* - The official Git reference.
Note: See TracChangeset for help on using the changeset viewer.