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
Then run:
git config --global core.excludesfile ~/.gitignore_global
In your 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.
In your Downloads folder create an _upload.viewsource.me folder and a subfolder for the project you're archiving. Then a subfolder for cdn and packages.
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 packages folders.
Also add a
latestsubfolder under thecdnfolder to hold a duplicate copy of the latest release. Later on thepackagesfolder will contain a duplicate copy of the latest zip'ed packages renamed tojquery-latest.zipandjquery-latest.tar.gz.
Open the 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.
Open the 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. jquery-1.5.0.tar.gz.
Then simply open the app and change:
Archive Type: zip
Again drag and drop and you now have all your .zip files e.g. jquery-1.5.0.zip. WIN!
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.
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 v1.1.3.1 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
Name: viewsource.me.test
Description: jQuery - version releases archived, tagged, hosted & packaged for download!
Homepage URL: none
Anyone
Follow the instructions for: "Existing Git Repo?"
git remote add origin git@github.com: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).
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).
git status
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.
http://book.git-scm.com/3_reviewing_history_-_git_log.html
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 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
Remove the Authors and Contact data.
Keep the Project Name and Short Project Description.
Change the Page Color to #ffffff
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 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 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.
http://viewsource.github.com/viewsource.me.test/1.5.0/jquery.js
When confirmed repeat the process of adding submodules for each tag.
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
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
WARNING: CLICK 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:
Upload complete!
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 v1.1.3.1 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.
If you don't already have a jquery-latest.zip and 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 jquery-1.6.0.zip and jquery-1.6.0.tar.gz renamed.
These uploads should have Short Description identifying the "latest" version v1.6.0.
When you need to upgrade to the next version release (e.g. 1.6.1) you need to first delete the jquery-latest.zip and 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.zip and jquery-latest.tar.gz which are renamed copies of jquery-1.6.1.zip and jquery-1.6.1.tar.gz
These uploads should have Short Description identifying the "latest" version v1.6.1.
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).
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 git@github.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