Importing an already exsting &debian; package into a &git; repository is as easy as: &gbp-import-dsc; package_0.1-1.dsc This will create a new &git; repository named after the imported package, put the upstream sources onto the upstream-branch and the &debian; patch on the debian-branch. In case of a debian native package only the debian-branch is being used. You can specify alternative branch names via the --upstream-branch and --debian-branch options or via the upstream-branch and debian-branch options in the configuration file. If you want to be able to exactly recreate the original tarball (orig.tar.gz) from &git; you should also specify the --pristine-tar option. This is recommended. If you want to import further versions you can change into your shiny new &git; repository and just continue with the same command: cd package/ &gbp-import-dsc; package_0.1-2.dsc &gbp-import-dsc; package_0.1-3.dsc &gbp-import-dsc; package_0.2-1.dsc Or you can import all versions at once using &gbp-import-dscs;: &gbp-import-dscs; /path/to/history/package_*.dsc This will create a &git; repository if necessary and import all versions sorted by version number. Change into your &git; repository (which can be empty), make sure it has all local modifications committed and run either of: &gbp-import-orig; /path/to/package_0.2.orig.tar.gz &gbp-import-orig; /path/to/package_0.2.tar.bz2 &gbp-import-orig; /path/to/package-0.2/ This puts the upstream souces onto the upstream-branch and tags them accordingly (the default tag format is upstream/%(version)s). The result is then merged onto the debian-branch and a new &debian; changelog entry is created. You can again specify different branch names via the --upstream-branch and --debian-branch options. You can also filter out content you don't want imported: &gbp-import-orig; --filter='CVS/*' /path/to/package_0.2.orig.tar.gz The --filter option can be used multiple times for more complex filtering. If you expect a merge conflict you can delay the merge to the debian-branch via the --no-merge and pull in the changes from the upstream-branch later. If you want to be able to exactly recreate the original tarball (orig.tar.gz) from &git; you should also specify the --pristine-tar option. This is recommended. To customize the commit message used by &gbp-import-orig; use the --import-msg option. This string is a standard python format string, into which the version variable is interpolated. (i.e., use %(version)s in your message to get the imported upstream version). If the &git; repository wasn't created with &gbp-import-dsc; you have to tell &gbp-buildpackage; and friends where to find the upstream sources. If the upstream sources are already on a separate branch things are pretty simple. You can either rename that branch to the default upstream-branch name upstream with: &gitcmd; branch upstream theupstream-branch &gitcmd; branch -D theupstream-branch or you can tell &gbp-buildpackage; the name of the branch to use as upstream-branch: cat <<EOF > .git/gbp.conf [DEFAULT] # this is the upstream-branch: upstream-branch=theupstream-branch EOF If you then use &gbp-import-orig; to import new upstream sources, they will from now on end up on theupstream-branch and merged to the debian-branch. If you don't have an upstream branch but started your repository with only the upstream sources (not the &debian; patch) you can simply branch from that point. So use &gitkcmd; or &gitcmd;-log to locate the commit-id of that commit and create the upstream branch from there, e.g.: COMMIT_ID=`&gitcmd; log --pretty=oneline | tail -1 | awk '{ print $1 }'` &gitcmd; branch upstream $COMMIT_ID The important thing here is that the COMMIT_ID specifies a point on the master branch that carried only the upstream sources and not the &debian; modifications. The above example assumes that this was the first commit to that repository. There's currently no easy way to create the upstream-branch if you never had the upstream sources as a single commit. Using &gbp-import-orig; on such repositories might lead to unexpected merge results. In order to fix this you can prepend the upstream sources as a single commit to your tree using &git;'s grafts. Afterwards you can simply create a branch as explained above and &gbp-import-orig; will work as expected. Alternatively, if you are only importing source from original tarballs (for instance when converting from a Subversion repository where the mergeWithUpstream was set for svn-buildpackage), you can create an empty upstream branch with the following commands: git checkout --orphan upstream git rm -rf . git commit --allow-empty -m 'Initial upstream branch.' git checkout -f master With Git versions lower than 1.7.2.3, the commands are slightly more complicated: git symbolic-ref HEAD refs/heads/upstream git rm --cached -r . git commit --allow-empty -m 'Initial upstream branch.' git checkout -f master So far we assumed you already have a &debian; package to start with but what if you want to start a new package? First create an empty repository: mkdir package-0.1 cd package-0.1 git init Then you import the upstream sources, branch off the upstream-branch branch and add the &debian; files (e.g. via dh_make): &gbp-import-orig; -u 0.1 ../package-0.1.tar.gz dh_make That's it, you're done. If you want to publish you're new repository you can use &gbp-create-remote-repo;. If upstream already uses git for packaging there are several ways to handle packaging. Two of them will be described in a bit detail here: If upstream doesn't build upstream tarballs or you don't care about them the simplest way is to clone upstreams repository and create a separate packaging branch in there. In order to help &gbp-buildpackage; to find upstream tags you need to specify the format using the --git-upstream-tag comand line option or the the upstream-tag configuration variable. A common upstream format is to put a v in front of the version number. In this case the configuration option would look like: [git-buildpackage] upstream-tag = v%(version)s version will be replaced with the upstream version number as read from debian/changelog. If you're using &pristine-tar; you can make &gbp-buildpackage commit the generated tarball back to the pristine-tar branch by using the --git-pristine-tar-commit option. This will make sure others building your package can regenerate the tarball you generated for building the &debian; package. To not make any assumptions about &gbp;'s configuration the following steps have all options given in its long versions on the command line . You can add these to &gbp.conf; to save lots of typing. First we clone the upstream repository. To avoid any dis ambiguities between the &debian; packaging repository and the upstream repository we name the upstream repository ustream instead of the default origin. git clone --no-checkout -o upstream git://git.example.com/libgbp.git cd libgbp git checkout -b debian/sid v1.0 The above makes sure we have debian/sid for the &debian; packaging. We didn't create any upstream/* branches, they're not needed for the packaging and only need to be kept up to date. After adding the &debian; packaging we build the package. This assumes you're using &pristine-tar; and upstream uses a version number format as described above: gbp buildpackage --git-pristine-tar --git-pristine-tar-commit --git-upstream-tag='v%(version)s' --git-debian-branch=debian/sid When updating to a new upstream version we simply fetch from upstream and merge in the new tag. Afterwards we update the changelog and build the package: git fetch upstream git merge v1.1 gbp dch --debian-branch=debian/sid --snapshot --auto debian/ gbp buildpackage --git-ignore-new --git-pristine-tar --git-pristine-tar-commit --git-upstream-tag='v%(version)s' Note that the above &gbp-dch; call makes sure we only pickup changes in the debian/ directory. Since we told it to build a snapshot changelog entry and we didn't commit the changelog yet we need to tell &gbp-buildpackage; that the working directory is unclean via the --git-ignore-new. Once everything looks good commit the changelog and build a release version: gbp dch --release --auto --git-debian-branch=debian/sid git commit -m"Release 1.1-1" debian/changelog gbp buildpackage --git-upstream-tag='v%(version)s' --git-debian-branch=debian/sid If you want to share you're repository with others you can use &gbp-create-remote-repo; and &gbp-pull; as usual. If you want to track upstream's &git; but continue to import the upstream tarballs, e.g. to make sure the tarball uploaded to &debian; has the same checksum as upstream's you can use the --upstream-vcs-tag option when importing new tarballs with &gbp-import-orig;. Assuming you have the upstream source in your repository with a tag v0.0.1 you can use: &gbp-import-orig; --upstream-vcs-tag=v0.0.1 foo_0.0.1.orig.tar.gz to add upstream's tag as additional parent to the merge commit. See #664771 for more details. By default &gbp; uses one branch to keep the &debian; packaging called master and a branch to keep the upstream packaging called upstream. This layout is simple to get started but fails short if one needs to maintain several versions of the package at the same time. Therefore the following layout is recommended: debian/<release> the &debian; packaging for a release jessie, wheezy, sid or experimental. upstream/<release> the upstream sources for a release matching one of the above security/<release> security updates for a certain release backports/<release> backports to a certain release dfsg/<release> the dfsg clean upstream sources in case the cleanup is done via a &git; merge from upstream to this branch. In case &pristine-tar; is being used there will be a single pristine-tar branch that keeps all binary deltas.