We don't want to polute the repository with a
.gitignore file... so you must add common OS files to your Global .gitignore. If you don't already have a global .gitignore then follow the instructions below (from: http://help.github.com/ignore-files/) or skip to the next section.
cd ~ touch .gitignore_global mate .gitignore_global
In Textmate add the following to the file and save
.DS_Store? ehthumbs.db Icon? Thumbs.db
git config --global core.excludesfile ~/.gitignore_global
Organise your local downloads and uploads
Downloads folder create a
_download.viewsource.me folder and a subfolder for the project you're archiving (must be a unique, lowercase alpha-numeric name without spaces. It may include "." or "_" or "-" characters). Then a subfolder for each version you are downloading (full version number i.e. 1.5.0/ ... NOT 1.5/).
cd ~/Downloads/ mkdir _download.viewsource.me cd _download.viewsource.me/ mkdir jquery cd jquery/ mkdir 1.5.0 mkdir 1.5.1 etc...
Download the public release source code files into it's version folder.
Downloads folder create an
_upload.viewsource.me folder and a subfolder for the project you're archiving. Then a subfolder for
mkdir _upload.viewsource.me cd _upload.viewsource.me/ mkdir jquery cd jquery mkdir cdn mkdir packages
In Finder copy and paste over all the version folder from
_download.viewsource.me/jquery/ and paste them into the
cdn and then the
Also add a
latestsubfolder under the
cdnfolder to hold a duplicate copy of the latest release. Later on the
packagesfolder will contain a duplicate copy of the latest zip'ed packages renamed to
cdn folder and then the first version subfolder e.g. 1.5.0. Remove any version prefix/suffixed string from the filenames e.g.:
jquery.1.5.js --> jquery.js jquery.1.5.min.js --> jquery.min.js
Continue to do this renaming process for each version.
If adding a project that contains large "optional" binary files (e.g. from inside a packaged example) then consider removing these files / examples. BUT remember to keep them in the
packages.zip and .tar.gz files... as these should accurately reflect the projects release packages unmodified.
packages folder and rename each version folder so it is prefixed with the projects name, e.g.:
1.5.0/ --> jquery-1.5.0/ 1.5.1/ --> jquery-1.5.1/
Now you need to create clean .zip and .tar.gz files of each of those folders (i.e. on Mac OS you must Exclude
.DS_Store files and Discard Resource Forks)... Luckily there is an awesome little Mac OSX app named CleanArchiver. It's a free, simple and nifty archiving utility.
Personally I'm using v3.0a6(39) and have dragged this app into the Finder Toolbar for quick access.
Click on the app in the Finder Toolbar and setup and save the apps defaults to:
Archive Type: gzip
Compression Level: Best
Encoding: [empty] <-- input is disabled for gzip
Discard Resource Forks: yes
Exclude .DS_Store: yes
Archive Individually: yes
You can then drag and drop multiple folders into the app icon in the Finder Toolbar and it will generate all the individual .tar.gz files for each folder e.g.
Then simply open the app and change:
Archive Type: zip
Again drag and drop and you now have all your .zip files e.g.
Note: Please test unzipping a few of these archives to make sure they are clean. If you can, also test unzipping on a PC running Windows - this will show up any Mac OSX junk.
Setup project "master" + first commit
Now setup your project folder
mkdir viewsource.me.test cd viewsource.me.test git init
In Finder drop in the 1st version files from the
cdn folder (make sure you remembered to rename version prefixed/suffixed files! e.g.
jquery-1.5.0.js --> jquery.js.
Then make your first commit (always commit deleted files with the -a option)
Message should be "[tag]" (and in some rare occasions "[tag]. Commit note" e.g. "v1.1.3. Includes the v18.104.22.168 patch."). The [tag] will always contain the full version number prefixed with a "v" e.g. v1.5.0, NOT v1.5 or 1.5.0
git status git add . git commit -am "v1.5.0"
Github switch to "viewsource" context
New Repository: https://github.com/repositories/new
Description: jQuery - version releases archived, tagged, hosted & packaged for download!
Homepage URL: none
Follow the instructions for: "Existing Git Repo?"
git remote add origin firstname.lastname@example.org:viewsource/viewsource.me.test.git git push -u origin master
Refresh Github to see your first commit (and don't worry about the missing README warning).
Commit all archive versions to "master"
Now in Finder delete the project files and drop in the next versions files (or if you're sure the files being dropped in have the same name's as all the existing files then just drop in and chose to replace the existing files).
Should show that the files have only been modified between the previous version and the newer version.
git add . git commit -am "v1.5.1"
Continue through all the archive versions being added for the project.
You may consider using Github.app on Mac OSX for managing these basic commits. Simply drag and drop the "viewsource.me.test" folder into the "Drop a folder to add to GitHub for Mac" to add the repository.
Tag each commit
Print out the commits history + tags
git log --pretty=oneline --decorate
Then start adding lightweight tags (no -a, -m or -s options!). Then list the tags added.
git tag v1.5.0 19fd2918c0a5a26d6052863bce2686e460267771 git tag
Push all the tags
git push --tags
If you need to delete a tag...
git -d v1.5.2 git push origin :v1.5.2
Auto generate Github Pages "gh-pages" branch + project page
Auto generate a GitHub Pages branch, with some default content.
- Go to the projects Admin page on GitHub
- Check the "GitHub Pages" checkbox
- A popup will ask you to "Activate GitHub Pages" - click the big "Automatic GitHub Page Generator" button
Project Name and
Short Project Description.
Page Color to
Click "Create Page".
Paste the Github Pages URL into the "click here to add a homepage" section e.g. http://viewsource.github.com/viewsource.me.test
Check that your GitHub Pages page has been built and is available at that url.
Checkout 'gh-pages' and commit '.nojekyll' and a '404.html'
Checkout the 'gh-pages' branch, change into that branch and commit a
.nojekyll file to avoid Github Pages from parsing content through Jekyll when the page is built. Also copy the index.html file to be used as a 404.html page. Note: it can take a while for the 404.html to work for 404 pages.
git fetch origin git checkout origin/gh-pages -b gh-pages git branch ls -la touch .nojekyll git add .nojekyll git commit -m ".nojekyll added." cp index.html 404.html git add 404.html git commit -m "404.html added." git push -u origin gh-pages
Add your first version submodule to Github Pages
Add a submodule for the first tagged version... make sure you add the Git Read-Only clone url from Github.
git checkout gh-pages git submodule add git://github.com/viewsource/viewsource.me.test.git 1.5.0
If you are asked to enter the
Password: for you computers admin user... then chances are you are trying to add the PRIVATE SSH or HTTP address. Enter an incorrect password and check you're using the Git Read-Only address.
Now go into the submodule directory, checkout the version tag into a new branch, commit and push the modified "gh-pages" branch.
cd 1.5.0 git checkout -b b1.5.0 v1.5.0 Switched to a new branch 'b1.5.0' cd .. git add . git commit -m "v1.5.0" git push origin gh-pages
Check you email inbox and hopefully you got a "[viewsource.me.test] Page build successful" email... if you got a "[viewsource.me.test] Page build failure" email then check what it says went wrong. Chance are it says "submodule fetch failed". If this is the case then reset back to your previous commit, remove submodule 1.5.0/ subfolder, and push this up to Github.
git log git reset --hard 23asadd3Afd2324erte234243 rm -rf 1.5.0/ git status git push --force origin gh-pages
If you got a success email then check the submodules files were auto pulled during the page build by visiting the hosted url of one of the pages files e.g.
When confirmed repeat the process of adding submodules for each tag.
Managing a "latest" submodule
If you don't already have a "latest" submodule (pointing to the most current version tag) then now's the time to set one up ...
git submodule add git://github.com/viewsource/viewsource.me.test.git latest cd latest git checkout -b b1.6.0 v1.6.0 Switched to a new branch 'b1.6.0' cd .. git add . git commit -m "latest v1.6.0" git push origin gh-pages
If you are coming back and adding a new version to the repo then you will first need to initialise the submodule and update it (because the "lastest" folder is empty due to the next step re: Clean "master" on local)...
git submodule init latest git submodule update latest cd latest/ git checkout -b b1.6.1 v1.6.1 cd .. git add . git commit -m "latest v1.6.1" git push origin gh-pages
Cleanup "master" on local
You will need to clean up your "master" branch from having "1.5.0/" - and other submodule folders - as an untracked directories... (see: Issues with Submodules ).
git checkout master git status
In Finder simply delete all of these submodule folders while in the
master branch... or if you want to stay in console:
rm -rf 1.5.0/ rm -rf 1.5.1/ ... etc
Go to your Github repository "downloads" page e.g. https://github.com/viewsource/viewsource.me.jquery/downloads
You will see all the tagged commits available for download. But that's just not good enough! ^_^. We have modified the filenames (and on some cases removed large binary files) from the versions kept in the repo. So to be nice lets upload the unmodified .zip and .tar.gz
packages we prepared earlier.
In Github click the
Upload a new file button. This will launch the
Select file(s) to upload prompt.
Important: The order that you upload files will determine their sort order on the downloads page. Always upload OLDER versions FIRST; and .TAR.GZ files before .ZIP files.
Select the first 3 sets of version packages just to test the water... click
open and then review the order of files listed waiting to be uploaded. This is the correct order:
jquery-1.0.0.tar.gz jquery-1.0.0.zip jquery-1.0.1.tar.gz jquery-1.0.1.zip jquery-1.0.2.tar.gz jquery-1.0.2.zip ... etc
Start Upload ON THE FIRST FILE; THEN WAIT!!! You need to wait until the file is fully uploaded and completed before you start the next upload... you want to see this in green:
Otherwise you may get the 2nd package listed in the Downloads - but when you try and download the file you get an XML error! (FAIL!).
Short description - 99% of the time just leave this blank. But in some cases you may want to include a comment (especially if there was a comment on [tag]) e.g. "v1.1.3. Includes the v22.214.171.124 patch."
TIP: Test each download, only upload in small batches, and have a coffee near by for those waiting periods!
TIP2: If you mess up the order click
Manage Downloads and delete the packages until you get things right.
Managing a "latest" download package
If you don't already have a
jquery-latest.tar.gz then now's the time to upload them! If you're on v1.6.0 then these files are just duplicates of
These uploads should have Short Description identifying the "latest" version
When you need to upgrade to the next version release (e.g. 1.6.1) you need to first delete the
jquery-latest.tar.gz downloads from Github. Click on the "Manage Downloads" button then delete the files (if you don't you will get an error informing you that the filename is already taken when you try and do an upload of your latest zip's).
Now upload the new
jquery-latest.tar.gz which are renamed copies of
These uploads should have Short Description identifying the "latest" version
Cloning the project
Clone the project, pull down the gh-pages branch, and update a specific submodule (1.5.1) to pull in it's files from the repo.
git clone git://github.com/viewsource/viewsource.me.test.git cd viewsource.me.test git fetch origin gh-pages git checkout gh-pages git submodule init git submodule update 1.5.1 cd 1.5.1
To update all submodules run
git submodule update (without any submodule identifier).
Forking the project for personal Github Pages hosting
Fork the project on github, clone using your SSH address, pull down the gh-pages branch, make a commit into the gh-pages branch to trigger Github to build your Github Pages page.
git clone email@example.com:chrisjacob/viewsource.me.test.git cd viewsource.me.test git fetch origin gh-pages git checkout gh-pages echo "My personal Github Pages fork of the project" > README.md git add . git commit -m "README.md added to trigger Github Pages build." git push origin gh-pages
Then visit your personal Github Pages hosted copy e.g. http://chrisjacob.github.com/viewsource.me.test/
If you made a mistake you can delete a branch using the following:
git checkout master git branch -D gh-pages git branch git push origin :gh-pages
Forceful reset, removing submodule folder and pushing to github (WARNING: Find a better way to do this if others have already accessed the public repo and cloned their own copies).
git reset --hard f2e2407571146b0f1d537d19fe209801f99cf36f rm -rf 1.5.0/ git push --force origin gh-pages
A handy little snippet to list all local branches with their upstream plus behind/ahead numbers:
git branch -vv