[PATCH] eng/vc-users: Convert wiki page to Rest

Marçal Comajoan Cara mcomajoancara at gmail.com
Mon Dec 3 17:11:49 UTC 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.
---
 eng/vc-users.rst | 643 ++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 641 insertions(+), 2 deletions(-)

diff --git a/eng/vc-users.rst b/eng/vc-users.rst
index ebd79bb..47864b4 100644
--- a/eng/vc-users.rst
+++ b/eng/vc-users.rst
@@ -7,5 +7,644 @@
 Software Development (Git Users)
 ********************************
 
-TBD - Convert https://devel.rtems.org/wiki/Developer/Git/Users to Rest
-TBD - and insert here.
+.. COMMENT: TBD - Convert https://devel.rtems.org/wiki/Developer/Git/Users to
+.. COMMENT: TBD - Rest and insert here.
+
+.. COMMENT: TBD - Managing a (private/public) Git mirror, using GitHub,
+.. COMMENT: TBD - submitting pull requests...
+
+Browse the Git Repository Online
+--------------------------------
+
+You can browse all available repositories online by
+accessing https://git.rtems.org/.
+
+Using the Git Repository
+------------------------
+
+The following examples demonstrate how to use the RTEMS' Git repos. These 
+examples are provided for the main rtems module, but they are also valid
+for the other modules.
+
+First, we need to obtain our own local copy of the RTEMS Git repository:
+
+.. code-block:: shell
+
+  git clone git://git.rtems.org/rtems.git rtems
+
+This command will create a folder named rtems in the current directory. This
+folder will contain a full-featured RTEMS' Git repository and the current HEAD
+revision checked out. Since all the history is available we can check out any
+release of RTEMS. Major RTEMS releases are available as separate branches in
+the repo.
+
+To see all available remote branches issue the following command:
+
+.. code-block:: shell
+
+  git branch -r
+
+We can check out one of those remote branches (e.g. rtems-4.10 branch) using
+the command:
+
+.. code-block:: shell
+
+  git checkout -b rtems410 origin/4.10
+
+This will create a local branch named "rtems410", containing the rtems-4.10
+release, that will track the remote branch "rtems-4-10-branch" in origin
+(​git://git.rtems.org/rtems.git). The ``git branch`` command prints a list of
+the current local branches, indicating the one currently checked out.
+
+If you want to switch between local branches:
+
+.. code-block:: shell
+
+  git checkout <branch-name>
+
+With time your local repository will diverge from the main RTEMS repository. To
+keep your local copy up to date you need to issue:
+
+.. code-block:: shell
+
+  git pull origin
+
+This command will update all your local branches with any new code revisions
+available on the central repository.
+
+Making Changes
+--------------
+
+Git allows you to make changes in the RTEMS source tree and track those changes
+locally. We recommend you make all your changes in local branches. If you are
+working on a few different changes or a progression of changes it is best to
+use a local branch for each change.
+
+A branch for each change lets your repo's master branch track the upstream
+RTEMS' master branch without interacting with any of the changes you are
+working on. A completed change is emailed to the developer's list for review
+and this can take time. While this is happening the upstream's master branch
+may be updated and you may need to rebase your work and test again if you are
+required to change or update your patch. A local branch isolates a specific
+change from others and helps you manage the process.
+
+First, you need to clone the repository: 
+
+.. code-block:: shell
+
+  git clone git://git.rtems.org/rtems.git rtems
+
+Or if you already cloned it before, then you might want to update to the latest
+version before making your changes:
+
+.. code-block:: shell
+
+  cd rtems
+  git pull
+
+Create a local branch to make your changes in, in this example, the change is
+``faster-context-switch``:
+
+.. code-block:: shell
+
+  git checkout -b faster-context-switch
+
+Next, make your changes to files. If you add, delete ormove/rename files you
+need to inform Git
+
+.. code-block:: shell
+
+  git add /some/new/file
+  git rm /some/old/file
+  git mv /some/old/file /some/new/file
+
+When you're satisfied with the changes you made, commit them (locally)
+
+.. code-block:: shell
+
+  git commit -a
+
+The ``-a`` flag commits all the changes that were made, but you can also
+control which changes to commit by individually adding files as you modify
+them by using. You can also specify other options to commit, such as a message
+with the ``-m`` flag.
+
+.. code-block:: shell
+
+  git add /some/changed/files
+  git commit
+
+Create a patch from your branch, in this case, we have two commits we want to
+send for review:
+
+.. code-block:: shell
+
+  git format-patch -2
+
+ There are new changes pushed to the RTEMS' master branch and our local branch
+ needs to be updated:
+
+.. code-block:: shell
+
+  git checkout master
+  git pull
+  git checkout faster-context-switch
+  git rebase master
+
+Working with Branches
+---------------------
+
+Branches facilitate trying out new code and creating patches.
+
+The previous releases of RTEMS are available through remote branches. To check
+out a remote branch, first query the Git repository for the list of branches:
+
+.. code-block:: shell
+
+  git branch -r
+
+Then check out the desired remote branch, for example:
+
+.. code-block:: shell
+
+  git checkout -b rtems410 origin/4.10
+
+Or if you have previously checked out the remote branch then you should see it
+in your local branches:
+
+.. code-block:: shell
+
+  git branch
+
+You can change to an existing local branch easily:
+
+.. code-block:: shell
+
+  git checkout rtems410
+
+You can also create a new branch and switch to it:
+
+.. code-block:: shell
+
+  git branch temporary
+  git checkout temporary
+
+Or more concisely:
+
+.. code-block:: shell
+
+  git checkout -b temporary
+
+If you forget which branch you are on
+
+.. code-block:: shell
+
+  git branch
+
+shows you by placing a * next to the current one.
+
+When a branch is no longer useful you can delete it. 
+
+.. code-block:: shell
+
+  git checkout master
+  git branch -d temporary
+
+If you have unmerged changes in the old branch Git complains and you need to
+use ``-D`` instead of ``-d``.
+
+Viewing Changes
+---------------
+
+To view all changes since the last commit:
+
+.. code-block:: shell
+
+  git diff HEAD
+
+To view all changes between the current branch and another branch, say master:
+
+.. code-block:: shell
+
+  git diff master..HEAD
+
+To view descriptions of committed changes:
+
+.. code-block:: shell
+
+  git log
+
+Or view the changeset for some file (or directory): 
+
+.. code-block:: shell
+
+  git log /some/file
+
+To view the changesets made between two branches:
+
+.. code-block:: shell
+
+  git log master..HEAD
+
+Or for a more brief description use shortlog:
+
+.. code-block:: shell
+
+  git shortlog master..HEAD
+
+Reverting Changes
+-----------------
+
+To remove all (uncommitted) changes on a branch
+
+.. code-block:: shell
+
+  git checkout -f
+
+Or to selectively revert (uncommited) files, for example if you
+accidentally deleted ./some/file
+
+.. code-block:: shell
+
+  git checkout -- ./some/file
+
+or
+
+.. code-block:: shell
+
+  git checkout HEAD ./some/file
+
+To remove commits there are two useful options, reset and revert. ``git reset``
+should only be used on local branches that no one else is accessing remotely.
+``git revert`` is cleaner and is the right way to revert changes that have
+already been pushed/pulled remotely.
+
+git reset
+---------
+
+``git reset`` is a powerful and tricky command that should only be used on
+local (un-pushed) branches): A good description of what it enables to do can be
+found ​here. The following are a few useful examples. Note that adding a ~
+after HEAD refers to the most recent commit, and you can add a number after
+the ~ to refer to commits even further back; HEAD by itself refers to the
+current working directory (changes since the last commit).
+
+.. code-block:: shell
+
+  git reset HEAD~
+
+Will undo the last commit and unstage those changes. Your working directory
+will remain the same, therefore a ``git status`` will yield any changes you
+made plus the changes made in your last commit. This can be used to fix the
+last commit. You will need to add the files again. 
+
+.. code-block:: shell
+
+  git reset --soft HEAD~
+
+Will just undo the last commit. The changes from the last commit will still be
+staged (just as if you finished git adding them). This can be used to amend the
+last commit (e.g. You forgot to add a file to the last commit).
+
+.. code-block:: shell
+
+  git reset --hard HEAD~
+
+Will revert everything, including the working directory, to the previous
+commit. This is dangerous and can lead to you losing all your changes; the
+``--hard`` flag ignores errors.
+
+.. code-block:: shell
+
+  git reset HEAD
+
+Will unstage any change. This is used to revert a wrong ``git add``. (e.g. You
+added a file that shouldn't be there, but you haven't 'committed')
+
+Will revert your working directory to a HEAD state. You will lose any change
+you made to files after the last commit. This is used when you just want to
+destroy all changes you made since the last commit.
+
+git revert
+----------
+
+``git revert`` does the same as reset but creates a new commit with the
+reverted changes instead of modifying the local repository directly.
+
+.. code-block:: shell
+
+  git revert HEAD
+
+This will create a new commit which undoes the change in HEAD. You will be
+given a chance to edit the commit message for the new commit.
+
+Merging Changes
+---------------
+
+Suppose you commit changes in two different branches, branch1 and branch2,
+and want to create a new branch containing both sets of changes:
+
+.. code-block:: shell
+
+  git checkout -b merged
+  git merge branch1
+  git merge branch2
+
+Or you might want to bring the changes in one branch into the other:
+
+.. code-block:: shell
+
+  git checkout branch1
+  git merge branch2
+
+And now that branch2 is merged you might get rid of it:
+
+.. code-block:: shell
+
+  git branch -d branch2
+
+If you have done work on a branch, say branch1, and have gone out-of-sync
+with the remote repository, you can pull the changes from the remote repo and
+then merge them into your branch:
+
+.. code-block:: shell
+
+  git checkout master
+  git pull
+  git checkout branch1
+  git merge master
+
+If all goes well the new commits you pulled into your master branch will be
+merged into your branch1, which will now be up-to-date. However, if branch1
+has not been pushed remotely then rebasing might be a good alternative to
+merging because the merge generates a commit.
+
+Rebasing
+--------
+
+An alternative to the merge command is rebase, which replays the changes
+(commits) on one branch onto another. ``git rebase`` finds the common ancestor
+of the two branches, stores each commit of the branch you’re on to temporary
+files and applies each commit in order.
+
+For example
+
+.. code-block:: shell
+
+  git checkout branch1
+  git rebase master
+
+or more concisely
+
+.. code-block:: shell
+
+  git rebase master branch1
+
+will bring the changes of master into branch1, and then you can fast-forward
+master to include branch1 quite easily
+
+.. code-block:: shell
+
+  git checkout master
+  git merge branch1
+
+Rebasing makes a cleaner history than merging; the log of a rebased branch
+looks like a linear history as if the work was done serially rather than in
+parallel. A primary reason to rebase is to ensure commits apply cleanly on a
+remote branch, e.g. when submitting patches to RTEMS that you create by working
+on a branch in a personal repository. Using rebase to merge your work with the
+remote branch eliminates most integration work for the committer/maintainer.
+
+There is one caveat to using rebase: Do not rebase commits that you have pushed
+to a public repository. Rebase abandons existing commits and creates new ones
+that are similar but different. If you push commits that others pull down, and
+then you rewrite those commits with ``git rebase`` and push them up again, the
+others will have to re-merge their work and trying to integrate their work
+into yours can become messy.
+
+Accessing a developer's repository
+----------------------------------
+
+RTEMS developers with Git commit access have personal repositories
+on https://git.rtems.org/ that can be cloned to view cutting-edge
+development work shared there.
+
+Creating a Patch
+----------------
+
+Before submitting a patch read about `Contributing
+<https://devel.rtems.org/wiki/Developer/Contributing>`_ to RTEMS and the
+`Commit Message <https://devel.rtems.org/wiki/Developer/Git#GitCommits>`_
+formatting we require.
+
+The recommended way to create a patch is to branch the Git repository master
+and use one commit for each logical change. Then you can use
+``git format-patch`` to turn your commits into patches and easily submit them.
+
+.. code-block:: shell
+
+  git format-patch master
+
+Creates a separate patch for each commit that has been made between the master
+branch and the current branch and writes them in the current directory. Use the
+``-o`` flag to redirect the files to a different directory. 
+
+If you are re-submitting a patch that has previously been reviewed, you should
+specify a version number for your patch, for example, use
+
+.. code-block:: shell
+
+  git format-patch -v2 ...
+
+to indicate the second version of a patch, ``-v3`` for a third, and so forth.
+
+Patches created using ``git format-patch`` are formatted so they can be emailed
+and rely on having Git configured with your name and email address, for example
+
+.. code-block:: shell
+
+  git config --global user.name "Your Name"
+  git config --global user.email name at domain.com
+
+Please use a real name, we do not allow pseudonyms or anonymous contributions.
+
+Submitting a Patch
+------------------
+
+Using ``git send-email`` you can easily contribute your patches. You will need
+to install ``git send-email`` first:
+
+.. code-block:: shell
+
+  sudo yum install git-email
+
+or 
+
+.. code-block:: shell
+
+  sudo dnf install git-email
+
+or
+
+.. code-block:: shell
+
+  sudo apt install git-email
+
+Then you will need to configure an SMTP server. You could install one on your
+localhost, or you can connect to a mail server such as Gmail.
+
+Configuring git send-email to use Gmail
+---------------------------------------
+
+Configure Git to use Gmail:
+
+.. code-block:: shell
+
+  git config --global sendemail.smtpserver smtp.gmail.com
+  git config --global sendemail.smtpserverport 587
+  git config --global sendemail.smtpencryption tls
+  git config --global sendemail.smtpuser your_email at gmail.com
+
+It will ask for your password each time you use ``git send-email``. Optionally
+you can also put it in your ``git config``:
+
+.. code-block:: shell
+
+  git config --global sendemail.smtppass your_password
+
+Sending Email
+-------------
+
+To send your patches just
+
+.. code-block:: shell
+
+  git send-email /path/to/patch --to devel at rtems.org
+
+To send multiple related patches (if you have more than one commit in your
+branch) specify a path to a directory containing all of the patches created by
+``git format-patch``. ``git send-email`` has some useful options such as:
+
+* ``--annotate`` to show/edit your patch
+* ``--cover-letter`` to prepend a summary
+* ``--cc=<address>`` to cc someone
+
+You can configure the to address:
+
+.. code-block:: shell
+
+  git config --global sendemail.to devel at rtems.org
+
+So all you need is:
+
+.. code-block:: shell
+
+  git send-email /path/to/patch
+
+Troubleshooting
+---------------
+
+Some restrictive corporate firewalls block access through the Git protocol
+(​git://). If you are unable to reach the server ​git://git.rtems.org/ you can
+try accessing through http. To clone the rtems repository using the http
+protocol use the following command:
+
+.. code-block:: shell
+
+  git clone http://git.rtems.org/rtems/ rtems
+
+This access through http is slower (way slower!) than through the git protocol,
+therefore, the Git protocol is preferred.
+
+Manage Your Code
+----------------
+
+You may prefer to keep your application and development work in a Git
+repository for all the good reasons that come with version control.
+For public repositories, you may like to try `GitHub <https://github.com/>`_
+or `BitBucket <https://bitbucket.org/>`_. RTEMS maintains
+`mirrors on GitHub <https://github.com/RTEMS>`_ which can make synchronizing
+with upstream changes relatively simple. If you need to keep your work private,
+you can use one of those services with private repositories or manage your own
+server. The details of setting up a server are outside the scope of this
+document, but if you have a server with SSH access you should be able to `find
+instructions
+<https://git-scm.com/book/en/v2/Git-on-the-Server-Setting-Up-the-Server>`_ on
+how to set up Git access. Once you have git configured on the server, adding
+repositories is a snap.
+
+Private Servers
+---------------
+
+In the following, replace @USER@ with your username on your server, @REPO@ with
+the name of your repository, and @SERVER@ with your server's name or address.
+
+To push a mirror to your private server, first create a bare repository on your
+server.
+
+.. code-block:: shell
+
+  cd /home/@USER@
+  mkdir git
+  mkdir git/@REPO at .git
+  cd git/@REPO at .git
+  git --bare init
+
+Now from your client machine (e.g. your work laptop/desktop), push a git,
+perhaps one you cloned from elsewhere, or one that you made locally with
+``git init``, by adding a remote and pushing:
+
+.. code-block:: shell
+
+  git remote add @SERVER@ ssh://@SERVER@/home/@USER@/git/@REPO@.git
+  git push @SERVER@ master
+
+You can replace the @SERVER@ with another name for your remote if you like.
+And now you can push other branches that you might have created. Now you can
+push and pull between your client and your server. Use SSH keys to authenticate
+with your server if you want to save on password typing; remember to put a
+passphrase on your SSH key if there is a risk the private key file might get
+compromised.
+
+The following is an example scenario that might be useful for RTEMS users that
+uses a slightly different approach than the one just outlined:
+
+.. code-block:: shell
+
+  ssh @SERVER@
+  mkdir git
+  git clone --mirror git://git.rtems.org/rtems.git
+  ## Add your ssh key to ~/.ssh/authorized_keys
+  exit
+  git clone ssh://@SERVER@/home/@USER@/git/rtems.git
+  cd rtems
+  git remote add upstream git://git.rtems.org/rtems.git
+  git fetch upstream
+  git pull upstream master
+  git push
+  ## If you want to track RTEMS on your personal master branch,
+  ## you should only push changes to origin/master that you pull
+  ## from upstream. The basic workflow should look something like:
+  git checkout master
+  git pull upstream master
+  git push
+  git checkout -b anewbranch
+  ## Repeat: do work, git commit -a
+  git push origin anewbranch
+
+  ## delete a remote branch
+  git push origin :anewbranch
+  ## delete a local branch
+  git branch -d anewbranch
+
+Learn more about Git
+--------------------
+
+Links to the sites with good Git information:
+
+* http://gitready.com/ - An excellent resource from beginner to very advanced. 
+* http://progit.org/book/ - Covers Git basics and some advanced features.
+  Includes some useful workflow examples.
+* https://lab.github.com/ - Learn to use Git and GitHub while doing a series of
+  projects.
+* https://git-scm.com/docs - The official Git reference.
-- 
2.17.1

More information about the devel mailing list