Difference between revisions of "TheMagPiGit"

From eLinux.org
Jump to: navigation, search
(RaspberryPi & github)
(19 intermediate revisions by 3 users not shown)
Line 1: Line 1:
{{TheMagPiHeader}}
+
{{TheMagPiTeamHeader}}
  
* [[RPi_MagPi_InfoForAuthors|Information for authors]] - the process of submitting an article.
 
* [[TheMagPiLayout|Layout & fonts]] - description of the standard layout and associated fonts.
 
* [[TheMagPiPdf|PDF creation]] - instructions for the generation of PDF for electronic and paper publication.
 
  
  
== Raspberry Pi & github ==
+
== Setting up access ==
  
=== Setting up access ===
+
* The first step is to create a [https://github.com/ github] account.  Then for those on the MagPi layout team, email the editor for permission to join the github organisation.
  
  * The first step is to create a [https://github.com/ github] accountThen for those on the MagPi layout team, email the editor for permission to join the github organisation.
+
* Since the Raspberry Pi does not have a great deal of processor power, it is better to use the command line tools to access github.  For OSX and Windows there are GUI tools available for download on the github site.
  
  * Since the Raspberry Pi does not have a great deal of processor power, it is better to use the command line tools to access github. 
 
  
  * Once you have a github account, on your Raspberry Pi type:
+
== Tools for LINUX or OSX ==
 +
 
 +
Several people would rather not read the [http://git-scm.com/book/en/ git book].  Therefore, some scripts were written to simplify the usage slightly.  Git is not a replacement for good communication.  Remember to update the local git repository before starting work on something and commit changes back to the repository frequently.
 +
 
 +
* Download [https://www.dropbox.com/s/xnra5lnw61wrm8r/mp-git-20130321.tar.gz mp-git-20130321.tar.gz] from the DropBox.
 +
* Unpack it,
 
<pre>
 
<pre>
git config --global user.name "John Doe"
+
tar xvfz mp-git-20130321.tar.gz
git config --global user.email J.Doe@machine.org
+
 
</pre>
 
</pre>
where the user name and email address should be replaced with your user name and email addressThis is a one time configuration step.  These settings are then stored in your ~/.gitconfig file.
+
* Install it,
 +
<pre>
 +
cd mp-git
 +
source install.sh
 +
</pre>
 +
* Then use the commands as neededThe commands are,
  
  * The easiest way to use the command line tools is via an ssh key pair. Type,
+
==== mp-git-setup.sh ====
 +
 
 +
Type
 
<pre>
 
<pre>
ssh-keygen
+
mp-git-setup.sh
 
</pre>
 
</pre>
to create an ssh key pair and choose a secure password (upper and lower case letters, symbols and numbers without dictionary words)This is a one time configuration step, unless the password needs to be updated in the future.
+
to install and configure gitThe script has no action if the installation and configuration is already okay.
  
  * Then go to your github account.  Select account preferences.  Then select "SSH Keys" from the left-hand menu.  Click on "Add SSH key" and add your public key (~/.ssh/id_rsa.pub).  This is a one time configuration step, unless the public key needs to be updated (for a password change) or another public key needs to be added.
+
==== mp-git-clone.sh ====
  
=== Using github ===
+
The script expects that the repositories will be in a parent directory called magpi-git.  (This can be overridden by setting the environmental variable MP_GIT_DIR to the full path of the parent directory.)  If the magpi-git directory does not already exist,
 +
<pre>
 +
mkdir magpi-git; cd magpi-git
 +
</pre>
 +
Then type
 +
<pre>
 +
mp-git-clone.sh 11
 +
</pre>
 +
to clone the issue 11 repository.  The script will not clone the repository again if a local copy already exists in the present working directory.  More than one repository can be requested at once.  For example,
 +
<pre>
 +
mp-git-clone.sh 11 12 13 templates
 +
</pre>
 +
will check out the issue 11, 12 and 13 repositories, as well as the templates repository.
  
  * At the start of an editing session (when you log into the Raspberry Pi), type:
+
==== mp-git-commit.sh ====
 +
 
 +
Type
 
<pre>
 
<pre>
ssh-agent
+
mp-git-commit.sh 'A message goes here' [all]
ssh-add
+
</pre>
 +
where the string 'A message goes here' should be replaced with a sensible and informative message and the text 'all' is optional.  If all is used, all repositories within the mp-git/ parent directory are checked.
 +
The script adds any new few files, commits to the local repository, fetches and remote changes and then merges the local changes into the remote repository.  (Git does not allow empty directories to be added)
 +
 
 +
==== mp-git-update.sh ====
 +
 
 +
Type
 
<pre>
 
<pre>
then enter your password for the ssh keyThis step needs to be rebooted each time you log into the Raspberry Pi.
+
mp-git-update.sh [all]
 +
</pre>
 +
to update the local copy with any changes from the github repository, where 'all' is optionalIf all is used, all repositories within the mp-git/ parent directory are checked.
  
  * Then use the ssh read and write link from the github repository, e.g.:
+
==== Using Proxy ====
 +
If you need to use a proxy:
 +
HTTP_PROXY="http://username:pwd@theproxyserver.com:port/"
 +
git config --global http.proxy $HTTP_PROXY
  
git clone git@github.com:someorg/reponame.git  
+
== Tagging ==
 +
 
 +
While git tagging is not currently scripted, the git commands can be used to tag and push the tag back to the repository. There purpose of tagging is to keep track of a version of many files at one point in time.  A good application would be to tag the repository once at the time of electronic publication and then once when printing.  Then one could refer to the printed version just by a tag, rather than risk some additional changes to the repository being included.
 +
 
 +
The list of tags can be viewed by typing
 +
<pre>
 +
git tag
 +
</pre>
 +
from within a mp-git/*/ directory.
 +
 
 +
A new tag can be added by
 +
<pre>
 +
git tag -a magpi-templates-00-00-01 -m 'Tagging before overwriting current templates with templates which contain document bleeds'
 +
</pre>
 +
and all tags can be pushed back to the repository
 +
<pre>
 +
git push --tags
 +
</pre>
  
this will create a folder called reponame.  The clone operation clones the repository to the local disk.
+
Tags are not pushed to the remote repository when mp-git-commit.sh is run, since the --tags flag is not included in the git push command inside that script.

Revision as of 09:29, 9 May 2013

TheMagPi.png

Main Readers Authors Volunteers Sponsors Advertising Translations


  • Quick start guide - A quick start guide to help new volunteers get the information they need.
  • Information for volunteers - A guide to help volunteers familiarize themselves with the team’s workflow / tools.
  • Information for authors - the process of submitting an article.
  • MagPi MMS - how to use the MagPi MMS.
  • MagPi GIT - how to use the MagPi GIT scripts.
  • Layout & fonts - description of the standard layout and associated fonts.
  • PDF creation - instructions for the generation of PDF for electronic and paper publication.


Setting up access

  • The first step is to create a github account. Then for those on the MagPi layout team, email the editor for permission to join the github organisation.
  • Since the Raspberry Pi does not have a great deal of processor power, it is better to use the command line tools to access github. For OSX and Windows there are GUI tools available for download on the github site.


Tools for LINUX or OSX

Several people would rather not read the git book. Therefore, some scripts were written to simplify the usage slightly. Git is not a replacement for good communication. Remember to update the local git repository before starting work on something and commit changes back to the repository frequently.

tar xvfz mp-git-20130321.tar.gz
  • Install it,
cd mp-git
source install.sh
  • Then use the commands as needed. The commands are,

mp-git-setup.sh

Type

mp-git-setup.sh 

to install and configure git. The script has no action if the installation and configuration is already okay.

mp-git-clone.sh

The script expects that the repositories will be in a parent directory called magpi-git. (This can be overridden by setting the environmental variable MP_GIT_DIR to the full path of the parent directory.) If the magpi-git directory does not already exist,

mkdir magpi-git; cd magpi-git

Then type

mp-git-clone.sh 11

to clone the issue 11 repository. The script will not clone the repository again if a local copy already exists in the present working directory. More than one repository can be requested at once. For example,

mp-git-clone.sh 11 12 13 templates

will check out the issue 11, 12 and 13 repositories, as well as the templates repository.

mp-git-commit.sh

Type

mp-git-commit.sh 'A message goes here' [all]

where the string 'A message goes here' should be replaced with a sensible and informative message and the text 'all' is optional. If all is used, all repositories within the mp-git/ parent directory are checked. The script adds any new few files, commits to the local repository, fetches and remote changes and then merges the local changes into the remote repository. (Git does not allow empty directories to be added)

mp-git-update.sh

Type

mp-git-update.sh [all]

to update the local copy with any changes from the github repository, where 'all' is optional. If all is used, all repositories within the mp-git/ parent directory are checked.

Using Proxy

If you need to use a proxy:

HTTP_PROXY="http://username:pwd@theproxyserver.com:port/"
git config --global http.proxy $HTTP_PROXY

Tagging

While git tagging is not currently scripted, the git commands can be used to tag and push the tag back to the repository. There purpose of tagging is to keep track of a version of many files at one point in time. A good application would be to tag the repository once at the time of electronic publication and then once when printing. Then one could refer to the printed version just by a tag, rather than risk some additional changes to the repository being included.

The list of tags can be viewed by typing

git tag

from within a mp-git/*/ directory.

A new tag can be added by

git tag -a magpi-templates-00-00-01 -m 'Tagging before overwriting current templates with templates which contain document bleeds'

and all tags can be pushed back to the repository

git push --tags

Tags are not pushed to the remote repository when mp-git-commit.sh is run, since the --tags flag is not included in the git push command inside that script.