From FreeCAD Documentation
Jump to navigation Jump to search
Sandbox Page for "Piffpoof"

Using Git and the GitHub Repository


The FreeCAD system is programmed, tested and documented by numerous people spread around the world. A commercial hosting service called GitHub is used to contain all the working and archive source code and test data for the project. Additionally it holds all the changes and version history for the source code and data. A separate website is used for discussion forums and a documentation Wiki. GitHub is based on the Git system which is a distributed revision control system and is free software under the GNU General Public License. (Git documentation, which GitHub uses, is available here) The GitHub allows persons involved with the FreeCAD project to work independently and coordinate documents (e.g. code, data) through GitHub as needed. New versions of FreeCAD are generated using GitHub and bugs are identified and rectified using GitHub. GitHub 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

FreeCAD uses GitHub in two main areas:

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

These 2 related but separate areas are covered in the two following sections.

Setting up Git and GitHub

Getting a GitHub Signon ID

The FreeCAD repositories are located on the GitHub servers and each GitHub user must have a User ID so the first thing is to get set up. Go to where you will supply the usual:

  • User Name
  • contact email account
  • password

Select the the plan that suits your needs, the Free account (0$ per month for 0 private repositories) is sufficient for working with the FreeCAD repositories.

You are now ready to set up access to GitHub.

Selecting the Git or GitHub Software

FreeCAD uses the GitHub servers, there are two options to interact with them:

This page will only document the command line mode interface as the GUI apps 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 git in the Terminal application and the system will list the Git summary of commands.

Ubuntu & Fedora Installation

This needs to be written

Windows Installation

This needs to be written

Using Git and GitHub With Files

The greater number of users will be simply getting files from the GitHub 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 the GitHub repository. The subsequent subsections cover creating, modifying and updating files on the GitHub repository.

Getting (Pulling) a File From the GitHub Repository

<to be filled in>

Note: For all the following processes you must go to the GitHub home page and sign in before you can use GitHub

Create a New Repository on GitHub as outlined here

  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:
    cd ~/Desktop/myFirstRepository
  3. intialise the directory as a local Git repository:
    git init
  4. add the files in your new (on disk) repository
    git add .
    notice that there is a space and a period fallowing the command
  5. now commit them to the GitHub repository with a descriptive comment:
    git commit -m 'First commit of my files to my repository'
    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:
    git remote add origin
    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:
    git push origin master
    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:
    cd ~/Desktop/myFirstRepository
  3. enter:
    git add yourNewFile1.jpg
    git add yourNewFile2.txt

    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
    git commit -m 'adding 2 new files to fill in the gaps'
    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:
    git push --set-upstream origin master

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)

Using Git and GitHub to Build FreeCAD

This needs to be written