One of the most frequent questions I answer about Git is why dealing with line endings is so difficult. This is an attempt to answer that question and explain the myriad of options and settings that control line endings in Git.

Git has gone through two systems for dealing with line endings in repositories. The root of the problem being that Unix, Linux and OS X use LF and Windows uses CRLF to denote the end of a line. Previous to OS X, Mac actually used CR, but for the most part we can ignore that.

None of this would be a problem if we each lived in our own little worlds and never shared code between operating systems. And by share I mean everything from working on a cross platform project to copy-pasting code out of a browser. In fact, anytime you download a sample project in a zip file, copy code out of a gist, copy code from someones blog or use code out of a file that you keep in Dropbox – you are sharing text and you need to deal with these invisible line-ending characters. All of these activities potentially introduce a different set of line endings into your code base which is going to make diffs messy and Git generally unhappy.

Git’s primary solution to all this is to specify that LF is the best way to store line endings for text files in a Git repository’s object database. It doesn’t force this on you but most developers using Git and GitHub have adopted this as a convention and even our own help recommends setting up your config to do this.

Background

Before describing the settings that control line endings in Git, there are a couple of things you need to know about: core.eol and what it means to write something to the object database.

End of line

core.eol

The first setting you need to know about is core.eol. In all but the rarest of cases you should never have to change this setting from it’s default. This setting doesn’t do much on its own, but as soon as we start telling Git to change our line endings for us we need to know the value of core.eol. This setting is used by all the other things we are going to talk about below, so it’s good to know that it exists and good to know that you probably don’t want to change it.

• core.eol = native – The default. When Git needs to change line endings to write a file in your working directory it will change them to whatever is the default line ending on your platform. For Windows this will be CRLF, for Unix/Linux/OS X this will be LF.

• core.eol = crlf – When Git needs to change line endings to write a file in your working directory it will always use CRLF to denote end of line.

• core.eol = lf – When Git needs to change line endings to write a file in your working directory it will always use LF to denote end of line.

You can run git config --global core.eol to see what this value is set to on your system. If nothing comes back that means you are on the using the default which is native.

In and out of the object database

What is the object database? I’m going to talk a lot about two different operations: writing to the object database and writing out to the working directory. It helps to understand these concepts a bit before moving on.

You may already know that Git has it’s own database in that .git folder which Scott does a great job of explaining in Chapter 9 of his Pro Git book. All you need to know is that when you do something like git commit you are writing objects into the database. This involves taking the files that you are committing, calculating their shas and writing them into the object database as blobs. This is what I mean when I say writing to the object database and this is when Git has a chance to run filters and do things like converting line endings.

The other place that Git has a chance to run filters is when it reads out of the object database and writes files into your working directory. This is what I mean when I say writing out into the working directory. Many commands in Git do this, but git checkout is the most obvious and easy to understand. This also happens when you do a git clone or run a command like git reset that changes your working directory.

The Old System

First, let’s talk about the old system. This is the original set of features in Git designed to solve this particular problem of line endings. There is a good chance you are still using this system and don’t even know. Here is how it works: Git has a configuration setting called core.autocrlf which is specifically designed to make sure that when a text file is written to the repository’s object database that all line endings in that text file are normalized to LF. Here are the different options for core.autocrlf and what they mean:

• core.autocrlf = false – This is the default, but most people are encouraged to change this immediately. The result of using false is that Git doesn’t ever mess with line endings on your file. You can check in files with LF or CRLF or CR or some random mix of those three and Git does not care. This can make diffs harder to read and merges more difficult. Most people working in a Unix/Linux world use this value because they don’t have CRLF problems and they don’t need Git to be doing extra work whenever files are written to the object database or written out into the working directory.

• core.autocrlf = true – This means that Git will process all text files and make sure that CRLF is replaced with LF when writing that file to the object database and turn all LF back into CRLF when writing out into the working directory. This is the recommended setting on Windows because it ensures that your repository can be used on other platforms while retaining CRLF in your working directory.

