If you haven't already, be sure to get set up with Git.
Although all of these are optional, these steps will improve your workflow and make learning git much more manageable.
Also checkout http://gitref.org/ for more examples and explanations.
Colors can let you know whether you're in a git working copy, and which branch your working on. Simply paste the following code into ~/.bash_profile using a text editor like nano.
parse_git_branch() {
git branch 2> /dev/null | sed -e '/^[^*]/d' -e 's/* \(.*\)/(git::\1)/'
}
if [ $TERM = 'dumb' ] ; then
# No color, no unicode.
export PS1="\w \$(parse_git_branch) > "
else
export PS1="\[\033[01;34m\]\w \[\033[32m\]\$(parse_git_branch)\[\033[00m\] ▶ "
fi
and whenever you're in a git working copy, your command prompt should look like this:
Colors can also show which lines have been added, deleted, ignored, and more by adding this code to ~/.gitconfig :
[color] branch = auto diff = auto status = auto [color "branch"] current = yellow reverse local = yellow remote = green [color "diff"] meta = yellow bold frag = magenta bold old = red bold new = green bold [color "status"] added = yellow changed = green untracked = cyan
Setting up a default text editor is helpful, especially when making commit comments that can't be capture with the -m option. To do so, simply copy the following code into ~/.bash_profile.
export EDITOR=nano
In this example, I'm setting my default text editor to nano, but most text editors will work.
In the event git can't resolve merge conflicts, it's a good idea to have a default merge tool like DiffMerge on hand. For Mac OS X, be sure to download the installer, and not the DMG.
To set this as your default, run
nano ~/.gitconfig
and past in the following code:
[mergetool "diffmerge"]
cmd = diffmerge --merge --result=$MERGED $LOCAL $BASE $REMOTE
trustExitCode = false
then run:
git config --global merge.tool diffmerge
and you should be good to go!
To create a (new, public) repository, go to you're github dashboard (simply github.com, once you're logged in to your account) and click on the "New Repository" button
Next, you'll need to run git init in Terminal in the directory you want to be add to your repo. In this case, this will be the relevant TileMill project folder in /Users/[you]/Documents/project This __init__ializes your git repo, creating a .git file in your current directory where all of your changes will be tracked.
Now run git add your-files.ext for any files or directories you want tracked by git. If you run git status, now you should see a list of the files you just added. Running git status is a good way to make sure only the files you have staged will be committed. If you added have added color highlighting to your .gitconfig file, the should be yellow:
You're ready for your first commit. Running git commit, should open your default text editor as a way of prompting you for a comment to describe the commit you are making. By convention, the first line of your first commit is appropriately "First Commit" followed by a description of the changes you are making (in this case you are adding files to your repo). After you've outlined your changes, save and close the editor, and your commit will be complete.
For subsequent commits, you can use the -m flag to make shorter comments:
git commit -m "a shorter comment"
Although you've committed your changes, they still only exist on your local branch of the repo that lives on your computer. This local repo can contain a list of any remote versions of the repo. To add a remote location to this list (i.e. one that others can access), run git remote add origin git@github.com:your-username/your-repo.git. You can copy the url from the set up page you saw after creating the repo at GitHub:
Now you can run git push -u origin master. Note that on your first push, you need to include the -u, ????adding an upstream reference so that all subsequent pulls will reference this remote version????
Now that git is tracking your TileMill project, making frequent commits will make it easier to track the evolution of the project. In order to track smaller changes, git allows you to selectively add "hunks" of altered code while ignoring others, using the -p flag:
In this case, the minus sign and red color indicate that I've deleted the comment /light blue/ and a green plus sign indication I've added a line of white space. If I wanted to add this, I could type "y" at the prompt. Since white space is pointless and I like that comment, I can also type "n" to decline adding this hunk. Doing this returns a the same prompt for the next hunk of code. Here, I've added a comment labeling the map's background, which I would like to add:
Entering yes adds the file as there are no more 'hunks', and you can commit your change s.
Git requires you to use git mv and git rm to make changes in the repo's filesystem. Using the standard unix counterparts mv and rm will preserve changes in your local working tree, but not in the git repo. For example, if you were to accidentally delete a file using rm, you could simply run git checkout your-deleted-file in the appropriate directory, and the file will be reinstated. Without running git checkout, subsequent pulls will not reinstate the file to your local working branch.
Unless your data is saved directly to the project/layers/ directory, this folder only contains symbolic links to the location of the data. Adding the project/layers/ and symlinks that live there to a git repo will fail to add the data, making it inaccessible to any collaborators attempting to work on the same TileMill project. To remove these symlinks run the following two commands
mv layers layers.orig/
rsync -aLv layers.orig/ layers/
This will create a new directory called layers.orig, containing the original smlinks, and a new folder called layers/ containing copies of the original files. You can now add the entire project to your git repo, allowing collaborators access to your data layers.
Git allows you create new branches that will still track your changes but not push them to the master branch. This allows you to experiment without jeopardizing the main (and hopefully stable) branch of the project. For example, if you are making serious alterations to an already functional data layer in a project that was already being used to render polished maps and didn't want to corrupt the original data files, branching your project would allow you to play with the data without worrying about whether your pushes would affect the files being used in the master branch.
To create a branch, run git branch you-branch-name. To simultaneously create and switch to a branch git branch -b you-branch-name (without invoking the -b option, you will create the new branch, but still be working in the original branch). To switch between branches run git checkout your-branch-name. Remember that any pushes you make will now require you to run git push origin your-branch-name. Once your now-isolated changes are complete, you will probably want to merge your branch back to the master. To do so run git merge your-branch-name.
If git can't resolve and conflicts, it's a perfect opportunity to try out DiffMerge or whatever mergetool you're using. You should see an error like this:
to resolve, run git mergetool or if you have not set up a default merge tool
git mergetool -t your-merge-tool. You should now see this prompt:
Enter yes, pick which changes you want from each file (in diffmerge, the version in your local working copy will be on the left and the conflicting version will be on the right), and save your changes. Once complete, push your changes and run git merge again. No error should appear. You will notice however that in your present working directory you will have a new file for every file in which you resolved a merge conflict. The file as it existed before the merge will now be labeled your-file.orig and the new file (inclusive of the merge resolution) will maintain the same naming convention.
The .gitignore file that lives in your home directory is a useful way of ensuring that git will not track certain file types. If you were editing a large GeoTiff creating changes that would result in unnecessarily large pulls for your collaborators, you could simple edit .gitignore by running nano ~/.gitignore and adding .tif to the file contents. This would ensure that all files with the .tif extension would not be tracked by git.
If you want or need to remember important commits, you can use git tag. As you will probably want to include a message relating the significance of your tag, run git tag -a your-tag-message. Tags are useful in that they allow you to reference important moments in your project's development. Using git diff your-tag-mesasge will display all changes to your current working tree since you made that tag:
