From: Catalin Marinas Date: Tue, 16 Aug 2005 16:06:55 +0000 (+0100) Subject: README file update X-Git-Tag: v0.6~8 X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~mdw/git/stgit/commitdiff_plain/1ac02448539c5c8b11e552a8a383afe389427fbc?ds=sidebyside README file update This file is quite out of date and needs to be updated. Signed-off-by: Catalin Marinas --- diff --git a/README b/README index dfb6442..2f43e09 100644 --- a/README +++ b/README @@ -1,107 +1,242 @@ Stacked GIT ------------ +=========== StGIT is a Python application providing similar functionality to Quilt -(i.e. pushing/poping patches to a stack) on top of GIT. These -operations are performed using the GIT merge algorithms. +(i.e. pushing/popping patches to/from a stack) on top of GIT. These +operations are performed using GIT commands and the patches are stored +as GIT commit objects, allowing easy merging of the StGIT patches into +other repositories using standard GIT functionality. -Note that StGIT is not an SCM interface for GIT. Use the GIT commands -or some other tools like Cogito for this. +Note that StGIT is not an SCM interface on top of GIT and it expects a +previously initialised GIT repository (unless it is cloned using StGIT +directly). For standard SCM operations, either use plain GIT commands +or the Cogito tool but it is not recommended to mix them with the +StGIT commands. For the latest version see http://www.procode.org/stgit/ Basic Operations ----------------- +================ -For a full list of commands: +See the help on individual commands for the full set of options. + +Help +---- + + For a full list of commands: stg help -For help on individual commands: + For help on individual commands: stg (-h | --help) -To initialise a tree (the tree must have been previously initialised -with GIT): +Repository initialisation/updating +---------------------------------- - stg init + To clone a repository (all the GIT repository types are accepted): -To add/delete files: + stg clone - stg add [*] - stg rm [*] + To initialise an existing GIT repository to be used with StGIT (not + needed if the cloning was done using StGIT): -To inspect the tree status: + stg init - stg status + For people switching between multiple branches in the same + repository, the 'init' command needs to be run for all the branches + intended to be used with StGIT. -To get a diff between 2 revisions: + To pull the latest changes from the remote repository (defaulting to + the value in .git/branches/origin): - stg diff [-r rev1[:[rev2]]] + stg pull [ or 'origin'] -A revision name can be of the form '([patch]/[bottom | top]) | ' -If the patch name is not specified but '/' is passed, the topmost -patch is considered. If neither 'bottom' or 'top' follows the '/', the -whole patch diff is displayed (this does not include the local -changes). + The 'pull' command takes care of updating all the patches in the + stack so that they apply cleanly (the user is notified of the + possible conflicts). -Note than when the first patch is pushed to the stack, the current -HEAD is saved in the .git/refs/heads/base file for easy reference. +Stack manipulation +------------------ -To create/delete a patch: + To create/delete a patch: stg new - stg delete [] + stg delete -The 'new' command also sets the topmost patch to the newly created -one. + The 'new' command also sets the topmost patch to the newly created + one. -To push/pop a patch to/from the stack: + To automatically delete the empty patches: - stg push [] - stg pop [] + stg clean -Note that the 'push' command can apply any patch in the unapplied -list. This is useful if you want to reorder the patches. + To push/pop a patch to/from the stack: -To add the patch changes to the tree: + stg push [--all | ] + stg pop [--all | ] - stg refresh + Note that the 'push' command can apply any patch in the unapplied + list. This is useful if one wants to reorder the patches. If there + are conflicts, they need to be fixed and 'stg resolved' run. The + 'push' operation can also be reverted with 'stg push --undo'. + + To rename a patch: + + stg rename -To inspect the patches applied: + To import an existing GNU diff patch file (defaulting to the + standard input): + + stg import [] + + To inspect the stack status: stg series stg applied stg unapplied stg top -To export a patch series: + To export a patch series (or a range of patches): + + stg export [--range=[[:]]] [] - stg export [] + The 'export' command supports options to automatically number the + patches (-n) or add the '.diff' extension (-d). -The 'export' command supports options to automatically number the -patches (-n) or add the '.diff' extension (-d). + To e-mail a patch or range of patches: -StGIT does not yet provide support for cloning or pulling changes from -a different repository. Until this becomes available, run the -following commands: + stg mail [--to=...] (--all | --range=[[:]] | ) - stg pop -a - your-git-script-for-pulling-and-merging - stg push -a +Changes to the topmost patch +---------------------------- -You can also look in the TODO file for what's planned to be -implemented in the future. + Any modified file already under revision control will automatically + be included in the topmost patch. + To add/delete files to/from the topmost patch: -Directory Structure -------------------- + stg add [*] + stg rm [*] + + To inspect the tree status: + + stg status + + To get a diff between 2 revisions: + + stg diff [-r rev1[:[rev2]]] + + A revision name can be of the form '([patch]/[bottom | top]) | base + | ' If the patch name is not specified but '/' is passed, + the topmost patch is used. If neither 'bottom' nor 'top' follows the + '/', the whole patch diff is displayed (this does not include the + local changes). + + Note than when the first patch is pushed on the stack, the current + HEAD is saved in the .git/refs/heads/base file for easy reference to + the base of the stack. + + To save the tree changes to the current patch and the GIT + repository: + + stg refresh -.git/ - objects/ - ??/ + The 'refresh' command also allows the modification of the patch + description and the author/maintainer information. + To display the files modified by a patch (defaulting to the topmost + one): + + stg files [] + + To merge a GNU diff file (defaulting to the standard input) into the + topmost patch: + + stg fold [] + + This command supports a '--threeway' option which applies the patch + onto the bottom of the topmost one and performs a three-way merge. + + +Advanced Usage +============== + +Configuration file +------------------ + +StGIT tries to read the configuration options from the following +files: /etc/stgitrc, ~/.stgitrc and .git/stgitrc. The latter overrides +the options in the former files. If no file is found, the defaults are +used. + +An example configuration file with options description can be found in +the examples/ directory. Most users would probably only define the +'smtpserver' option used by the 'mail' command. + +The gitmergeonefile.py script does the three-way merging on individual +files using the tool specified by the 'merger' option. The user can +specify a smarter tool to be used. + +Templates +--------- + +The 'export' and 'mail' commands use templates for generating the +patch files or e-mails. The default templates are installed under +/share/stgit/templates/ and, combined with the extra options +available for the commands, should be enough for most users. The +template format uses the standard Python string formatting rules. The +variables available are shown in the the help message for the +commands. + +The 'mail' command can also send an initial e-mail for which there is +no default template. The /share/stgit/examples/firstmail.tmpl +file can be used as an example. + +A default description for new patches can be defined in the +.git/patchdescr.tmpl file. This is useful for things like +signed-off-by lines. + +Dealing with conflicts +---------------------- + +Pushing a patch on the stack can fail if the patch cannot be applied +cleanly. This usually happens if there are overlapping changes in the +tree, the patch depends on other patch which is not applied or if a +patch was not merged upstream in the exact form it was sent. + +The 'push' operation will stop after the first patch with +conflicts. The 'status' command shows the conflict files by marking +them with a 'C'. If the 'keeporig' options is set to 'yes' (the +default), the original files involved in the merge operations are left +in the tree as .older, .local and .remote for a +better analysis by the user. If 'diff3' is used as the merger (the +default), conflict markers can be found in the corresponding files as +well. + +Once the conflict is fixed, the 'resolved' command has to be run to +clear the conflict state. This command also removes the original files +involved in the merge for a given file. + +Merging two patches into one +---------------------------- + +There is no command to do this directly at the moment but one can +export the patch to be merged and use the 'stg fold' command on the +generated diff file. Assuming that the merged patch was not already +applied, the operation will succeed. Pushing the merged patch onto the +stack will result in an empty patch (StGIT notifying the user) that +can be safely deleted. + + +.git/ Directory Structure +========================= + +HEAD -> refs/heads/ +objects/ + ??/ + ... refs/ heads/ master - the master commit id @@ -119,18 +254,21 @@ refs/ unapplied - list of not-yet applied patches current - name of the topmost patch patch1/ - first - the initial id of the patch (used for log) bottom - the bottom id of the patch top - the top id of the patch + description - the patch description + authname - author's name + authemail - author's e-mail + commname - committer's name + commemail - committer's e-mail patch2/ + ... ... ... -HEAD -> refs/heads/ - A Bit of StGIT Patch Theory ---------------------------- +=========================== We assume that a patch is a diff between two nodes - bottom and top. A node is a commit SHA1 id or tree SHA1 id in the GIT terminology: