Changes between Version 46 and Version 47 of Developer/Git

Feb 29, 2012, 9:27:21 PM (7 years ago)

/* Move content */ Move the sub-heading under GIT Access for users to a new page.


  • Developer/Git

    v46 v47  
    8 RTEMS project's revision control tool is GIT and the git repositories can be located at
     8RTEMS project's revision control tool is Git and the git repositories can be located at
    99=  Why git?  =
    1212Git is a distributed revision control system with an emphasis on speed and data safety. With git revision control system each user has a full featured copy of the main repository. Each revision control operation is done in the local repository and can be later shared using patches or by direct push to the main repository.
    13 = RTEMS GIT Repositories  =
     13= RTEMS Git Repositories  =
    2525 *  rtems-graphics-toolkit.git - Graphic support libraries for RTEMS.
    2626 *  rtems-schedsim-git - Scheduling Simulator
    27 = RTEMS GIT Server  =
     27= RTEMS Git Server  =
    29 RTEMS has a dedicated GIT server. The machine runs cgit to provide a web interface to GIT, the GIT protocol for direct read-only access and ssh accounts for those with commit access. The configuration is standard with the only hook currently used to send commit details to the mailing list.
    30 =  GIT Access for users  =
     29RTEMS has a dedicated Git server. The machine runs cgit to provide a web interface to GIT, the GIT protocol for direct read-only access and ssh accounts for those with commit access. The configuration is standard with the only hook currently used to send commit details to the mailing list.
     30=  Git Access for Users  =
    33 The git repository is available read-only to the public at large. Only a small subset of selected people have write permission, but everyone is welcome to commit a patch with proper licensing. See the [wiki:Developer/GitUsers Git Users] page with instructions and some useful git commands.
    34 = Browse the GIT Repository Online =
     33The git repository is available read-only to the public at large, and anyone is welcome to submit a patch (with proper licensing) by mailing it to the [wiki:Rtems-devel_mailing_list Mailing Lists] or [wiki:Filing_a_bug_report Bugzilla]. See the [wiki:Developer/GitUsers Git Users] page for access instructions and some useful git commands.
     34=  Git Access for Committers =
    37 You can browse our GIT history of all available repositories online by accessing
    38 = Using the GIT Repository =
    41 The following examples demostrate how to use the RTEMS' git repo. These examples are provided for the main rtems module, but they are also valid for the other modules.
    43 First we need to obtain our own local copy of the RTEMS git repository:
    44 {{{
    45  git clone git:// rtems
    46 }}}
    47 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.
    48 Since all the history is available we can checkout any release of RTEMS. Major RTEMS releases are available as separate branches in the repo.
    50 To see all available remote branches issue the following command:
    51 {{{
    52  git branch -r
    53 }}}
    55 We can checkout one of those remote branches (e.g. rtems-4.10 branch) using the command:
    56 {{{
    57  git checkout -b rtems410 origin/4.10
    58 }}}
    59 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:// The 'git branch' command prints a list of the current local branches, indicating the one currently checked out.
    61 If you want to switch between local branches:
    62 {{{
    63  git checkout <branch-name>
    64 }}}
    66 With time your local repository will diverge from the main RTEMS repository. To keep your local copy up to date you need to issue:
    67 {{{
    68  git pull origin
    69 }}}
    70 This command will update all your local branches with any new code revisions available on the central repository.
    71 = Making Changes =
    73 Git allows you to make changes in the RTEMS source tree and track those changes locally. First you need to clone the repository:
    74 {{{
    75  git clone git:// rtems
    76 }}}
    77 Or if you already cloned it before, then you might want to update to the latest version before making your changes:
    78 {{{
    79  cd rtems
    80  git pull
    81 }}}
    82 Next make your changes to files. If you add, delete or move/rename files you need to inform Git
    83 {{{
    84  git add /some/new/file
    85  git rm /some/old/file
    86  git mv /some/old/file /some/new/file
    87 }}}
    88 When you're satisfied with the changes you made, commit them (locally)
    89 {{{
    90  git commit -a
    91 }}}
    92 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.
    93 {{{
    94  git add /some/changed/files
    95  git commit
    96 }}}
    97 But you shouldn't do any of this on the branch that you cloned, instead you should create a new branch to work with, so that the cloned branch (master) is a pristine copy of the upstream RTEMS repository.
    98 = Working with Branches =
    100 Branches facilitate trying out new code and creating patches.
    102 Previous release of RTEMS are available through remote branches. To check out a remote branch, first query the Git repository for the list of branches:
    103 {{{
    104  git branch -r
    105 }}}
    106 Then checkout the desired remote branch, for example:
    107 {{{
    108  git checkout -b rtems410 origin/4.10
    109 }}}
    111 Or if you have previously checked out the remote branch then you should see it in your local branches:
    112 {{{
    113  git branch
    114 }}}
    115 You can change to an existing local branch easily:
    116 {{{
    117  git checkout rtems410
    118 }}}
    120 You can also create a new branch and switch to it:
    121 {{{
    122  git branch temporary
    123  git checkout temporary
    124 }}}
    125 Or more concisely:
    126 {{{
    127  git checkout -b temporary
    128 }}}
    130 If you forget which branch you are on
    131 {{{
    132  git branch
    133 }}}
    134 shows you by placing a * next to the current one.
    136 When a branch is no longer useful you can delete it.
    137 {{{
    138  git checkout master
    139  git branch -d temporary
    140 }}}
    141 If you have unmerged changes in the old branch git complains and you need to use -D instead of -d.
    142 = Viewing Changes =
    145 To view all changes since the last commit:
    146 {{{
    147  git diff HEAD
    148 }}}
    150 To view all changes between the current branch and another branch, say master:
    151 {{{
    152  git diff master..HEAD
    153 }}}
    155 To view descriptions of committed changes:
    156 {{{
    157  git log
    158 }}}
    159 Or view the changeset for some file (or directory):
    160 {{{
    161  git log /some/file
    162 }}}
    164 To view the changesets made between two branches:
    165 {{{
    166  git log master..HEAD
    167 }}}
    168 Or for a more brief description use shortlog:
    169 {{{
    170  git shortlog master..HEAD
    171 }}}
    172 = Reverting Changes =
    175 To remove all (uncommitted) changes on a branch
    176 {{{
    177  git checkout -f
    178 }}}
    179 Or to selectively revert (uncommited) files, for example if you accidentally deleted ./some/file
    180 {{{
    181  git checkout -- ./some/file
    182 }}}
    183 or
    184 {{{
    185  git checkout HEAD ./some/file
    186 }}}
    188 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.
    189 = git reset =
    191 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 last commit).
    192 {{{
    193 git reset HEAD~
    194 }}}
    195 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.
    197 {{{
    198 git reset --soft HEAD~
    199 }}}
    200 Will just undo the last commit. The changes from 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. I forgot to add a file to the last commit).
    202 {{{
    203 git reset --hard HEAD~
    204 }}}
    205 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.
    207 {{{
    208 git reset HEAD
    209 }}}
    210 Will unstage any change. This is used to revert a wrong git add. (e.g. I added a file that shouldn't be there, but I haven't 'committed')
    212 {{{
    213 git reset --hard HEAD
    214 }}}
    215 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.
    216 = git revert =
    218 git revert does the same as reset but creates a new commit with the reverted changes instead of modifying the local repository directly.
    219 {{{
    220  git revert HEAD
    221 }}}
    222 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.
    223 = Merging Changes =
    225 Suppose you commit changes in two different branches, branch1 and branch2, and want to create a new branch containing both sets of changes:
    226 {{{
    227  git checkout -b merged
    228  git merge branch1
    229  git merge branch2
    230 }}}
    232 Or you might want to bring the changes in one branch into the other:
    233 {{{
    234  git checkout branch1
    235  git merge branch2
    236 }}}
    238 And now that branch2 is merged you might get rid of it:
    239 {{{
    240  git branch -d branch2
    241 }}}
    243 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:
    244 {{{
    245  git checkout master
    246  git pull
    247  git checkout branch1
    248  git merge master
    249 }}}
    250 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
    251 = Rebasing =
    253 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.
    255 For example
    256 {{{
    257  git checkout branch1
    258  git rebase master
    259 }}}
    260 or more concisely
    261 {{{
    262  git rebase master branch1
    263 }}}
    264 will bring the changes of master into branch1, and then you can fast-forward master to include branch1 quite easily
    265 {{{
    266  git checkout master
    267  git merge branch1
    268 }}}
    270 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.
    272 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.
    273 = Creating a Patch =
    275 The easiest way to create a patch is to make and commit changes in a branch and then use either diff or format-patch comparing against the upstream master branch. (Of course, if the patch is supposed to be against a different branch then you should substitute that branch's name for master.)
    276 {{{
    277  git diff master..HEAD > ../rtems.diff
    278 }}}
    279 Creates a diff containing the changes made in the current branch's commits since the master branch. Here I redirected the output to a file in the parent directory.
    280 {{{
    281  git format-patch master
    282 }}}
    283 Creates a separate patch for each commit that has been made between the master branch and the current branch's head. These files, appended with .patch, are formatted so they can be emailed and rely on having git configured with your name and email address, for example
    284 {{{
    285  git config --global "Your Name"
    286  git config --global
    287 }}}
    289 Submit your patch to the [wiki:RTEMSMailingLists_  rtems-devel mailing list] and if the patch fixes a bug, file a PR on the [wiki:Bugzilla Bugzilla].
    290 =  GIT Access for contributors  =
     36A small set of selected people have write permission.
    29237TODO: Some guidelines for anyone who wishes to contribute to rtems... Patches? Pull Requests?...
    437182# git push upstream somebranch:master
    439 =  Troubleshooting  =
    442 Some restrictive corporate firewalls block access through the git protocol (git://) If you are unable to reach the server git:// you can try accessing through http. To clone the rtems repository using the http protocol use the following command:
    444 {{{
    445 git clone rtems
    446 }}}
    448 This access through http is slower (way slower!) than through the git protocol therefore the git protocol is preferred. 
    449184=  Learn more about Git  =
    450185Links to site with good Git information.