docs/tutorial/repo.txt

   1 .. _tutorial-repo:
   2
   3 The repository
   4 ==============
   5
   6 After this introduction, let's start directly with code::
   7
   8   >>> from dulwich.repo import Repo
   9
  10 The access to a repository is through the Repo object. You can open an
  11 existing repository or you can create a new one. There are two types of Git
  12 repositories:
  13
  14   Regular Repositories -- They are the ones you create using ``git init`` and
  15   you daily use. They contain a ``.git`` folder.
  16
  17   Bare Repositories -- There is no ".git" folder. The top-level folder
  18   contains itself the "branches", "hooks"... folders. These are used for
  19   published repositories (mirrors). They do not have a working tree.
  20
  21 Creating a repository
  22 ---------------------
  23
  24 Let's create a folder and turn it into a repository, like ``git init`` would::
  25
  26   >>> from os import mkdir
  27   >>> import sys
  28   >>> mkdir("myrepo")
  29   >>> repo = Repo.init("myrepo")
  30   >>> repo
  31   <Repo at 'myrepo'>
  32
  33 You can already look at the structure of the "myrepo/.git" folder, though it
  34 is mostly empty for now.
  35
  36 Opening an existing repository
  37 ------------------------------
  38
  39 To reopen an existing repository, simply pass its path to the constructor
  40 of ``Repo``::
  41
  42     >>> repo = Repo("myrepo")
  43     >>> repo
  44     <Repo at 'myrepo'>
  45
  46 Opening the index
  47 -----------------
  48
  49 The index is used as a staging area. Once you do a commit,
  50 the files tracked in the index will be recorded as the contents of the new
  51 commit. As mentioned earlier, only non-bare repositories have a working tree,
  52 so only non-bare repositories will have an index, too. To open the index, simply
  53 call::
  54
  55     >>> index = repo.open_index()
  56     >>> print(index.path.decode(sys.getfilesystemencoding()))
  57     myrepo/.git/index
  58
  59 Since the repository was just created, the index will be empty::
  60
  61     >>> list(index)
  62     []
  63
  64 Staging new files
  65 -----------------
  66
  67 The repository allows "staging" files. Only files can be staged - directories
  68 aren't tracked explicitly by git. Let's create a simple text file and stage it::
  69
  70     >>> f = open('myrepo/foo', 'wb')
  71     >>> _ = f.write(b"monty")
  72     >>> f.close()
  73
  74     >>> repo.stage([b"foo"])
  75
  76 It will now show up in the index::
  77
  78     >>> print(",".join([f.decode(sys.getfilesystemencoding()) for f in repo.open_index()]))
  79     foo
  80
  81
  82 Creating new commits
  83 --------------------
  84
  85 Now that we have staged a change, we can commit it. The easiest way to
  86 do this is by using ``Repo.do_commit``. It is also possible to manipulate
  87 the lower-level objects involved in this, but we'll leave that for a
  88 separate chapter of the tutorial.
  89
  90 To create a simple commit on the current branch, it is only necessary
  91 to specify the message. The committer and author will be retrieved from the
  92 repository configuration or global configuration if they are not specified::
  93
  94     >>> commit_id = repo.do_commit(
  95     ...     b"The first commit", committer=b"Jelmer Vernooij <jelmer@samba.org>")
  96
  97 ``do_commit`` returns the SHA1 of the commit. Since the commit was to the
  98 default branch, the repository's head will now be set to that commit::
  99
 100     >>> repo.head() == commit_id
 101     True