diff --git a/docs/protocol.txt b/docs/protocol.txt index ed694b9e..2a04820f 100644 --- a/docs/protocol.txt +++ b/docs/protocol.txt @@ -1,65 +1,65 @@ .. _protocol: =================== Git Server Protocol =================== Transport ========= The Git protocol operates over pipes or TCP/IP. When a client connects over TCP/IP, it sends a header that tells the server which program to run and what parameters to use. When invoked over SSH, git will run a program with the parameters as command line arguments. Protocols ========= Basics ------ Git communicates with a server by piping data between a local program and a remote program. A common way of sending a unit of information is a pkt_line. This is a 4 byte size as human encoded hex (i.e. totally underusing the 4 bytes...) that tells you the size of the payload, followed by the payload. The size includes the 4 byes used by the size itself. 0009ABCD\n Git can also multiplex data using the sideband. As well as 4 bytes size, there would be a 1 byte channel number. This is in binary, so ``1`` will be ``\x01``. Typically Git will piggyback a list of capabilities on the first pkt_line it sends. It will also look for capabilities in the first pkt_like it receives. Git will degrade as much as possible when encountering a server or client with differing capabilities. git-upload-pack --------------- git-upload pack is used by git-ls-remote, git-clone, git-fetch and git-pull. And i'm sure others. Typically a client will connect a local git-fetch-pack to a remote git-upload-pack. Capabilities for this protocol include multi_ack, thin-pack, ofs-delta, sideband and sideband-64k A thin pack can reference objects not in the current pack. The server tells the client what refs it has. The client states which of those SHA1's it would like. It then starts to report which SHA1's it has. The server ACKs these allowing the client to work out when to stop sending SHA1's. This saves a lot of transfer because the client can make decisions like "well if it -has this SHA, then it has all its parents so i dont need to care about those". +has this SHA, then it has all its parents so I don't need to care about those". When the client stops sending shas, the server can work out an optimal pack and then send it to the client. git-receive-pack ---------------- git-receive-pack is used by git push. Typically a client connects a local git-send-pack to a remote git-receive-pack. Capabilities include report-status and delete-ref. diff --git a/docs/tutorial/file-format.txt b/docs/tutorial/file-format.txt index d003efce..c1f53df1 100644 --- a/docs/tutorial/file-format.txt +++ b/docs/tutorial/file-format.txt @@ -1,99 +1,99 @@ Git File format =============== For a better understanding of Dulwich, we'll start by explaining most of the Git secrets. Open the ".git" folder of any Git-managed repository. You'll find folders like "branches", "hooks"... We're only interested in "objects" here. Open it. You'll mostly see 2 hex-digits folders. Git identifies content by its SHA-1 digest. The 2 hex-digits plus the 38 hex-digits of files inside these folders form the 40 characters (or 20 bytes) id of Git objects you'll manage in Dulwich. We'll first study the three main objects: - The Commit; - The Tree; - The Blob. The Commit ---------- You're used to generate commits using Git. You have set up your name and e-mail, and you know how to see the history using ``git log``. A commit file looks like this:: commit tree parent [parent if several parents from merges] author committer -But where are the changes you commited? The commit contains a reference to a +But where are the changes you committed? The commit contains a reference to a tree. The Tree -------- A tree is a collection of file information, the state of a single directory at a given point in time. A tree file looks like this:: tree ... And repeats for every file in the tree. Note that the SHA-1 digest is in binary form here. The file mode is like the octal argument you could give to the ``chmod`` command. Except it is in extended form to tell regular files from directories and other types. We now know how our files are referenced but we haven't found their actual content yet. That's where the reference to a blob comes in. The Blob -------- -A blob is simply the content of files you are versionning. +A blob is simply the content of files you are versioning. A blob file looks like this:: blob If you change a single line, another blob will be generated by Git at commit time. This is how Git can fastly checkout any version in time. On the opposite, several identical files with different filenames generate only one blob. That's mostly how renames are so cheap and efficient in Git. Dulwich Objects --------------- Dulwich implements these three objects with an API to easily access the information you need, while abstracting some more secrets Git is using to accelerate operations and reduce space. More About Git formats ---------------------- These three objects make up most of the contents of a Git repository and are used for the history. They can either appear as simple files on disk (one file per object) or in a ``pack`` file, which is a container for a number of these objects. The is also an index of the current state of the working copy in the repository as well as files to track the existing branches and tags. For a more detailed explanation of object formats and SHA-1 digests, see: http://www-cs-students.stanford.edu/~blynn/gitmagic/ch08.html Just note that recent versions of Git compress object files using zlib. diff --git a/docs/tutorial/object-store.txt b/docs/tutorial/object-store.txt index 98e63719..c246ce2a 100644 --- a/docs/tutorial/object-store.txt +++ b/docs/tutorial/object-store.txt @@ -1,187 +1,187 @@ .. _tutorial-object-store: The object store ================ The objects are stored in the ``object store`` of the repository. >>> from dulwich.repo import Repo >>> repo = Repo.init("myrepo", mkdir=True) Initial commit -------------- When you use Git, you generally add or modify content. As our repository is empty for now, we'll start by adding a new file:: >>> from dulwich.objects import Blob >>> blob = Blob.from_string(b"My file content\n") >>> print(blob.id.decode('ascii')) c55063a4d5d37aa1af2b2dad3a70aa34dae54dc6 Of course you could create a blob from an existing file using ``from_file`` instead. -As said in the introduction, file content is separed from file name. Let's +As said in the introduction, file content is separated from file name. Let's give this content a name:: >>> from dulwich.objects import Tree >>> tree = Tree() >>> tree.add(b"spam", 0o100644, blob.id) Note that "0o100644" is the octal form for a regular file with common permissions. You can hardcode them or you can use the ``stat`` module. The tree state of our repository still needs to be placed in time. That's the job of the commit:: >>> from dulwich.objects import Commit, parse_timezone >>> from time import time >>> commit = Commit() >>> commit.tree = tree.id >>> author = b"Your Name " >>> commit.author = commit.committer = author >>> commit.commit_time = commit.author_time = int(time()) >>> tz = parse_timezone(b'-0200')[0] >>> commit.commit_timezone = commit.author_timezone = tz >>> commit.encoding = b"UTF-8" >>> commit.message = b"Initial commit" Note that the initial commit has no parents. At this point, the repository is still empty because all operations happen in memory. Let's "commit" it. >>> object_store = repo.object_store >>> object_store.add_object(blob) Now the ".git/objects" folder contains a first SHA-1 file. Let's continue saving the changes:: >>> object_store.add_object(tree) >>> object_store.add_object(commit) Now the physical repository contains three objects but still has no branch. Let's create the master branch like Git would:: >>> repo.refs[b'refs/heads/master'] = commit.id The master branch now has a commit where to start. When we commit to master, we are also moving HEAD, which is Git's currently checked out branch: >>> head = repo.refs[b'HEAD'] >>> head == commit.id True >>> head == repo.refs[b'refs/heads/master'] True How did that work? As it turns out, HEAD is a special kind of ref called a symbolic ref, and it points at master. Most functions on the refs container work transparently with symbolic refs, but we can also take a peek inside HEAD: >>> import sys >>> print(repo.refs.read_ref(b'HEAD').decode(sys.getfilesystemencoding())) ref: refs/heads/master Normally, you won't need to use read_ref. If you want to change what ref HEAD points to, in order to check out another branch, just use set_symbolic_ref. Now our repository is officially tracking a branch named "master" referring to a single commit. Playing again with Git ---------------------- At this point you can come back to the shell, go into the "myrepo" folder and type ``git status`` to let Git confirm that this is a regular repository on branch "master". Git will tell you that the file "spam" is deleted, which is normal because Git is comparing the repository state with the current working copy. And we have absolutely no working copy using Dulwich because we don't need it at all! You can checkout the last state using ``git checkout -f``. The force flag will prevent Git from complaining that there are uncommitted changes in the working copy. The file ``spam`` appears and with no surprise contains the same bytes as the blob:: $ cat spam My file content Changing a File and Committing it --------------------------------- Now we have a first commit, the next one will show a difference. As seen in the introduction, it's about making a path in a tree point to a new blob. The old blob will remain to compute the diff. The tree is altered and the new commit'task is to point to this new version. Let's first build the blob:: >>> from dulwich.objects import Blob >>> spam = Blob.from_string(b"My new file content\n") >>> print(spam.id.decode('ascii')) 16ee2682887a962f854ebd25a61db16ef4efe49f An alternative is to alter the previously constructed blob object:: >>> blob.data = b"My new file content\n" >>> print(blob.id.decode('ascii')) 16ee2682887a962f854ebd25a61db16ef4efe49f In any case, update the blob id known as "spam". You also have the opportunity of changing its mode:: >>> tree[b"spam"] = (0o100644, spam.id) Now let's record the change:: >>> from dulwich.objects import Commit >>> from time import time >>> c2 = Commit() >>> c2.tree = tree.id >>> c2.parents = [commit.id] >>> c2.author = c2.committer = b"John Doe " >>> c2.commit_time = c2.author_time = int(time()) >>> c2.commit_timezone = c2.author_timezone = 0 >>> c2.encoding = b"UTF-8" >>> c2.message = b'Changing "spam"' In this new commit we record the changed tree id, and most important, the previous commit as the parent. Parents are actually a list because a commit may happen to have several parents after merging branches. Let's put the objects in the object store:: >>> repo.object_store.add_object(spam) >>> repo.object_store.add_object(tree) >>> repo.object_store.add_object(c2) You can already ask git to introspect this commit using ``git show`` and the value of ``c2.id`` as an argument. You'll see the difference will the previous blob recorded as "spam". The diff between the previous head and the new one can be printed using write_tree_diff:: >>> from dulwich.patch import write_tree_diff >>> import sys >>> write_tree_diff(sys.stdout, repo.object_store, commit.tree, tree.id) diff --git a/spam b/spam index c55063a..16ee268 100644 --- a/spam +++ b/spam @@ -1,1 +1,1 @@ -My file content +My new file content You won't see it using git log because the head is still the previous commit. It's easy to remedy:: >>> repo.refs[b'refs/heads/master'] = c2.id Now all git tools will work as expected. diff --git a/docs/tutorial/repo.txt b/docs/tutorial/repo.txt index bef62a36..72840b0a 100644 --- a/docs/tutorial/repo.txt +++ b/docs/tutorial/repo.txt @@ -1,101 +1,101 @@ .. _tutorial-repo: The repository ============== After this introduction, let's start directly with code:: >>> from dulwich.repo import Repo The access to a repository is through the Repo object. You can open an existing repository or you can create a new one. There are two types of Git repositories: Regular Repositories -- They are the ones you create using ``git init`` and you daily use. They contain a ``.git`` folder. Bare Repositories -- There is no ".git" folder. The top-level folder contains itself the "branches", "hooks"... folders. These are used for published repositories (mirrors). They do not have a working tree. Creating a repository --------------------- Let's create a folder and turn it into a repository, like ``git init`` would:: >>> from os import mkdir >>> import sys >>> mkdir("myrepo") >>> repo = Repo.init("myrepo") >>> repo -You can already look a the structure of the "myrepo/.git" folder, though it +You can already look at the structure of the "myrepo/.git" folder, though it is mostly empty for now. Opening an existing repository ------------------------------ To reopen an existing repository, simply pass its path to the constructor of ``Repo``:: >>> repo = Repo("myrepo") >>> repo Opening the index ----------------- The index is used as a staging area. Once you do a commit, the files tracked in the index will be recorded as the contents of the new commit. As mentioned earlier, only non-bare repositories have a working tree, so only non-bare repositories will have an index, too. To open the index, simply call:: >>> index = repo.open_index() >>> print(index.path.decode(sys.getfilesystemencoding())) myrepo/.git/index Since the repository was just created, the index will be empty:: >>> list(index) [] Staging new files ----------------- The repository allows "staging" files. Only files can be staged - directories aren't tracked explicitly by git. Let's create a simple text file and stage it:: >>> f = open('myrepo/foo', 'wb') >>> _ = f.write(b"monty") >>> f.close() >>> repo.stage([b"foo"]) It will now show up in the index:: >>> print(",".join([f.decode(sys.getfilesystemencoding()) for f in repo.open_index()])) foo Creating new commits -------------------- Now that we have staged a change, we can commit it. The easiest way to do this is by using ``Repo.do_commit``. It is also possible to manipulate the lower-level objects involved in this, but we'll leave that for a separate chapter of the tutorial. To create a simple commit on the current branch, it is only necessary to specify the message. The committer and author will be retrieved from the repository configuration or global configuration if they are not specified:: >>> commit_id = repo.do_commit( ... b"The first commit", committer=b"Jelmer Vernooij ") ``do_commit`` returns the SHA1 of the commit. Since the commit was to the default branch, the repository's head will now be set to that commit:: >>> repo.head() == commit_id True