Sandbox:Piffpoof4

= Linking Scripts and FreeCAD files to Wiki Pages=

Introduction
FreeCAD uses a Wiki system provide user documentation. The need exists in the documentation to provide both Python script files and FreeCAD documents (which are binary files). This page describes how those two types of documents can be linked from the WIki.

A Gist is a concept within the git systems of a short piece of code, say for an example. It is different from a git repository as the git repository most often has multiple files. To further confuse the difference, the Gist has a full version control history as does a proper git repository. Also it turns out that a gist can hold more than one file, further blurring the distinction between gist and git repository. The FreeCAD Wiki uses the gist concept to hold examples that are either Python script of FreeCAD document files (i.e. ,FCStd files).

Creating an Account for 'git'
A git account is required to hold the files which will be attached to the WIki pages, if you need to create a git account then Click Here

Creating a 'Gist'
It seems that a new 'Gist' can only be created using the webpages of github.com. Consequently we will create a file in the new Gist so it can be created.

Steps A-I are steps on the website, the following steps with numbers are on your computer using the git software

You now have a new gist with a single file in it. --- 1	go to a directory where you are going to work with the git code 2	git clone https://gist.github.com/userName/c841d68e15ac152d59c6.git - a directory names 'c841d68e15ac152d59c6' will appear and it will have the initial file you put into the git repository 3	cd c841d68e15ac152d59c6 4	cp /home/username/somebinaryfile.bin. or use the file browser to move a file in	or save a file in from FreeCAD 5	git add -A 6	git commit -m "commit message" 7	git push You have now added a binary file to your newly created gist which will now have 2 files

J	sign into github - you should be on the page https://github.com/ K	click on the "Gist" button at the top of the page - you should be on the page https://gist.github.com/ - your Gists should be listed L	click on the button "Your Gists" in the upper right corner - you should be on the page https://gist.github.com/userName - there should be a list of your gists

M	for the gist you just created, there is a button "<>" followed by a digit (2 in this example) and the word "files", click on the "<>" - you should be on the page https://gist.github.com/userName/c841d68e15ac152d59c6, where it lists two files: - the file you added initially to crate the gist - the binary file you added second

For a binary file: N1	for the binary file there will be a link "View Raw ->", right-click on this link and copy the link - jump to step O --- For a script file: N2	for the script file there will be a link "Raw" at the right end of the box surrounding the name of the script file, click on this link N3	the page will now be a listing of the script file, copy the URL from the ORL field at the top of the browser - jump to step O --- O	In your Wiki page, enter a line of the form: [XXX some description for the link] where XXX is the URL you copied in step N	It will be of the form: https://gist.github.com/userName/c841d68e15ac152d59c6/raw/xxxxxxxx/fileName.FCStd P	remove the 'xxxxxxxx' so you have a file specification of the form https://gist.github.com/userName/c841d68e15ac152d59c6/raw/fileName.FCStd Q	substitute this file specification for the XXX in the Wiki line of step O, so you end up with a line in your Wiki of the form: some description for the link R	this link is now directed from the Wiki page to the latest version of your binary file at the github - You now have a Wiki page where both the links can be right-clicked and the Save File As option selected. The user can then direct the downloading of either a Python script file or a Python binary file (*.FCStd).

Trial Files and Terminal Log
Python script file

FreeCAD FCStd file

Python script file

FreeCAD FCStd file

new day, new gist

python with extension --- a binary

a python script

forum thread starts here

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.