en/multiplayer.txt @@ -9,7 +9,7 @@ target: book book/default.css book.html book.pdf # The book consists of these text files in the following order: TXTFILES := preface.txt intro.txt basic.txt clone.txt branch.txt history.txt \ - grandmaster.txt secrets.txt drawbacks.txt translate.txt + multiplayer.txt grandmaster.txt secrets.txt drawbacks.txt translate.txt book.xml: $(addprefix $(LANG)/,$(TXTFILES)) # Kludge to make preface sections work for languages besides English. Makefile @@ -1,4 +1,4 @@ -== Git Shortcomings == +== Appendix A: Git Shortcomings == There are some Git issues I've swept under the carpet. Some can be handled easily with scripts and hooks, some require reorganizing or redefining the project, and for the few remaining annoyances, one will just have to wait. Or better yet, pitch in and help! en/drawbacks.txt @@ -4,214 +4,31 @@ This pretentiously named page is my dumping ground for uncategorized Git tricks. === Source Releases === -For my projects, Git tracks exactly the files I'd like to archive and release to users. To create a tarball of the source code, I run: +For my projects, Git tracks exactly the files I'd like to archive and release +to users. To create a tarball of the source code, I run: $ git archive --format=tar --prefix=proj-1.2.3/ HEAD -=== Git Over SSH, HTTP === - -Suppose you have ssh access to a web server, but Git is not installed. Though less efficient than its native protocol, Git can communicate over HTTP. - -Download, compile and install Git in your account, and create a repository in your web directory: - - $ GIT_DIR=proj.git git init - -In the "proj.git" directory, run: - - $ git --bare update-server-info - $ chmod a+x hooks/post-update - -From your computer, push via ssh: - - $ git push web.server:/path/to/proj.git master - -and others get your project via: - - $ git clone http://web.server/proj.git - -=== Git Over Anything === - -Want to synchronize repositories without servers, or even a network connection? -Need to improvise during an emergency? -We've seen <<makinghistory, *git fast-export* and *git fast-import* can convert -repositories to a single file and back>>. We could shuttle such files back and -forth to transport git repositories over any medium, but a more efficient tool -is *git bundle*. - -The sender creates a 'bundle': - - $ git bundle create somefile HEAD - -then transports the bundle, +somefile+, to the other party somehow: email, -thumb drive, floppy disk, an *xxd* printout and an OCR machine, -reading bits over the phone, smoke signals, etc. The receiver retrieves -commits from the bundle by typing: - - $ git pull somefile - -The receiver can even do this from an empty repository. Despite its -size, +somefile+ contains the entire original git repository. - -In larger projects, eliminate waste by bundling only changes the other -repository lacks: - - $ git bundle create somefile HEAD ^COMMON_SHA1 - -If done frequently, one could easily forget which commit was last sent. The -help page suggests using tags to solve this. Namely, after you send a bundle, -type: - - $ git tag -f lastbundle HEAD - -and create new refresher bundles with: - - $ git bundle create newbundle HEAD ^lastbundle - -=== Patches: The Global Currency === - -Patches are text representations of your changes that can be easily understood -by computers and humans alike. This gives them universal appeal. You can email a -patch to developers no matter what version control system they're using. As long -as your audience can read their email, they can see your edits. Similarly, on -your side, all you require is an email account: there's no need to setup an online Git repository. - -Recall from the first chapter: - - $ git diff COMMIT - -outputs a patch which can be pasted into an email for discussion. In a Git -repository, type: - - $ git apply < FILE - -to apply the patch. - -In more formal settings, when author names and perhaps signatures should be -recorded, generate the corresponding patches past a certain point by typing: - - $ git format-patch START_COMMIT - -The resulting files can be given to *git-send-email*, or sent by hand. You can also specify a range of commits: - - $ git format-patch START_COMMIT..END_COMMIT - -On the receving end, save an email to a file, then type: - - $ git am < FILE - -This applies the incoming patch and also creates a commit, including information such as the author. - -With a browser email client, you may need to click a button to see the email in its raw original form before saving the patch to a file. - -There are slight differences for mbox-based email clients, but if you use one -of these, you're probably the sort of person who can figure them out easily -without reading tutorials! - -=== Sorry, We've Moved === - -From earlier chapters, we've seen that after cloning a repository, running -*git push* or *git pull* will automatically push to or pull from the original -URL. How does Git do this? The secret lies in config options initialized -created with the clone. Let's take a peek: - - $ git config --list - -The +remote.origin.url+ option controls the source URL; "origin" is a nickname -given to the source repository. As with the "master" branch convention, we may -change or delete this nickname but there is usually no reason for doing so. - -If the the original repository moves, we can update the URL via: - - $ git config remote.origin.url NEW_URL - -The +branch.master.merge+ option specifies the default remote branch in -a *git pull*. During the initial clone, it is set to the current branch of the -source repository, so even if the HEAD of the source repository subsequently -moves to a different branch, a later pull will faithfully follow the -original branch. - -This option only applies to the repository we first cloned from, which is -recorded in the option +branch.master.remote+. If we pull in from other -repositories we must explicitly state which branch we want: - - $ git pull ANOTHER_URL master - -The above explains why some of our earlier push and pull examples occasionally -required arguments. - -=== Remote Branches === - -When you clone a repository, you also clone all its branches. You may not have -noticed this because Git hides them away: you must ask for them specifically. -This prevents branches in the remote repository from interfering with -your branches, and also makes Git easier for beginners. - -List the remote branches with: - - $ git branch -r - -You should see something like: - - origin/HEAD - origin/master - origin/experimental - -These represent branches and the HEAD of the remote repository, and can be used -in regular Git commands. For example, suppose you have made many commits, and -wish to compare against the last fetched version. You could search through the -logs for the appropriate SHA1 hash, but it's much easier to type: - - $ git diff origin/HEAD - -Or you can see what the "experimental" branch has been up to: - - $ git log origin/experimental - -=== Multiple Remotes === - -Suppose two other developers are working on our project, and we want to -keep tabs on both. We can follow more than one repository at a time with: - - $ git remote add other ANOTHER_URL - $ git pull other some_branch - -Now we have merged in a branch from the second repository, and we have -easy access to all branches of all repositories: - - $ git diff origin/experimental^ other/some_branch~5 - -But what if we just want to compare their changes without affecting our own -work? In other words, we want to examine their branches without having -their changes invade our working directory. In this case, rather than pull, -run: - - $ git fetch # Fetch from origin, the default. - $ git fetch other # Fetch from the second programmer. - -This fetches their histories and nothing more, so although the working -directory remains untouched, we can refer to any branch of any repository in -a Git command. By the way, behind the scenes, a pull is simply a fetch followed -by *git merge*; recall the latter merges a given commit into the working -directory. Usually we pull because we want to merge after a fetch; this -situation is a notable exception. - -See *git help remote* for how to remove remote repositories, ignore certain -branches, and more. - === Commit What Changed === -Telling Git when you've added, deleted and renamed files is troublesome for certain projects. Instead, you can type: +Telling Git when you've added, deleted and renamed files is troublesome for +certain projects. Instead, you can type: $ git add . $ git add -u -Git will look at the files in the current directory and work out the details by itself. Instead of the second add command, run `git commit -a` if you also intend to commit at this time. +Git will look at the files in the current directory and work out the details by +itself. Instead of the second add command, run `git commit -a` if you also +intend to commit at this time. See *git help ignore* for how to specify files +that should be ignored. You can perform the above in a single pass with: $ git ls-files -d -m -o -z | xargs -0 git update-index --add --remove -The *-z* and *-0* options prevent ill side-effects from filenames containing strange characters. Note this command adds ignored files. You may want to use the `-x` or `-X` option. +The *-z* and *-0* options prevent ill side-effects from filenames containing +strange characters. As this command adds ignored files, you may want to use the +`-x` or `-X` option. === My Commit Is Too Big! === @@ -403,13 +220,14 @@ cases this can overlook. If only I had bought idiot insurance by using a _hook_ to alert me about these problems: - $ chmod +x .git/hooks/pre-commit + $ cd .git/hooks + $ cp pre-commit.sample pre-commit # Older Git versions: chmod +x pre-commit Now Git aborts a commit if useless whitespace or unresolved merge conflicts are detected. For this guide, I eventually added the following to the beginning of the -*pre-commit* hook to warn about absent-mindedness: +*pre-commit* hook to guard against absent-mindedness: if git ls-files -o | grep '\.txt$'; then echo FAIL! Untracked .txt files. @@ -418,9 +236,7 @@ For this guide, I eventually added the following to the beginning of the Several git operations support hooks; see *git help hooks*. One can write hooks to complain about spelling mistakes in commit messages, add new files, indent -paragraphs, complain about lines over 80 characters long, add an entry to a -webpage, play a sound, and so on. +paragraphs, append an entry to a webpage, play a sound, and so on. -In fact, we encountered the *post-update* hook while discussing Git over -HTTP: in this case, after the repository is updated, a hook script -maintains a few files Git needs for non-native communication. +We encountered the *post-update* hook earlier when discussing Git over +HTTP. This hook updates a few files Git needs for non-native communication. en/grandmaster.txt @@ -1,4 +1,4 @@ -== Appendix A: Translating This Guide == +== Appendix B: Translating This Guide == Clone the source, then create a directory corresponding to the target http://www.iana.org/assignments/language-subtag-registry[language's IETF tag]: see http://www.w3.org/International/articles/language-tags/Overview.en.php[the W3C article on internationalization]. For example, English is "en", Japanese is "ja", and Traditional Chinese is "zh-Hant". In the new directory, and translate the +txt+ files from the "en" subdirectory. en/translate.txt 8a574254c5c48faa8b7cd744b532a6f03f375c5b Ben Lynn benlynn@gmail.com http://github.com/blynn/gitmagic/commit/feed681568d9453f6472d003dbdc45a06d49175b feed681568d9453f6472d003dbdc45a06d49175b 2009-06-26T13:57:18-07:00 2009-06-26T02:10:47-07:00 Split Grandmastery chapter. It was getting too big. Also, the chapter on shortcomings is now an appendix. I like having the last chapter end with a section related to the opening sentence of the preface. 40f2a5f666c27495dbf2018b5a230a9c661debd0 Ben Lynn benlynn@gmail.com