Sandbox:Piffpoof8

=FreeCAD Examples Repo on Github=

Introduction
The FreeCAD system is programmed, tested and documented by numerous people spread around the world. The Git protocol is used to coordinate all the working and archive source code, the test data, as well as the changes and version history. FreeCAD uses a separate website for discussion forums and a documentation Wiki. The Git system is a distributed revision control system and is free software under the GNU General Public License, it's documentation is available at Git-Documentation) The Git protocol allows persons involved with the FreeCAD project to work independently and coordinate documents (e.g. code, data) with each other as needed. New versions of FreeCAD are generated using Git and bugs are identified and rectified using Git. The Git protocol provides the following services for the FreeCAD project:


 * distributed revision control
 * source code management
 * a command-line tool
 * web-based graphical interface via the desktop
 * access control

As Git is a protocol for communication and exchange of data, any software that implements the protocol can participate. Different FreeCAD users work with different Git tools, some of which are:


 * Gitorious
 * GitLab
 * BitBucket
 * sourceforge
 * GitHub

FreeCAD uses Git in two main areas:


 * source code management and system build
 * storage and revision control of data files

Building the FreeCAD system is covered in a separate document Source_code_management, the remainder of this document covers Git for non-developers.

Setting up Git
Note: This page will only document the command line mode interface as the various GUI based apps for Git come with their own documentation and are specific to the platform.

Installing the Git Software
Expand the topic box below that matches your computing platform:

Macintosh Installation

 * 1) go to Source Forge and download the .DMG file
 * 2) Create a folder that will hold the Git install image and later the Git repositories.
 * 3) Double-click the DMG file (which will be in the Downloads folder), Once it is mounted open it in a Finder window and copy the contents to the folder you created.
 * 4) Double-click the package (ends in .PKG) to install Git. This will install git to /usr/local/git. Root access is required so it will ask for an administrator account and password.

Git should now be installed and operational. You can now start using it as described in the next section. If you want to check it simply type   in the Terminal application and the system will list the Git summary of commands.

Using Git With Files
The greater number of users will be simply getting files from the Git repository, the lesser number will be creating, modifying and updating files. The first subsection covers what will be the most frequent operation, which is getting a file (or files) from a Git repository. The subsequent subsections cover creating, modifying and updating files on the Git repository.

Create a New Git Repository
There are multiple different Git hosts and each has there own software and/or webpages, the exact steps will be specific to that system. Below are some examples:

GitHub Repository Creation

 * 1) click on the plus sign ("+") on any page
 * 2) give your repository a name
 * 3) a description always helps
 * 4) set your repository as public/private Note: if you are on the free (i.e. pay no money plan) then you can only create a Public repository
 * 5) do not check the box or select the 2 menus to create any of the optional items (e.g. README, license, .gitignore) as they may conflict later cause a conflict
 * 6) click Create Repository
 * 7) leave this webpage open as it will be needed in the next step

Upload Your Files to Your Newly Created Repository (Pushing) as outlined here

 * 1) open up the Terminal application
 * 2) change your working directory to the folder holding your file:
 * 3) intialise the directory as a local Git repository:
 * 4) add the files in your new (on disk)  repository  notice that there is a space and a period fallowing the command
 * 5) now commit them to the GitHub repository with a descriptive comment:  your files are now copied to the GitHub repository and put under version control.
 * 6) return to the webpage from the previous step, click on the icon to copy the URL of your repository on the GitHub server, the URL will be of the form:  you can also copy this URL by normal means
 * 7) in the Terminal application enter:  which will designate the central version of the repository on the GitHub server as the master copy (i.e. the origin)
 * 8) still in the Terminal enter:  this will copy the changes from your local on-disk repository to the central master copy located on the GitHub server. You will be asked for your GitHub User ID and password.

Your new repository is now fully created on the GitHub server.

Adding Files to the Repository (Pushing)

 * 1) move or copy the new files that you wish to add to the Git repository directory on your local disk: (~/Desktop/myFirstRepository in the example above)
 * 2) in the Terminal application set your working directory the local repository:
 * 3) enter:  this will add the 2 files to your local Git repository
 * 4) as with the previous example, now commit them to the GitHub repository with a descriptive comment  your files are now copied to the GitHub repository and put under version control.
 * 5) and finally copy the files from your local repository to the central one:

Your 2 new files are now both in your local repository as well as propagated to the central repository on GitHub

Making Changes to Files in the Repository (Forking)
Forking is a process used when working with other persons. If you do not have write access to their repository and wish to change something, you create a 'fork' for that change.


 * 1) locate the page of the repository which you wish to alter on the Git server
 * 2) click the Fork button on that page which creates a copy of their Git repository which you will be able to make changes to
 * 3) "clone" the copy to your computer
 * 4) make your changes
 * 5) commit those changes
 * 6) push the changes to your own copy on the Git server
 * 7) later the owner of the code can decide to merge your changes or not

Once your edits are done then go to the page of the copied repository (i.e. on the central server) where you will have the option of creating a "pull" request. If you create the pull request then Git will notify the owner. The owner can click "Merge pull request" to "pull" these changes into his repository. That would integrtae your edits back into the main stream of the code.

Pull Requests
Pull requests let you tell others about changes you've pushed to a repository on GitHub. Once a pull request is sent, interested parties can review the set of changes, discuss potential modifications, and even push follow-up commits if necessary.

Miscellaneous Commands

 * git help - produces help for the git facility
 * git status - shows the status of your repository (are there commits pending?)
 * git branch - shows the status of files in the central repository versus your local working directory
 * git pull - fetches the files from the remote repository and merges it with your local copy

Sandbox:Piffpoof1