• core.autocrlf = input – This means that Git will process all text files and make sure that CRLF is replaced with LF when writing that file to the object database. It will not, however, do the reverse. When you read files back out of the object database and write them into the working directory they will still have LFs to denote the end of line. This setting is generally used on Unix/Linux/OS X to prevent CRLFs from getting written into the repository. The idea being that if you pasted code from a web browser and accidentally got CRLFs into one of your files, Git would make sure they were replaced with LFs when you wrote to the object database.

You can run git config --global core.autocrlf to see what this value is set to on your system. If nothing comes back that means you are on the using the default which is false.

How does Git know that a file is text? Good question. Git has an internal method for heuristically checking if a file is binary or not. A file is deemed text if it is not binary. Git can sometimes be wrong and this is the basis for our next setting.

The next setting that was introduced is core.safecrlf which is designed to protect against these cases where Git might change line endings on a file that really should just be left alone.

• core.safecrlf = true – When getting ready to run this operation of replacing CRLF with LF before writing to the object database, Git will make sure that it can actually successfully back out of the operation. It will verify that the reverse can happen (LF to CRLF) and if not the operation will be aborted.

• core.safecrlf = warn – Same as above, but instead of aborting the operation, Git will just warn you that something bad might happen.

One final layer on all this is that you can create a file called .gitattributes in the root of your repository and add rules for specific files. These rules allow you to control things like autocrlf on a per file basis. So you could, for instance, put this in that file to tell Git to always replace CRLF with LF in txt files:

*.txt crlf

Or you could do this to tell Git to never replace CRLF with LF for txt files like this:

*.txt -crlf

Or you could do this to tell Git to only replace CRLF with LF when writing, but to read back LF when writing the working directory for txt files like this:

*.txt crlf=input

OK. Got all that? See all the problems and the mess we’ve made? It gets worse when you start working on projects that push you towards different global settings. Enter the new system which is available in Git 1.7.2 and above.

The New System

The new system moves to defining all of this in the .gitattributes file that you keep with your repository. This means that line endings can be encapsulated entirely within a repository and don’t depend on everyone having the proper global settings.

In the new system you are in charge of telling git which files you would like CRLF to LF replacement to be done on. This is done with a text attribute in your repository’s .gitattributes file. In this case the man page is actually quite helpful. Here are some examples of using the text attribute:

• *.txt text – Set all files matching the filter *.txt to be text. This means that Git will run CRLF to LF replacement on these files every time they are written to the object database and the reverse replacement will be run when writing out to the working directory.

• *.txt -text – Unset all files matching the filter. These files will never run through the CRLF to LF replacement.

• *.txt text=auto – Set all files matching the filter to be converted (CRLF to LF) if those files are determined by Git to be text and not binary. This relies on Git’s built in binary detection heuristics.

If a file is unspecified then Git falls back to the core.autocrlf setting and you are back in the old system. This is how backwards compatibility is maintained, but I would recommend (especially for Windows developers) that you explicitly create a .gitattributes file.

Here is an example you might use for a C# project:

# These files are text and should be normalized (convert crlf => lf)
*.cs      text diff=csharp
*.xaml    text
*.csproj  text
*.sln     text
*.tt      text
*.ps1     text
*.cmd     text
*.msbuild text
*.md      text

# Images should be treated as binary
# (binary is a macro for -text -diff)
*.png     binary
*.jepg    binary

*.sdf     binary

One final note that the man page for gitattributes mentions is that you can tell git to detect all text files and automatically normalize them (convert CRLF to LF):

* text=auto

This is certainly better than requiring everyone to be on the same global setting for core.autocrlf, but it means that you really trust Git to do binary detection properly. In my opinion it is better to explicitly specify your text files that you want normalized. Don’t forget if you are going to use this setting that it should be the first line in your .gitattributes file so that subsequent lines can override that setting.

