{{tag>english}}{{tag>stub}}

===== Pull UHSD source code from Github =====

==== Option: Download the zippd UHSDR ====
  * The easiest approach is to donload the zipped UHSDR source code from [[https://github.com/df8oe/UHSDR|Github UHSDR repository]] and unpack.
  * If using Eclipse: create a work space pointing at the local directory where UHSDR has been unpacked. Check Eclipse settings after that (active build etc.)

==== Option: Use "Github Desktop" ====
  * Download [[https://desktop.github.com/|Github Desktop]]. The .exe file is the executable (portable) program and does not need installation
  * Provide your github username and password, clone the [[https://github.com/df8oe/UHSDR|Github UHSDR repository]]
  * Optional: Create a local branch for your source code changes
  * If using Eclipse: create a work space pointing at the local directory where UHSDR has been unpacked. Check Eclipse settings after that (active build etc.)
 
==== Option: Use "git" on command line level, command line style ====

A git cheat sheet can be found {{ :en:uhsdr_dev:git_cheat_sheet.pdf |here}}

=== Fork UHSDR to your own remote github repo ===
  * Create github account if needed, or sign into github
  * Goto https://github.com/df8oe/UHSDR and create a fork - which will be located in your github space
  * Note the URL of your github fork, e.g. https://github.com/DF9TS/UHSDR-1

=== Pull UHSDR from Github ===
  * If git is not intalled on your system: <code>$apt-get install git</code>
  * Clone UHSDR repository: Go to the directory where you want to store the GIT clone, then create a local clone. Use the URL for your github fork, e.g. <code>$git clone https://github.com/DF9TS/UHSDR-1</code>
  * You now have a local clone of your fork in the current local directory
  * Check the remote repos assigned <code>git remote -v</code>
  * Add DF8OE UHSD repo as upstream remote repo so that you can esaly synch it with your fork: <code>git remote add upstream https://github.com/df8oe/UHSDR</code>
  * Check with "git remote -v" that upstream has been added. You now have two remote repos: "origin" which is your fork on github, and "upstream" which is the DF8OE master repo

=== Rebase: Synchronising your fork with UHSDR DF8OE repo ===
  * You want to synchronise your forked UHSDR with the DF8OE main repo from time to time to include the latest changes of UHSDR into your fork.
  * For that use <code> git pull --rebase upstream active-devel</code>
  * Your local fork is now synchronised with UHSDR DF8OE repo
  * Next you need to push these changes to your remote github repo <code>git push origin active-devel</code>
  * Your github fork is now synchronised with DF8OE UHSDR main repo

=== Creating branches for tests and experiments ===
Before creating any new branch please pull the changes from upstream as explained above. Make sure your forked repo is up to date.

  * Create the branch on your local machine and switch in this branch :<code>$ git checkout -b [name_of_your_new_branch]</code>
  * Change working branch : <code>$ git checkout [name_of_your_new_branch]</code>
  * Push the branch from local repo onto remote github : <code>$ git push origin [name_of_your_new_branch]</code>
  * When you want to commit something in your branch, be sure to be in your branch. Add -u parameter to set upstream. To check current branch use <code>$ git branch</code>
  * Add a new remote for your branch : <code>$ git remote add [name_of_your_remote]</code> 
  * Push changes from your commit into your branch : <code>$ git push [name_of_your_new_remote] [name_of_your_branch]</code>
  * Update your branch when the original branch from official repository has been updated : <code>$ git fetch [name_of_your_remote]</code>
  * Then you need to apply to merge changes, if your branch is derivated from develop you need to do : <code>$ git merge [name_of_your_remote]/develop</code>
  * Delete a branch on your local filesystem : <code>$ git branch -d [name_of_your_new_branch]</code>
  * To force the deletion of local branch on your filesystem : <code>$ git branch -D [name_of_your_new_branch]</code>
  * Delete the branch on github : <code>$ git push origin :[name_of_your_new_branch]</code>

=== Use local UHSDR clone in Eclipse ===
See also GNU MCU Eclipse [[https://gnu-mcu-eclipse.github.io/eclipse/workspace/preferences/|workspace preferences]]
== Option: Create work space ==
  * Good if you need new Eclipse settings specially for this Github clone
  * There will be a new Eclipse work space assigned to this import. The new work space can have its own Eclipse settings. Everytime you switch to this work space Eclipse will change all settings accordingly.
  * Start Eclipse. File->Switch workspace->Other
  * Enter directory of local UHSDR clone.
  * When using this new work space Eclipse will use settings of UHSDR clone. So please check Eclipse settings (active build, ..)

== Option: Import UHSDR into eclipse ==
  * Good if this Github clone should work under your standard Eclipse settings
  * File->Import, then General->Existing Projects into work space, hit "Next"
  * "Select root directory”. Use "browse" button and point to local github mchf root (in my case: $HOME/uhdsrd/UHSDR/mchf-eclipse/)
  * Hit "Finish"

==== Contributing, Rebase ====
The heart of any open source project is the contributions by individuals. Source code for the project is using git currently and can be found [[https://github.com/df8oe/UHSDR|here]]. There is a good explanation of github workflow [[http://nvie.com/posts/a-successful-git-branching-model/|here]] that is worth a read before branching and hacking on the code. And an online book written directly from the git creators you can find [[https://git-scm.com/book/en/v1/|here]] - or locally {{ :en:uhsdr_dev:progit.pdf |here}}.

We have specific instructions for contributors collected in [[https://github.com/df8oe/mchf-github/blob/active-devel/CONTRIBUTING.md|guidelines for contributing]].

For own developments and experiments in code you should **NOT** use merge/pull to integrate your changes in df8oe's active-devel. Instead 
 use git "rebase" command, as documented on our contribution page. 
We had very little trouble to follow that approach for the last two years. It also has its issues but in general, once you understand how to operate it, it works quite well. The main benefit of the rebase approach is that it keeps all your "local" changes together on top of the last official release you rebased on. Opposed to the merge approach you have been running, which does mingle your changes with the external changes in the time history.

==== Further reading ====
https://www.atlassian.com/git/tutorials/setting-up-a-repository/git-clone
http://www.ralfebert.de/git/