diff --git a/en/book/01-introduction/chapter1.asc b/en/book/01-introduction/chapter1.asc index 474fcae91..0b93cc66e 100644 --- a/en/book/01-introduction/chapter1.asc +++ b/en/book/01-introduction/chapter1.asc @@ -230,6 +230,9 @@ You can also check what Git thinks a specific key’s value is by typing `git co $ git config user.name Scott Chacon +==== Credential Caching + + === Getting Help If you ever need help while using Git, there are three ways to get the manual page (manpage) help for any of the Git commands: diff --git a/en/book/02-git-basics/chapter2.asc b/en/book/02-git-basics/chapter2.asc index 05f337a58..0e4d6c5ff 100644 --- a/en/book/02-git-basics/chapter2.asc +++ b/en/book/02-git-basics/chapter2.asc @@ -625,6 +625,22 @@ You can see the commit history in the top half of the window along with a nice a At any stage, you may want to undo something. Here, we’ll review a few basic tools for undoing changes that you’ve made. Be careful, because you can’t always undo some of these undos. This is one of the few areas in Git where you may lose some work if you do it wrong. +==== Reset Demystified + +===== The Three Trees + +===== The Workflow + +===== The Role of Reset + +===== Reset With a Path + +===== A Fun Example + +===== Check It Out + +===== Summary + ==== Changing Your Last Commit One of the common undos takes place when you commit too early and possibly forget to add some files, or you mess up your commit message. If you want to try that commit again, you can run commit with the `--amend` option: @@ -703,6 +719,8 @@ You can see that the changes have been reverted. You should also realize that th Remember, anything that is committed in Git can almost always be recovered. Even commits that were on branches that were deleted or commits that were overwritten with an `--amend` commit can be recovered (see Chapter 9 for data recovery). However, anything you lose that was never committed is likely never to be seen again. +==== Undoing All Changes + === Working with Remotes To be able to collaborate on any Git project, you need to know how to manage your remote repositories. Remote repositories are versions of your project that are hosted on the Internet or network somewhere. You can have several of them, each of which generally is either read-only or read/write for you. Collaborating with others involves managing these remote repositories and pushing and pulling data to and from them when you need to share work. diff --git a/en/book/03-git-branching/chapter3.asc b/en/book/03-git-branching/chapter3.asc index ba5b1a212..e76190f4d 100644 --- a/en/book/03-git-branching/chapter3.asc +++ b/en/book/03-git-branching/chapter3.asc @@ -280,6 +280,8 @@ If you’re happy with that, and you verify that everything that had conflicts h You can modify that message with details about how you resolved the merge if you think it would be helpful to others looking at this merge in the future — why you did what you did, if it’s not obvious. +==== Undoing Merges + === Branch Management Now that you’ve created, merged, and deleted some branches, let’s look at some branch-management tools that will come in handy when you begin using branches all the time. @@ -554,6 +556,8 @@ You have to merge that work in at some point so you can keep up with the other d If you treat rebasing as a way to clean up and work with commits before you push them, and if you only rebase commits that have never been available publicly, then you’ll be fine. If you rebase commits that have already been pushed publicly, and people may have based work on those commits, then you may be in for some frustrating trouble. +==== Rebase vs. Merge + === Summary We’ve covered basic branching and merging in Git. You should feel comfortable creating and switching to new branches, switching between branches and merging local branches together. You should also be able to share your branches by pushing them to a shared server, working with others on shared branches and rebasing your branches before they are shared. diff --git a/en/book/04-git-server/chapter4.asc b/en/book/04-git-server/chapter4.asc index 84567b422..ead4b58d2 100644 --- a/en/book/04-git-server/chapter4.asc +++ b/en/book/04-git-server/chapter4.asc @@ -354,153 +354,69 @@ Notice that you have to tell the command where to find your Git repositories wit Again, GitWeb can be served with any CGI capable web server; if you prefer to use something else, it shouldn’t be difficult to set up. At this point, you should be able to visit `http://gitserver/` to view your repositories online, and you can use `http://git.gitserver` to clone and fetch your repositories over HTTP. -=== Gitosis - -Keeping all users’ public keys in the `authorized_keys` file for access works well only for a while. When you have hundreds of users, it’s much more of a pain to manage that process. You have to shell onto the server each time, and there is no access control — everyone in the file has read and write access to every project. - -At this point, you may want to turn to a widely used software project called Gitosis. Gitosis is basically a set of scripts that help you manage the `authorized_keys` file as well as implement some simple access controls. The really interesting part is that the UI for this tool for adding people and determining access isn’t a web interface but a special Git repository. You set up the information in that project; and when you push it, Gitosis reconfigures the server based on that, which is cool. - -Installing Gitosis isn’t the simplest task ever, but it’s not too difficult. It’s easiest to use a Linux server for it — these examples use a stock Ubuntu 8.10 server. - -Gitosis requires some Python tools, so first you have to install the Python setuptools package, which Ubuntu provides as python-setuptools: - - $ apt-get install python-setuptools - -Next, you clone and install Gitosis from the project’s main site: - - $ git clone git://eagain.net/gitosis.git - $ cd gitosis - $ sudo python setup.py install - -That installs a couple of executables that Gitosis will use. Next, Gitosis wants to put its repositories under `/home/git`, which is fine. But you have already set up your repositories in `/opt/git`, so instead of reconfiguring everything, you create a symlink: - - $ ln -s /opt/git /home/git/repositories - -Gitosis is going to manage your keys for you, so you need to remove the current file, re-add the keys later, and let Gitosis control the `authorized_keys` file automatically. For now, move the `authorized_keys` file out of the way: - - $ mv /home/git/.ssh/authorized_keys /home/git/.ssh/ak.bak - -Next you need to turn your shell back on for the 'git' user, if you changed it to the `git-shell` command. People still won’t be able to log in, but Gitosis will control that for you. So, let’s change this line in your `/etc/passwd` file - - git:x:1000:1000::/home/git:/usr/bin/git-shell - -back to this: - - git:x:1000:1000::/home/git:/bin/sh - -Now it’s time to initialize Gitosis. You do this by running the `gitosis-init` command with your personal public key. If your public key isn’t on the server, you’ll have to copy it there: - - $ sudo -H -u git gitosis-init < /tmp/id_dsa.pub - Initialized empty Git repository in /opt/git/gitosis-admin.git/ - Reinitialized existing Git repository in /opt/git/gitosis-admin.git/ - -This lets the user with that key modify the main Git repository that controls the Gitosis setup. Next, you have to manually set the execute bit on the `post-update` script for your new control repository. - - $ sudo chmod 755 /opt/git/gitosis-admin.git/hooks/post-update - -You’re ready to roll. If you’re set up correctly, you can try to SSH into your server as the user for which you added the public key to initialize Gitosis. You should see something like this: - - $ ssh git@gitserver - PTY allocation request failed on channel 0 - fatal: unrecognized command 'gitosis-serve schacon@quaternion' - Connection to gitserver closed. - -That means Gitosis recognized you but shut you out because you’re not trying to do any Git commands. So, let’s do an actual Git command — you’ll clone the Gitosis control repository: - - # on your local computer - $ git clone git@gitserver:gitosis-admin.git - -Now you have a directory named `gitosis-admin`, which has two major parts: - - $ cd gitosis-admin - $ find . - ./gitosis.conf - ./keydir - ./keydir/scott.pub - -The `gitosis.conf` file is the control file you use to specify users, repositories, and permissions. The `keydir` directory is where you store the public keys of all the users who have any sort of access to your repositories — one file per user. The name of the file in `keydir` (in the previous example, `scott.pub`) will be different for you — Gitosis takes that name from the description at the end of the public key that was imported with the `gitosis-init` script. +=== Git Daemon -If you look at the `gitosis.conf` file, it should only specify information about the `gitosis-admin` project that you just cloned: +For public, unauthenticated read access to your projects, you’ll want to move past the HTTP protocol and start using the Git protocol. The main reason is speed. The Git protocol is far more efficient and thus faster than the HTTP protocol, so using it will save your users time. - $ cat gitosis.conf - [gitosis] +Again, this is for unauthenticated read-only access. If you’re running this on a server outside your firewall, it should only be used for projects that are publicly visible to the world. If the server you’re running it on is inside your firewall, you might use it for projects that a large number of people or computers (continuous integration or build servers) have read-only access to, when you don’t want to have to add an SSH key for each. - [group gitosis-admin] - writable = gitosis-admin - members = scott +In any case, the Git protocol is relatively easy to set up. Basically, you need to run this command in a daemonized manner: -It shows you that the 'scott' user — the user with whose public key you initialized Gitosis — is the only one who has access to the `gitosis-admin` project. + git daemon --reuseaddr --base-path=/opt/git/ /opt/git/ -Now, let’s add a new project for you. You’ll add a new section called `mobile` where you’ll list the developers on your mobile team and projects that those developers need access to. Because 'scott' is the only user in the system right now, you’ll add him as the only member, and you’ll create a new project called `iphone_project` to start on: +`--reuseaddr` allows the server to restart without waiting for old connections to time out, the `--base-path` option allows people to clone projects without specifying the entire path, and the path at the end tells the Git daemon where to look for repositories to export. If you’re running a firewall, you’ll also need to punch a hole in it at port 9418 on the box you’re setting this up on. - [group mobile] - writable = iphone_project - members = scott +You can daemonize this process a number of ways, depending on the operating system you’re running. On an Ubuntu machine, you use an Upstart script. So, in the following file -Whenever you make changes to the `gitosis-admin` project, you have to commit the changes and push them back up to the server in order for them to take effect: + /etc/event.d/local-git-daemon - $ git commit -am 'add iphone_project and mobile group' - [master]: created 8962da8: "changed name" - 1 files changed, 4 insertions(+), 0 deletions(-) - $ git push - Counting objects: 5, done. - Compressing objects: 100% (2/2), done. - Writing objects: 100% (3/3), 272 bytes, done. - Total 3 (delta 1), reused 0 (delta 0) - To git@gitserver:/opt/git/gitosis-admin.git - fb27aec..8962da8 master -> master +you put this script: -You can make your first push to the new `iphone_project` project by adding your server as a remote to your local version of the project and pushing. You no longer have to manually create a bare repository for new projects on the server — Gitosis creates them automatically when it sees the first push: + start on startup + stop on shutdown + exec /usr/bin/git daemon \ + --user=git --group=git \ + --reuseaddr \ + --base-path=/opt/git/ \ + /opt/git/ + respawn - $ git remote add origin git@gitserver:iphone_project.git - $ git push origin master - Initialized empty Git repository in /opt/git/iphone_project.git/ - Counting objects: 3, done. - Writing objects: 100% (3/3), 230 bytes, done. - Total 3 (delta 0), reused 0 (delta 0) - To git@gitserver:iphone_project.git - * [new branch] master -> master +For security reasons, it is strongly encouraged to have this daemon run as a user with read-only permissions to the repositories — you can easily do this by creating a new user 'git-ro' and running the daemon as them. For the sake of simplicity we’ll simply run it as the same 'git' user that Gitosis is running as. -Notice that you don’t need to specify the path (in fact, doing so won’t work), just a colon and then the name of the project — Gitosis finds it for you. +When you restart your machine, your Git daemon will start automatically and respawn if it goes down. To get it running without having to reboot, you can run this: -You want to work on this project with your friends, so you’ll have to re-add their public keys. But instead of appending them manually to the `~/.ssh/authorized_keys` file on your server, you’ll add them, one key per file, into the `keydir` directory. How you name the keys determines how you refer to the users in the `gitosis.conf` file. Let’s re-add the public keys for John, Josie, and Jessica: + initctl start local-git-daemon - $ cp /tmp/id_rsa.john.pub keydir/john.pub - $ cp /tmp/id_rsa.josie.pub keydir/josie.pub - $ cp /tmp/id_rsa.jessica.pub keydir/jessica.pub +On other systems, you may want to use `xinetd`, a script in your `sysvinit` system, or something else — as long as you get that command daemonized and watched somehow. -Now you can add them all to your 'mobile' team so they have read and write access to `iphone_project`: +Next, you have to tell your Gitosis server which repositories to allow unauthenticated Git server-based access to. If you add a section for each repository, you can specify the ones from which you want your Git daemon to allow reading. If you want to allow Git protocol access for your iphone project, you add this to the end of the `gitosis.conf` file: - [group mobile] - writable = iphone_project - members = scott john josie jessica + [repo iphone_project] + daemon = yes -After you commit and push that change, all four users will be able to read from and write to that project. +When that is committed and pushed up, your running daemon should start serving requests for the project to anyone who has access to port 9418 on your server. -Gitosis has simple access controls as well. If you want John to have only read access to this project, you can do this instead: +If you decide not to use Gitosis, but you want to set up a Git daemon, you’ll have to run this on each project you want the Git daemon to serve: - [group mobile] - writable = iphone_project - members = scott josie jessica + $ cd /path/to/project.git + $ touch git-daemon-export-ok - [group mobile_ro] - readonly = iphone_project - members = john +The presence of that file tells Git that it’s OK to serve this project without authentication. -Now John can clone the project and get updates, but Gitosis won’t allow him to push back up to the project. You can create as many of these groups as you want, each containing different users and projects. You can also specify another group as one of the members (using `@` as prefix), to inherit all of its members automatically: +Gitosis can also control which projects GitWeb shows. First, you need to add something like the following to the `/etc/gitweb.conf` file: - [group mobile_committers] - members = scott josie jessica + $projects_list = "/home/git/gitosis/projects.list"; + $projectroot = "/home/git/repositories"; + $export_ok = "git-daemon-export-ok"; + @git_base_url_list = ('git://gitserver'); - [group mobile] - writable = iphone_project - members = @mobile_committers +You can control which projects GitWeb lets users browse by adding or removing a `gitweb` setting in the Gitosis configuration file. For instance, if you want the iphone project to show up on GitWeb, you make the `repo` setting look like this: - [group mobile_2] - writable = another_iphone_project - members = @mobile_committers john + [repo iphone_project] + daemon = yes + gitweb = yes -If you have any issues, it may be useful to add `loglevel=DEBUG` under the `[gitosis]` section. If you’ve lost push access by pushing a messed-up configuration, you can manually fix the file on the server under `/home/git/.gitosis.conf` — the file from which Gitosis reads its info. A push to the project takes the `gitosis.conf` file you just pushed up and sticks it there. If you edit that file manually, it remains like that until the next successful push to the `gitosis-admin` project. +Now, if you commit and push the project, GitWeb will automatically start showing your iphone project. === Gitolite @@ -682,71 +598,11 @@ We'll round off this discussion with a sampling of other features, all of which, **Mirroring**: Gitolite can help you maintain multiple mirrors, and switch between them easily if the primary server goes down. -=== Git Daemon +=== GitLab -For public, unauthenticated read access to your projects, you’ll want to move past the HTTP protocol and start using the Git protocol. The main reason is speed. The Git protocol is far more efficient and thus faster than the HTTP protocol, so using it will save your users time. +=== Gerrit -Again, this is for unauthenticated read-only access. If you’re running this on a server outside your firewall, it should only be used for projects that are publicly visible to the world. If the server you’re running it on is inside your firewall, you might use it for projects that a large number of people or computers (continuous integration or build servers) have read-only access to, when you don’t want to have to add an SSH key for each. - -In any case, the Git protocol is relatively easy to set up. Basically, you need to run this command in a daemonized manner: - - git daemon --reuseaddr --base-path=/opt/git/ /opt/git/ - -`--reuseaddr` allows the server to restart without waiting for old connections to time out, the `--base-path` option allows people to clone projects without specifying the entire path, and the path at the end tells the Git daemon where to look for repositories to export. If you’re running a firewall, you’ll also need to punch a hole in it at port 9418 on the box you’re setting this up on. - -You can daemonize this process a number of ways, depending on the operating system you’re running. On an Ubuntu machine, you use an Upstart script. So, in the following file - - /etc/event.d/local-git-daemon - -you put this script: - - start on startup - stop on shutdown - exec /usr/bin/git daemon \ - --user=git --group=git \ - --reuseaddr \ - --base-path=/opt/git/ \ - /opt/git/ - respawn - -For security reasons, it is strongly encouraged to have this daemon run as a user with read-only permissions to the repositories — you can easily do this by creating a new user 'git-ro' and running the daemon as them. For the sake of simplicity we’ll simply run it as the same 'git' user that Gitosis is running as. - -When you restart your machine, your Git daemon will start automatically and respawn if it goes down. To get it running without having to reboot, you can run this: - - initctl start local-git-daemon - -On other systems, you may want to use `xinetd`, a script in your `sysvinit` system, or something else — as long as you get that command daemonized and watched somehow. - -Next, you have to tell your Gitosis server which repositories to allow unauthenticated Git server-based access to. If you add a section for each repository, you can specify the ones from which you want your Git daemon to allow reading. If you want to allow Git protocol access for your iphone project, you add this to the end of the `gitosis.conf` file: - - [repo iphone_project] - daemon = yes - -When that is committed and pushed up, your running daemon should start serving requests for the project to anyone who has access to port 9418 on your server. - -If you decide not to use Gitosis, but you want to set up a Git daemon, you’ll have to run this on each project you want the Git daemon to serve: - - $ cd /path/to/project.git - $ touch git-daemon-export-ok - -The presence of that file tells Git that it’s OK to serve this project without authentication. - -Gitosis can also control which projects GitWeb shows. First, you need to add something like the following to the `/etc/gitweb.conf` file: - - $projects_list = "/home/git/gitosis/projects.list"; - $projectroot = "/home/git/repositories"; - $export_ok = "git-daemon-export-ok"; - @git_base_url_list = ('git://gitserver'); - -You can control which projects GitWeb lets users browse by adding or removing a `gitweb` setting in the Gitosis configuration file. For instance, if you want the iphone project to show up on GitWeb, you make the `repo` setting look like this: - - [repo iphone_project] - daemon = yes - gitweb = yes - -Now, if you commit and push the project, GitWeb will automatically start showing your iphone project. - -=== Hosted Git +=== Other Hosting Options If you don’t want to go through all of the work involved in setting up your own Git server, you have several options for hosting your Git projects on an external dedicated hosting site. Doing so offers a number of advantages: a hosting site is generally quick to set up and easy to start projects on, and no server maintenance or monitoring is involved. Even if you set up and run your own server internally, you may still want to use a public hosting site for your open source code — it’s generally easier for the open source community to find and help you with. @@ -758,114 +614,6 @@ Because we can’t cover all of them, and because I happen to work at one of the GitHub is by far the largest open source Git hosting site and it’s also one of the very few that offers both public and private hosting options so you can keep your open source and private commercial code in the same place. In fact, we used GitHub to privately collaborate on this book. -==== GitHub - -GitHub is slightly different than most code-hosting sites in the way that it namespaces projects. Instead of being primarily based on the project, GitHub is user centric. That means when I host my `grit` project on GitHub, you won’t find it at `github.com/grit` but instead at `github.com/schacon/grit`. There is no canonical version of any project, which allows a project to move from one user to another seamlessly if the first author abandons the project. - -GitHub is also a commercial company that charges for accounts that maintain private repositories, but anyone can quickly get a free account to host as many open source projects as they want. We’ll quickly go over how that is done. - -==== Setting Up a User Account - -The first thing you need to do is set up a free user account. If you visit the Pricing and Signup page at `http://github.com/plans` and click the "Sign Up" button on the Free account (see figure 4-2), you’re taken to the signup page. - -image::images/18333fig0402-tn.png[Figure 4-2. The GitHub plan page.] - -Here you must choose a username that isn’t yet taken in the system and enter an e-mail address that will be associated with the account and a password (see Figure 4-3). - -image::images/18333fig0403-tn.png[Figure 4-3. The GitHub user signup form.] - -If you have it available, this is a good time to add your public SSH key as well. We covered how to generate a new key earlier, in the "Simple Setups" section. Take the contents of the public key of that pair, and paste it into the SSH Public Key text box. Clicking the "explain ssh keys" link takes you to detailed instructions on how to do so on all major operating systems. -Clicking the "I agree, sign me up" button takes you to your new user dashboard (see Figure 4-4). - -image::images/18333fig0404-tn.png[Figure 4-4. The GitHub user dashboard.] - -Next you can create a new repository. - -==== Creating a New Repository - -Start by clicking the "create a new one" link next to Your Repositories on the user dashboard. You’re taken to the Create a New Repository form (see Figure 4-5). - -image::images/18333fig0405-tn.png[Figure 4-5. Creating a new repository on GitHub.] - -All you really have to do is provide a project name, but you can also add a description. When that is done, click the "Create Repository" button. Now you have a new repository on GitHub (see Figure 4-6). - -image::images/18333fig0406-tn.png[Figure 4-6. GitHub project header information.] - -Since you have no code there yet, GitHub will show you instructions for how create a brand-new project, push an existing Git project up, or import a project from a public Subversion repository (see Figure 4-7). - -image::images/18333fig0407-tn.png[Figure 4-7. Instructions for a new repository.] - -These instructions are similar to what we’ve already gone over. To initialize a project if it isn’t already a Git project, you use - - $ git init - $ git add . - $ git commit -m 'initial commit' - -When you have a Git repository locally, add GitHub as a remote and push up your master branch: - - $ git remote add origin git@github.com:testinguser/iphone_project.git - $ git push origin master - -Now your project is hosted on GitHub, and you can give the URL to anyone you want to share your project with. In this case, it’s `http://github.com/testinguser/iphone_project`. You can also see from the header on each of your project’s pages that you have two Git URLs (see Figure 4-8). - -image::images/18333fig0408-tn.png[Figure 4-8. Project header with a public URL and a private URL.] - -The Public Clone URL is a public, read-only Git URL over which anyone can clone the project. Feel free to give out that URL and post it on your web site or what have you. - -The Your Clone URL is a read/write SSH-based URL that you can read or write over only if you connect with the SSH private key associated with the public key you uploaded for your user. When other users visit this project page, they won’t see that URL—only the public one. - -==== Importing from Subversion - -If you have an existing public Subversion project that you want to import into Git, GitHub can often do that for you. At the bottom of the instructions page is a link to a Subversion import. If you click it, you see a form with information about the import process and a text box where you can paste in the URL of your public Subversion project (see Figure 4-9). - -image::images/18333fig0409-tn.png[Figure 4-9. Subversion importing interface.] - -If your project is very large, nonstandard, or private, this process probably won’t work for you. In Chapter 7, you’ll learn how to do more complicated manual project imports. - -==== Adding Collaborators - -Let’s add the rest of the team. If John, Josie, and Jessica all sign up for accounts on GitHub, and you want to give them push access to your repository, you can add them to your project as collaborators. Doing so will allow pushes from their public keys to work. - -Click the "edit" button in the project header or the Admin tab at the top of the project to reach the Admin page of your GitHub project (see Figure 4-10). - -image::images/18333fig0410-tn.png[Figure 4-10. GitHub administration page.] - -To give another user write access to your project, click the “Add another collaborator” link. A new text box appears, into which you can type a username. As you type, a helper pops up, showing you possible username matches. When you find the correct user, click the Add button to add that user as a collaborator on your project (see Figure 4-11). - -image::images/18333fig0411-tn.png[Figure 4-11. Adding a collaborator to your project.] - -When you’re finished adding collaborators, you should see a list of them in the Repository Collaborators box (see Figure 4-12). - -image::images/18333fig0412-tn.png[Figure 4-12. A list of collaborators on your project.] - -If you need to revoke access to individuals, you can click the "revoke" link, and their push access will be removed. For future projects, you can also copy collaborator groups by copying the permissions of an existing project. - -==== Your Project - -After you push your project up or have it imported from Subversion, you have a main project page that looks something like Figure 4-13. - -image::images/18333fig0413-tn.png[Figure 4-13. A GitHub main project page.] - -When people visit your project, they see this page. It contains tabs to different aspects of your projects. The Commits tab shows a list of commits in reverse chronological order, similar to the output of the `git log` command. The Network tab shows all the people who have forked your project and contributed back. The Downloads tab allows you to upload project binaries and link to tarballs and zipped versions of any tagged points in your project. The Wiki tab provides a wiki where you can write documentation or other information about your project. The Graphs tab has some contribution visualizations and statistics about your project. The main Source tab that you land on shows your project’s main directory listing and automatically renders the README file below it if you have one. This tab also shows a box with the latest commit information. - -==== Forking Projects - -If you want to contribute to an existing project to which you don’t have push access, GitHub encourages forking the project. When you land on a project page that looks interesting and you want to hack on it a bit, you can click the "fork" button in the project header to have GitHub copy that project to your user so you can push to it. - -This way, projects don’t have to worry about adding users as collaborators to give them push access. People can fork a project and push to it, and the main project maintainer can pull in those changes by adding them as remotes and merging in their work. - -To fork a project, visit the project page (in this case, mojombo/chronic) and click the "fork" button in the header (see Figure 4-14). - -image::images/18333fig0414-tn.png[Figure 4-14. Get a writable copy of any repository by clicking the "fork" button.] - -After a few seconds, you’re taken to your new project page, which indicates that this project is a fork of another one (see Figure 4-15). - -image::images/18333fig0415-tn.png[Figure 4-15. Your fork of a project.] - -==== GitHub Summary - -That’s all we’ll cover about GitHub, but it’s important to note how quickly you can do all this. You can create an account, add a new project, and push to it in a matter of minutes. If your project is open source, you also get a huge community of developers who now have visibility into your project and may well fork it and help contribute to it. At the very least, this may be a way to get up and running with Git and try it out quickly. - === Summary You have several options to get a remote Git repository up and running so that you can collaborate with others or share your work. diff --git a/en/book/06-github/chapter6.asc b/en/book/06-github/chapter6.asc new file mode 100644 index 000000000..79ae69b6c --- /dev/null +++ b/en/book/06-github/chapter6.asc @@ -0,0 +1,107 @@ +== GitHub + +GitHub is slightly different than most code-hosting sites in the way that it namespaces projects. Instead of being primarily based on the project, GitHub is user centric. That means when I host my `grit` project on GitHub, you won’t find it at `github.com/grit` but instead at `github.com/schacon/grit`. There is no canonical version of any project, which allows a project to move from one user to another seamlessly if the first author abandons the project. + +GitHub is also a commercial company that charges for accounts that maintain private repositories, but anyone can quickly get a free account to host as many open source projects as they want. We’ll quickly go over how that is done. + +=== Setting Up a User Account + +The first thing you need to do is set up a free user account. If you visit the Pricing and Signup page at `http://github.com/plans` and click the "Sign Up" button on the Free account (see figure 4-2), you’re taken to the signup page. + +image::images/18333fig0402-tn.png[Figure 4-2. The GitHub plan page.] + +Here you must choose a username that isn’t yet taken in the system and enter an e-mail address that will be associated with the account and a password (see Figure 4-3). + +image::images/18333fig0403-tn.png[Figure 4-3. The GitHub user signup form.] + +If you have it available, this is a good time to add your public SSH key as well. We covered how to generate a new key earlier, in the "Simple Setups" section. Take the contents of the public key of that pair, and paste it into the SSH Public Key text box. Clicking the "explain ssh keys" link takes you to detailed instructions on how to do so on all major operating systems. +Clicking the "I agree, sign me up" button takes you to your new user dashboard (see Figure 4-4). + +image::images/18333fig0404-tn.png[Figure 4-4. The GitHub user dashboard.] + +Next you can create a new repository. + +=== Creating a New Repository + +Start by clicking the "create a new one" link next to Your Repositories on the user dashboard. You’re taken to the Create a New Repository form (see Figure 4-5). + +image::images/18333fig0405-tn.png[Figure 4-5. Creating a new repository on GitHub.] + +All you really have to do is provide a project name, but you can also add a description. When that is done, click the "Create Repository" button. Now you have a new repository on GitHub (see Figure 4-6). + +image::images/18333fig0406-tn.png[Figure 4-6. GitHub project header information.] + +Since you have no code there yet, GitHub will show you instructions for how create a brand-new project, push an existing Git project up, or import a project from a public Subversion repository (see Figure 4-7). + +image::images/18333fig0407-tn.png[Figure 4-7. Instructions for a new repository.] + +These instructions are similar to what we’ve already gone over. To initialize a project if it isn’t already a Git project, you use + + $ git init + $ git add . + $ git commit -m 'initial commit' + +When you have a Git repository locally, add GitHub as a remote and push up your master branch: + + $ git remote add origin git@github.com:testinguser/iphone_project.git + $ git push origin master + +Now your project is hosted on GitHub, and you can give the URL to anyone you want to share your project with. In this case, it’s `http://github.com/testinguser/iphone_project`. You can also see from the header on each of your project’s pages that you have two Git URLs (see Figure 4-8). + +image::images/18333fig0408-tn.png[Figure 4-8. Project header with a public URL and a private URL.] + +The Public Clone URL is a public, read-only Git URL over which anyone can clone the project. Feel free to give out that URL and post it on your web site or what have you. + +The Your Clone URL is a read/write SSH-based URL that you can read or write over only if you connect with the SSH private key associated with the public key you uploaded for your user. When other users visit this project page, they won’t see that URL—only the public one. + +=== Importing from Subversion + +If you have an existing public Subversion project that you want to import into Git, GitHub can often do that for you. At the bottom of the instructions page is a link to a Subversion import. If you click it, you see a form with information about the import process and a text box where you can paste in the URL of your public Subversion project (see Figure 4-9). + +image::images/18333fig0409-tn.png[Figure 4-9. Subversion importing interface.] + +If your project is very large, nonstandard, or private, this process probably won’t work for you. In Chapter 7, you’ll learn how to do more complicated manual project imports. + +=== Adding Collaborators + +Let’s add the rest of the team. If John, Josie, and Jessica all sign up for accounts on GitHub, and you want to give them push access to your repository, you can add them to your project as collaborators. Doing so will allow pushes from their public keys to work. + +Click the "edit" button in the project header or the Admin tab at the top of the project to reach the Admin page of your GitHub project (see Figure 4-10). + +image::images/18333fig0410-tn.png[Figure 4-10. GitHub administration page.] + +To give another user write access to your project, click the “Add another collaborator” link. A new text box appears, into which you can type a username. As you type, a helper pops up, showing you possible username matches. When you find the correct user, click the Add button to add that user as a collaborator on your project (see Figure 4-11). + +image::images/18333fig0411-tn.png[Figure 4-11. Adding a collaborator to your project.] + +When you’re finished adding collaborators, you should see a list of them in the Repository Collaborators box (see Figure 4-12). + +image::images/18333fig0412-tn.png[Figure 4-12. A list of collaborators on your project.] + +If you need to revoke access to individuals, you can click the "revoke" link, and their push access will be removed. For future projects, you can also copy collaborator groups by copying the permissions of an existing project. + +=== Your Project + +After you push your project up or have it imported from Subversion, you have a main project page that looks something like Figure 4-13. + +image::images/18333fig0413-tn.png[Figure 4-13. A GitHub main project page.] + +When people visit your project, they see this page. It contains tabs to different aspects of your projects. The Commits tab shows a list of commits in reverse chronological order, similar to the output of the `git log` command. The Network tab shows all the people who have forked your project and contributed back. The Downloads tab allows you to upload project binaries and link to tarballs and zipped versions of any tagged points in your project. The Wiki tab provides a wiki where you can write documentation or other information about your project. The Graphs tab has some contribution visualizations and statistics about your project. The main Source tab that you land on shows your project’s main directory listing and automatically renders the README file below it if you have one. This tab also shows a box with the latest commit information. + +=== Forking Projects + +If you want to contribute to an existing project to which you don’t have push access, GitHub encourages forking the project. When you land on a project page that looks interesting and you want to hack on it a bit, you can click the "fork" button in the project header to have GitHub copy that project to your user so you can push to it. + +This way, projects don’t have to worry about adding users as collaborators to give them push access. People can fork a project and push to it, and the main project maintainer can pull in those changes by adding them as remotes and merging in their work. + +To fork a project, visit the project page (in this case, mojombo/chronic) and click the "fork" button in the header (see Figure 4-14). + +image::images/18333fig0414-tn.png[Figure 4-14. Get a writable copy of any repository by clicking the "fork" button.] + +After a few seconds, you’re taken to your new project page, which indicates that this project is a fork of another one (see Figure 4-15). + +image::images/18333fig0415-tn.png[Figure 4-15. Your fork of a project.] + +=== GitHub Summary + +That’s all we’ll cover about GitHub, but it’s important to note how quickly you can do all this. You can create an account, add a new project, and push to it in a matter of minutes. If your project is open source, you also get a huge community of developers who now have visibility into your project and may well fork it and help contribute to it. At the very least, this may be a way to get up and running with Git and try it out quickly. diff --git a/en/book/06-git-tools/01-chapter6.markdown b/en/book/07-git-tools/01-chapter6.markdown similarity index 100% rename from en/book/06-git-tools/01-chapter6.markdown rename to en/book/07-git-tools/01-chapter6.markdown diff --git a/en/book/06-git-tools/chapter6.asc b/en/book/07-git-tools/chapter7.asc similarity index 99% rename from en/book/06-git-tools/chapter6.asc rename to en/book/07-git-tools/chapter7.asc index 3148d9bfe..28894f82b 100644 --- a/en/book/06-git-tools/chapter6.asc +++ b/en/book/07-git-tools/chapter7.asc @@ -525,6 +525,8 @@ If you stash some work, leave it there for a while, and continue on the branch f This is a nice shortcut to recover stashed work easily and work on it in a new branch. +=== Searching + === Rewriting History Many times, when working with Git, you may want to revise your commit history for some reason. One of the great things about Git is that it allows you to make decisions at the last possible moment. You can decide what files go into which commits right before you commit with the staging area, you can decide that you didn’t mean to be working on something yet with the stash command, and you can rewrite commits that already happened so they look like they happened in a different way. This can involve changing the order of the commits, changing messages or modifying files in a commit, squashing together or splitting apart commits, or removing commits entirely — all before you share your work with others. @@ -1120,6 +1122,20 @@ Or, to compare what is in your `rack` subdirectory with what the `master` branch $ git diff-tree -p rack_remote/master +=== Notes + +=== Bundle + +=== Rerere + +=== History Hacks + +==== Grafts (?) + +==== Replace + +==== Shallow + === Summary You’ve seen a number of advanced tools that allow you to manipulate your commits and staging area more precisely. When you notice issues, you should be able to easily figure out what commit introduced them, when, and by whom. If you want to use subprojects in your project, you’ve learned a few ways to accommodate those needs. At this point, you should be able to do most of the things in Git that you’ll need on the command line day to day and feel comfortable doing so. diff --git a/en/book/07-customizing-git/01-chapter7.html b/en/book/08-customizing-git/01-chapter7.html similarity index 100% rename from en/book/07-customizing-git/01-chapter7.html rename to en/book/08-customizing-git/01-chapter7.html diff --git a/en/book/07-customizing-git/chapter7.asc b/en/book/08-customizing-git/chapter8.asc similarity index 100% rename from en/book/07-customizing-git/chapter7.asc rename to en/book/08-customizing-git/chapter8.asc diff --git a/en/book/08-git-and-other-scms/01-chapter8.markdown b/en/book/09-git-and-other-scms/01-chapter8.markdown similarity index 100% rename from en/book/08-git-and-other-scms/01-chapter8.markdown rename to en/book/09-git-and-other-scms/01-chapter8.markdown diff --git a/en/book/08-git-and-other-scms/chapter8.asc b/en/book/09-git-and-other-scms/chapter9.asc similarity index 99% rename from en/book/08-git-and-other-scms/chapter8.asc rename to en/book/09-git-and-other-scms/chapter9.asc index 55b23c1cb..674bd5438 100644 --- a/en/book/08-git-and-other-scms/chapter8.asc +++ b/en/book/09-git-and-other-scms/chapter9.asc @@ -343,6 +343,12 @@ The `git svn` tools are useful if you’re stuck with a Subversion server for no If you follow those guidelines, working with a Subversion server can be more bearable. However, if it’s possible to move to a real Git server, doing so can gain your team a lot more. +=== Git and Mercurial + +=== Git and Perforce + +=== Git and TFS + === Migrating to Git If you have an existing codebase in another VCS but you’ve decided to start using Git, you must migrate your project one way or another. This section goes over some importers that are included with Git for common systems and then demonstrates how to develop your own custom importer. @@ -415,6 +421,8 @@ Because you want all your branches and tags to go up, you can now run this: All your branches and tags should be on your new Git server in a nice, clean import. +==== Mercurial + ==== Perforce The next system you’ll look at importing from is Perforce. A Perforce importer is also distributed with Git, but only in the `contrib` section of the source code — it isn’t available by default like `git svn`. To run it, you must get the Git source code, which you can download from git.kernel.org: @@ -484,6 +492,8 @@ If you run `git log`, you can see that all the SHA-1 checksums for the commits h Your import is ready to push up to your new Git server. +==== TFS + ==== A Custom Importer If your system isn’t Subversion or Perforce, you should look for an importer online — quality importers are available for CVS, Clear Case, Visual Source Safe, even a directory of archives. If none of these tools works for you, you have a rarer tool, or you otherwise need a more custom importing process, you should use `git fast-import`. This command reads simple instructions from stdin to write specific Git data. It’s much easier to create Git objects this way than to run the raw Git commands or try to write the raw objects (see Chapter 9 for more information). This way, you can write an import script that reads the necessary information out of the system you’re importing from and prints straightforward instructions to stdout. You can then run this program and pipe its output through `git fast-import`. @@ -684,6 +694,8 @@ There you go — a nice, clean Git repository. It’s important to note that not You can do a lot more with the `fast-import` tool — handle different modes, binary data, multiple branches and merging, tags, progress indicators, and more. A number of examples of more complex scenarios are available in the `contrib/fast-import` directory of the Git source code; one of the better ones is the `git-p4` script I just covered. +=== A Custom Credential Cache + === Summary You should feel comfortable using Git with Subversion or importing nearly any existing repository into a new Git one without losing data. The next chapter will cover the raw internals of Git so you can craft every single byte, if need be. diff --git a/en/book/10-git-in-other-environments/chapter10.asc b/en/book/10-git-in-other-environments/chapter10.asc new file mode 100644 index 000000000..9c809222a --- /dev/null +++ b/en/book/10-git-in-other-environments/chapter10.asc @@ -0,0 +1,31 @@ +== Git in Other Environments + +=== Graphical Interfaces + +==== gitk & git-gui + +==== GitHub for Windows/Mac + +==== Other GUIs + +=== Git in Visual Studio + +=== Git in Eclipse + +=== Git in Bash + +=== Git in Zsh + +=== Git in Powershell + +=== Git in Your Application + +==== libgit2 + +==== libgit2sharp + +==== objective-git + +==== rugged + +==== pygit2 diff --git a/en/book/09-git-internals/01-chapter9.markdown b/en/book/11-git-internals/01-chapter9.markdown similarity index 100% rename from en/book/09-git-internals/01-chapter9.markdown rename to en/book/11-git-internals/01-chapter9.markdown diff --git a/en/book/09-git-internals/chapter9.asc b/en/book/11-git-internals/chapter11.asc similarity index 99% rename from en/book/09-git-internals/chapter9.asc rename to en/book/11-git-internals/chapter11.asc index cf90891ce..a00fb7500 100644 --- a/en/book/09-git-internals/chapter9.asc +++ b/en/book/11-git-internals/chapter11.asc @@ -966,6 +966,8 @@ Let’s see how much space you saved. The packed repository size is down to 7K, which is much better than 2MB. You can see from the size value that the big object is still in your loose objects, so it’s not gone; but it won’t be transferred on a push or subsequent clone, which is what is important. If you really wanted to, you could remove the object completely by running `git prune --expire`. +=== Environment Variables + === Summary You should have a pretty good understanding of what Git does in the background and, to some degree, how it’s implemented. This chapter has covered a number of plumbing commands — commands that are lower level and simpler than the porcelain commands you’ve learned about in the rest of the book. Understanding how Git works at a lower level should make it easier to understand why it’s doing what it’s doing and also to write your own tools and helping scripts to make your specific workflow work for you. diff --git a/en/book/book.asc b/en/book/book.asc index ff002a77d..9be461d9d 100644 --- a/en/book/book.asc +++ b/en/book/book.asc @@ -24,10 +24,14 @@ include::04-git-server/chapter4.asc[] include::05-distributed-git/chapter5.asc[] -include::06-git-tools/chapter6.asc[] +include::06-github/chapter6.asc[] -include::07-customizing-git/chapter7.asc[] +include::07-git-tools/chapter7.asc[] -include::08-git-and-other-scms/chapter8.asc[] +include::08-customizing-git/chapter8.asc[] -include::09-git-internals/chapter9.asc[] +include::09-git-and-other-scms/chapter9.asc[] + +include::10-git-in-other-environments/chapter10.asc[] + +include::11-git-internals/chapter11.asc[]