We are huge fans of the Arduino stack which is hosted on GitHub, and there are dozens of Arduino boards running around the office. The beauty of writing code for the Arduino is that you rarely end up writing a lot of it and once you’ve written a sketch, it runs on a whole variety of compatible boards. Compared to how microcontroller prototyping was done 5 years ago, this is a serious breath of fresh air. There are some of us, however, who would rather continue to write code in vi (MacVim in my case), so I came up with a nice hack…

Enter vim-arduino.

This is my first attempt at getting Arduino IDE functionality into MacVim. Right now you can compile, deploy and open a serial port. The board for deployment always defaults to ‘uno’, but you can override that by putting the name of the board  on the first line of your sketch like so (any board found in boards.txt is valid):

// board: atmega328

Compiling code can be done like so: <Leader>ac

Compiling and the deploying is done like so: <Leader>ad

You can also open a serial port for debugging like this: <Leader>as

The goal here is to be 100% compatible with existing Arduino sketches and to take advantage of the rest of the Arduino environment. Your hardware hacking peers should never know you are secretly rocking vi.

Checkout the README to get things setup and bug me on Twitter if you find any of this useful.

Abstract

Ever wonder how software is designed and developed at GitHub? Are you curious about how new features are deployed to the site? (Hint: ask the robot.) Want to know why we don’t have any managers and don’t track vacation days?

This talk will explore running your company like an open source project and give some insight into how GitHub continues to leverage ruby and other open source tools to keep up with massive data loads and a growing community of users.

Slides

http://speakerdeck.com/u/tclem/p/code-first-ask-questions-later

Video

I know there was AV taken at the conference and I will post a link once it is available.

http://confreaks.net/videos/723-rockymtnruby2011-code-first-ask-questions-later

Credits

The font in my presentation is called Junction and can be found on the League of Movable Type. Many of the photographs are my own or from the GitHub Instagram stream. A couple of them are from flickr under the creative commons license: easy button, just do it, robot. The grainy robot attacking image is actually from SNL.

Part 2: GitHub

Okay, now we can move on to GitHub. Unlike writing a paper, software developers rarely write code all by themselves in a closet. Well, some do… but most of us collaborate on our software projects. GitHub provides a meeting place for software developers to collaborate around code and the different versions of that code. It stretches the analogy, but imagine that your paper with all the different snapshots you took along the way was available for other people not just to read, but to derive new papers from. You would always be credited as the original author, but everyone can create derivative works and if someone added a really nice abstract you could pull just that change back into your version of the paper. GitHub acts like a digital room where everyone hangs out to share their projects, ideas, and most importantly their code. The same way that Facebook provides a medium for people to hang out digitally and share status, photos, notes, etc –GitHub provides a medium for programmers to share code.

Code is a very abstract notion to people who don’t program for a living, and this is where I think the idea of writing a paper as an analogy for writing code is very helpful. Just as you could have written your paper in Spanish or French or English, code can be written in any number of languages. The primary purpose of code is to communicate something to a computer. You can think of it like writing an instruction manual. In 3rd grade, I remember, we did an activity where we had to explicitly write out the instructions for making a peanut butter and jelly sandwich. The teacher then took our written instructions and followed them to a tee. If you wrote “Take two pieces of bread”, she would literally tear off two very small pieces of bread to start making the sandwich. If you didn’t explain how to open the jelly jar, there would be no jelly on your sandwich. If you didn’t explicitly say that the jelly and peanut butter sides of the bread should be touching in the middle, you would get a sandwich with jelly and peanut butter on the outside. This is what it is like when you have to communicate with a computer. At the lowest level, computers are really dumb; they can only do what they are told, so your instructions (code) must tell the machine exactly what you want it to do.

As you can probably imagine, writing all this code can get very unwieldy. Not only because of the sheer amount of code that it takes to develop a complex system like the Android operating system, but because that code is written by a large number of programmers (think lots of people editing the same paper all at once). This is where GitHub really shines. GitHub provides the ability for developers to publish and share code, solicit collaboration from other programmers, gain reputation in the community and discover/contribute to other code projects of interest. In many ways it is a realization of the original intent of the internet. To throw out yet another metaphor, GitHub creates a framework for the evolutionary improvement of software in real time. Like the evolution of species, software is allowed to mutate and change over time creating new variants, symbiotic relationships (sometimes even parasitic ones!), and a dazzling array of constructs and programs. GitHub is like primordial soup in which all these software projects are interacting, growing and changing. And instead of eons, this all happens at the speed of the interwebs.

If you want to learn more about GitHub, you know where to go.

If things are still fuzzy, then all you need to know is that we run a web site…. And we sell these cute little creatures that are a cross between a cat and an octopus…

So here, presented in two parts, is the crash course for the layman:

Part 1: Git

We have to start with Git. Git and GitHub are two different things. Git is a version control system. You don’t need to know anything about it other than it is amazing.

Okay, maybe I’ll tell you a little more than that. If you have ever typed a paper into a computer (or written one by hand) you have probably used a low fidelity form of version control. Say you are working on a big paper and at certain points you want to save off a version or draft. You might do this for many reasons. Maybe it is an important paper and you want to put a copy somewhere else safe. Maybe you add a `01` to the filename and later a `02` and so on (or you might use today’s date `ImportantPaper_4_13_2011.txt`). Maybe you need to turn in a draft or pass a draft off for editing. These activities are all analogous to creating a snapshot of what your paper looks like at a certain point in time and saving it off. Another good example of why having snapshots is important is if you are going to completely re-write your conclusion. Having a saved version of your old conclusion lets you go back to it at any time to see what you wrote or even to revert back because your new conclusion turned out to be a bad idea.

Software developers are usually focused on code instead of papers, but they have the same problems. You need to be able to quickly and easily take snapshots of the current state of your code base (along with some comments about that revision) and have the ability to come back to that point in history at any time. You might also want to compare the current state of your code with any previous state. Programmers call the solution to this problem version control. Just as you could write your paper in any number of document editing systems (Word, Pages, text files, Quark, LaTeX, etc) there are many different version control systems. Git is one of those systems. Developers write programs in a variety of computer languages and these programs are sort of like big papers, but vastly more complex. Having the ability to take snapshots frequently and travel back in history to see how a code file changed over time is an essential activity.

If you are really interested in learning more about Git you can download and learn about it here. I would also highly recommend my friend Scott Chacon’s book Pro Git.

If you have stuck around just for the Octocats, then I suggest you head over to the octodex until part 2 comes out.

I took a new position as a developer at GitHub working out of their main San Francisco office and couldn’t be more excited about it. The culture is ideal, my co-workers are some of the smartest people I have worked with yet, I’m learning a ton, and I have big plans for all the amazing things this company is going to do in the next few years. Ramping up in a new job is always exciting, with all the new things to learn and people to meet. Finding your way around a new city just adds to the excitement: where to live, where to eat, where to buy crap you need. I cannot speak more highly of the SF GitHub peeps who have gone out of their way to make my family and I feel welcome. From driving us around all weekend to find an apartment, to offering rides, to supplying blankets & pillows & air mattresses for sleeping in newly rented apartments, to dinner invites and insights about living in SF –we have been enthusiastically ushered into the community.

As far as what I’m working on at GitHub, here is just a taste (more to come later, I promise)…

Tom and I are working hard to extend the reach of our campfire robot (hubot) into the physical world. It still needs some better packaging, but version 1 of “Door Me” is up and running; allowing GitHub scros to never leave their seats to answer the door buzzer again.

I’m also jamming on libgit2 –building out objective-c bindings, contributing to rugged and some of the other language bindings. If you aren’t familiar with the project, you should check it out. It is probably one of the best examples of TDD on a C project that I’ve seen recently.

Rock climbing (and especially bouldering which is what I do the most of) involves solving problems and this, I think, is at the root of the correlation. You might think that at the end of a day of writing code, the last thing you’d want to be faced with is another set of problems to solve. But there is something very refreshing about the mental and physical challenges associated with climbing that compliment a day job lived in the abstract. The rock is real, the goal is fixed. You need a combination of mental awareness, physical strength, dexterity, technique and lots of plain old perseverance to get up a rock face. There is also a individual/collaborate dichotomy to climbing similar to the world of math, science, and programming. At the end of the day, it is you the individual that must solve the problem and climb the route. No one is there to help you and it comes down to how well you execute the sequence of movements required to accomplish the climb. However, in the background there is a constant community of collaboration going on. Beta is exchanged. Technique is discussed. Methods of training or recovery debated. Different movements are tried over and over again with subtle variation and the results are communicated to the group.

If you get your thumb fully engaged and pinch while you are crimping off the top of that left hand you can gain enough pull to make that high move. But you have to keep that right toe on or it is all over.

Beta often doesn’t work for everyone though. Height, ape index and a variety of other physical factors determine how you go about climbing a particular problem and in many cases a friend’s method will be of no help to you. One of my peers is tall enough that I almost always have to come up with a different set of beta for climbing the same problems because I just can’t reach the holds and keep my feet where he does. Another friend is so much stronger than I that he doesn’t worry about his feet too much and is very adept at jumping for holds and then catching and stabilizing his swing. I’m a much more cerebral and technique based climber. I’m not overly strong, so I rely on body position, using my feet, maximum efficiency of movement and subtle leverage points to get up the rock. One of things I’m trying to learn now as I have progressed to harder climbs is actually how to move very dynamically on the rock by jumping and pogo-ing to catch holds while using my core to contain swing and stay put after I come back in contact with the rock again.

As a developer moving from the abstract world of 1′s and 0′s to the physical world of rock, sweat and sometimes blood it seems there is endless entertainment in the realm of conquering boulders and cliffs. The same way I sometimes wake up in the morning with the solution to a programming challenge appearing in my head, I will often dream about a particular bouldering problem I’m working on. Or I’ll be driving to work, visualizing the movements in my head of a particularly hard climb, my hands sweating on the steering wheel. When I come back to that problem the next day things click that weren’t working the day before and I’ll find myself  sending what previously felt impossible.

I’ve taken a few of my fellow developers climbing and have been fascinated by the reaction to the sport. For someone who has never climbing before (and especially if they are particularly strong or adept at another sport) climbing for the first time can be a very frustrating activity. Traditional strength does you nothing in climbing until you learn how to use it. And often it is forearm and contact strength that matters way more than your ability to bench press. You legs also matter much more than your arms do and some of the most common climbing advise heard is to climb with your legs, not your arms. One of these developers in particular impressed me. Not necessarily with his climbing ability, but with his persistence in solving the problems. I think he spent the entire night on a single bouldering problem. He worked every move. He listened intently to any guidance that I offered and then was back at it with renewed vigor. And by the end of the night he made it all the way up! What is really interesting is that over the years of working with this guy, I’ve noticed that this is the same way he tackles programming problems: with quiet persistence and a never die attitude. I learned it is equally important to check in on him and make sure he has what he needs to be productive or give some piece of guidance, but at the end of the day he delivers.

I think software engineering is much like this situation where you are constantly being thrown at problems that you don’t know enough about. You are continually learning new things and being asked to communicate where you are in solving the problem and when it will be done. You need a combination of a love for what you are doing, maybe some base talent, the ability to learn new skills on the fly, and a whole lot of persistence. Your attitude as you approach the inevitable road blocks and set backs matters more than anything else. That is why programmers love climbing. Because they thrive off those situations of solving hard problems, dealing with set backs and ultimately accomplishing great things. It isn’t burdensome to us, it is drives us forward and onto the next challenge. We thrive off it.

To give some brief background: Advanced Mobile 311 is a new product for Blue Dot that is providing the ability for citizens to easily report issues in their communities. 311 is a phone number set aside in the US for reporting non-emergency problems and our applications take this concept into the hands of smart phone users allowing them to mark the location of problems on a map (possibly using GPS), take a picture and submit a specific service request to their city or municipality. We certainly aren’t the only one doing this and some US cities like San Fransisco and New York have already implemented and been running crowd sourcing 311 solutions for a while now. City Sourced is working hard at this same problem with limited partnerships around the US. Much more can be said around the business models and players in the Gov 2.0 movement, but for now I’m more interested in the process of writing and delivering consumer applications which is something very new for me.

While it will take a week or so for the application updates I just submitted to make it through the review process in their respective store, you can check out the existing apps both in the iPhone App Store and the Windows Marketplace (requires Zune unfortunately). Both are free of charge so feel free to try them out! By in large it has been a positive experience developing both applications.

Prior to this, I had no real experience developing applications on a mac, using Xcode or writing Objective-c. Once I got over the C# to Objective-c transition and understood the basic paradigms of the development framework I was quite productive in creating the iPhone version of the application. I have been a mac user for a long time (really since I was a kid) so the OS is familiar to me and I intuitively understand the UX. The API and maturity of the iOS SDK is really very impressive and the 311 application fit very well into what the platform was designed to do. I actually created the iPhone app first (as Windows Phone 7 was just a rumor at this time) so it was a good exercise to have to think in another language. I think the one thing that I struggled with the most was memory management specifically around the didReceiveMemoryWarning and viewDidUnload paradigm. Debugging programs and understanding errors in Xcode is kinda like taking a step back in time when you are used to Visual Studio and .net development. The maturity of the iOS platform also means that you have to deal with supporting multiple devices and multiple versions of the operating system along with new devices like the iPad which have a different form factor and require a different set of graphics. All that said, it was quite pleasurable developing on my mac and the speed of the iPhone simulator is a breath of fresh air after using the WM emulator. The tools felt lightweight, high performing and easy to work with. I even dove in and did some of the graphic design for the internal menu icons and status bubbles.

Submitting to the App Store was really no big deal. Instructions to properly build and sign your application were straightforward. The only thing that bites me each time is that I chose to have a space in my application’s name “Mobile 311″ and this seems to be a continued source of  problems when uploading to the Store (there are workarounds – comment if you are interested).

On the Windows Phone side of things we were lucky enough to be on the white list for applications that came out with the release of the physical phone. The Microsoft stack is really where Blue Dot feels at home and the development experience on the Windows Phone was very impressive (especially since I was basically working on a pre-release tool set and a version 1.0 product with limited access to real devices and all the other interesting things that come with being an early adopter). I must say that Microsoft was very supportive in this process, even providing consulting resources when necessary (although most of my issues were resolved by waiting for the next release of the tools). Development for Windows Phone applications is done in Visual Studio 2010 and in C# & Silverlight. I had never done any WPF or Silverlight development before, but the ramp up was pretty easy and I must say that it is a huge improvement over WinForms development. Visual Studio is a truly first class development environment and VS 2010 only raises the bar. The new wp7 emulator is fantastic (MS obviously took a page from Apple’s book here) – it loads very quickly and makes it easy to develop and debug your application. I struggled a little bit with things like the camera functionality (which does not work on the emulator) and understanding how the Task system works. It is really nice not to have to worry about memory management and the debugging tools are far superior to those in Xcode. Overall, it was very fun to re-create this application in another tool set/environment. I tried to make the app feel like a windows phone app and not an iPhone port and was pretty happy with how things turned out.

Submitting to the Marketplace was a very similar process to App Store submittal. The only thing that annoys me here is that the Marketplace holds all sorts of other stuff (not just phone apps) and you can only view things in the store you have Zune installed.

We are considering creating apps for the other leading smartphone operating systems, but until that happens I also created a mobile optimized web site that is reachable by any browser for submitting service request. Obviously there is no way to use things like GPS, but you can still submit requests to the system.

Finally, all of the server components are now up and running in Windows Azure, which is Microsoft’s cloud OS. Our server is architect-ed in a way that it can run both in a traditional hosted model and on Azure. The difference between our 311 system and some of the other offerings right now is that we are pre-integrated into some of the major ERP systems that cities already use to mange service requests. And by having our infrastructure in Azure we can offer a data stream to anyone without them having to purchase and provision servers or worry about physically infrastructure.

Go check out the apps! iPhone, Windows Phone