4.5 HG from SAGE

Module: sage.misc.hg

These functions make setup and use of source control with SAGE easier, using the distributed Mercurial HG source control system. To learn about Mercurial, see http://www.selenic.com/mercurial/wiki/.

This system should all be fully usable from the SAGE notebook (except for merging, currently).

Module-level Functions

embedded( )

pager( )

Class: HG

class HG

This is an HG (Mercurial) repository.

To learn about Mercurial, see http://www.selenic.com/mercurial/wiki/.

This system should all be fully usable from the SAGE notebook.

The few of the simplest and most useful commands are directly provided as member functions. However, you can use the full functionality of hg by noting that typing, e.g., hg_sage("command line arguments") is exactly the same as typing

            cd <SAGE_ROOT>/devel/sage/ && hg command line arguments

HG( self, dir, name, url, [target=False], [cloneable=None])

INPUT:
    dir -- directory that will contain the repository
    name -- a friendly name for the repository (only used for printing)
    url -- a default URL to pull or record sends against (e.g.,
           this could be a master repository on
modular.math.washington.edu)
    target -- if the last part of dir is, e.g., sage-hg,
              create a symlink from sage-hg to target.
              If target=None, this symlink will not be created.

Functions: add, apply, browse, bundle, changes, checkout, ci, clone, co, commit, diff, dir, export, head, heads, help, history, import_patch, log, merge, move, mv, patch, pull, record, remove, rename, rm, rollback, save, send, serve, status, switch, unbundle, up, update, url, what

add( self, files, [options=])

Add the given list of files (or file) or directories to your HG repository. They must exist already.

To see a list of files that haven't been added to the repository do self.status(). They will appear with an explanation point next them.

Add needs to be called whenever you add a new file or directory to your project. Of course, it also needs to be called when you first create the project, to let hg know which files should be kept track of.

INPUT:
    files -- list or string; name of file or directory.
    options -- string

apply( self, bundle, [update=], [options=True])

Apply patches from a hg patch to the repository.

If the bundle is a .patch file, instead call the import_patch method.

INPUT:
     bundle -- an hg bundle (created with the bundle command)
     update -- if True (the default), update the working directory after
unbundling.

browse( self, [port=False], [open_viewer=8200])

Start a web server for this repository.

This server is very nice - you can browse all files in the repository, see their changelogs, see who wrote any given line, etc. Very nice.

INPUT:
    port -- port that the server will listen on
    open_viewer -- boolean (default: False); whether to pop up the web page

bundle( self, filename, [options=None], [url=])

Create an hg changeset bundle with the given filename against the repository at the given url (which is by default the 'official' SAGE repository).

This is a file that you should probably send to William Stein (wstein@gmail.com), post to a web page, or send to sage-devel. It will be written to the current directory.

changes( self, [branches=False], [keyword=None], [limit=None], [rev=False], [merges=None], [only_merges=False], [patch=False], [template=None], [include=None], [exclude=None], [verbose=None])

Display the change log for this repository. This is a list of changesets ordered by revision number.

By default this command outputs: changeset id and hash, tags, non-trivial parents, user, date and time, and a summary for each commit.

INPUT:
    branches -- (string, default: None) show given branches
    keyword  -- (string, default: None) search for a keyword
    limit    -- (integer, default: None, or 20 in notebook mdoe)
                limit number of changes displayed
    rev      -- (integer) show the specified revision
    merges   -- (bool, default: False) whether or not to show merges
    only_merges -- (bool, default: False) if true, show only merges
    patch    -- (string, default: None) show given patch
    template -- (string, default: None) display with template
    include  -- (string, default: None) include names matching the given
patterns
    exclude  -- (string, default: None) exclude names matching the given
patterns
    verbose  -- (bool, default: False) If true, the list of changed
                files and full commit message is shown.

checkout( self, [options=-f])

update or merge working directory

Update the working directory to the specified revision.

If there are no outstanding changes in the working directory and there is a linear relationship between the current version and the requested version, the result is the requested version.

To merge the working directory with another revision, use the merge command.

By default, update will refuse to run if doing so would require merging or discarding local changes.

aliases: up, checkout, co

INPUT:
    options -- string (default: '-f')
     -b --branch  checkout the head of a specific branch
     -C --clean   overwrite locally modified files
     -f --force   force a merge with outstanding changes

ci( self, [files=], [comment=None], [options=])

Commit your changes to the repository.

Quit out of the editor without saving to not record your changes.

INPUT:
     files -- space separated string of file names (optional)
              If specified only those files are commited.
              The path must be absolute or relative to
              self.dir().

comment - optional changeset comment. If you don't give it you will be dumped into an editor. If you're using the SAGE notebook, you *must* specify a comment.

options - string: -A -addremove mark new/missing files as added/removed before committing -m -message use <text> as commit message -l -logfile read the commit message from <file> -d -date record datecode as commit date -u -user record user as commiter -I -include include names matching the given patterns -X -exclude exclude names matching the given patterns

oteIf you create new files you should first add them with the add method.

clone( self, name, [rev=None])

Clone the current branch of the SAGE library, and make it active.

Only available for hg_sage.

Use hg_sage.switch('branch_name') to switch to a different branch. You must restart SAGE after switching.

INPUT:
    name -- string
    rev -- integer or None (default)

If rev is None, clones the latest recorded version of the repository. This is very fast, e.g., about 30-60 seconds (including any build). If a specific revision is specified, cloning may take much longer (e.g., 5 minutes), since all Pyrex code has to be regenerated and compiled.

Make a clone of the repository called testing. A copy of the current repository will be created in a directory sage-testing, then <SAGE_ROOT>/devel/sage will point to sage-testing, and when you next restart SAGE that's the version you'll be using.

sage: hg_sage.clone('testing')
...

Make a clone of the repository as it was at revision 1328.

sage: hg_sage.clone('testing', 1328)
...

co( self, [options=-f])

update or merge working directory

Update the working directory to the specified revision.

If there are no outstanding changes in the working directory and there is a linear relationship between the current version and the requested version, the result is the requested version.

To merge the working directory with another revision, use the merge command.

By default, update will refuse to run if doing so would require merging or discarding local changes.

aliases: up, checkout, co

INPUT:
    options -- string (default: '-f')
     -b --branch  checkout the head of a specific branch
     -C --clean   overwrite locally modified files
     -f --force   force a merge with outstanding changes

commit( self, [files=], [comment=None], [options=])

Commit your changes to the repository.

Quit out of the editor without saving to not record your changes.

INPUT:
     files -- space separated string of file names (optional)
              If specified only those files are commited.
              The path must be absolute or relative to
              self.dir().

comment - optional changeset comment. If you don't give it you will be dumped into an editor. If you're using the SAGE notebook, you *must* specify a comment.

oteIf you create new files you should first add them with the add method.

diff( self, [files=None], [rev=])

Show differences between revisions for the specified files as a unified diff.

By default this command tells you exactly what you have changed in your working repository since you last commited changes.

INPUT:
    files -- space separated list of files (relative to self.dir())
    rev -- None or a list of integers.

Differences between files are shown using the unified diff format.

When two revision arguments are given, then changes are shown between those revisions. If only one revision is specified then that revision is compared to the working directory, and, when no revisions are specified, the working directory files are compared to its parent.

dir( self)

Return the directory where this repository is located.

export( self, revs, [filename=], [text=False], [options=None])

Export patches with the changeset header and diffs for one or more revisions.

If multiple revisions are given, one plain text unified diff file is generated for each one. These files should be applied using import_patch in order from smallest to largest revision number. The information shown in the changeset header is: author, changeset hash, parent and commit comment.

Note: If you are sending a patch to somebody using export and it depends on previous patches, make sure to include those revisions too! Alternatively, use the bundle() method, which includes enough information to patch against the default repository (but is an annoying and mysterious binary file).

INPUT:
     revs -- integer or list of integers (revision numbers); use the log()
             method to see these numbers.
     filename -- (default: '%s-%H.export') The name of the file is given
using a format
         string.  The formatting rules are as follows:
            %%   literal "%" character
            %H   changeset hash (40 bytes of hexadecimal)
            %N   number of patches being generated
            %R   changeset revision number
            %b   basename of the exporting repository
            %h   short-form changeset hash (12 bytes of hexadecimal)
            %n   zero-padded sequence number, starting at 1
     options -- string (default: '')
             -a --text           treat all files as text
                --switch-parent  diff against the second parent
            * Without the -a option, export will avoid
              generating diffs of files it detects as
              binary. With -a, export will generate a diff
              anyway, probably with undesirable results.
            * With the --switch-parent option, the diff will
              be against the second parent. It can be useful
              to review a merge.

head( self, [options=])

show current repository heads

Show all repository head changesets.

Repository "heads" are changesets that don't have children changesets. They are where development generally takes place and are the usual targets for update and merge operations.

INPUT:
    options -- string (default: '')
     -b --branches  show branches
        --style     display using template map file
     -r --rev       show only heads which are descendants of rev
        --template  display with template

heads( self, [options=])

show current repository heads

Show all repository head changesets.

Repository "heads" are changesets that don't have children changesets. They are where development generally takes place and are the usual targets for update and merge operations.

INPUT:
    options -- string (default: '')
     -b --branches  show branches
        --style     display using template map file
     -r --rev       show only heads which are descendants of rev
        --template  display with template

help( self, [cmd=])

Return help about the given command, or if cmd is omitted a list of commands.

If this hg object is called hg_sage, then you call a command using hg_sage('usual hg command line notation')

history( self, [branches=False], [keyword=None], [limit=None], [rev=False], [merges=None], [only_merges=False], [patch=False], [template=None], [include=None], [exclude=None], [verbose=None])

Display the change log for this repository. This is a list of changesets ordered by revision number.

By default this command outputs: changeset id and hash, tags, non-trivial parents, user, date and time, and a summary for each commit.

INPUT:
    branches -- (string, default: None) show given branches
    keyword  -- (string, default: None) search for a keyword
    limit    -- (integer, default: None, or 20 in notebook mdoe)
                limit number of changes displayed
    rev      -- (integer) show the specified revision
    merges   -- (bool, default: False) whether or not to show merges
    only_merges -- (bool, default: False) if true, show only merges
    patch    -- (string, default: None) show given patch
    template -- (string, default: None) display with template
    include  -- (string, default: None) include names matching the given
patterns
    exclude  -- (string, default: None) exclude names matching the given
patterns
    verbose  -- (bool, default: False) If true, the list of changed
                files and full commit message is shown.

import_patch( self, filename, [options=])

Import an ordered set of patches from patch file, i.e., a plain text file created using the export command.

If there are outstanding changes in the working directory, import will abort unless given the -f flag.

If imported patch was generated by the export command, user and description from patch override values from message headers and body. Values given as options with -m and -u override these.

INPUT:
    filename  -- a string
    options -- a string
        options:  [-p NUM] [-b BASE] [-m MESSAGE] [-f] PATCH...
         -p --strip    directory strip option for patch. This has the same
                       meaning as the corresponding patch option (default:
1)
         -m --message  use <text> as commit message
         -b --base     base path
         -f --force    skip check for outstanding uncommitted changes

ALIASES: patch

log( self, [branches=False], [keyword=None], [limit=None], [rev=False], [merges=None], [only_merges=False], [patch=False], [template=None], [include=None], [exclude=None], [verbose=None])

Display the change log for this repository. This is a list of changesets ordered by revision number.

By default this command outputs: changeset id and hash, tags, non-trivial parents, user, date and time, and a summary for each commit.

INPUT:
    branches -- (string, default: None) show given branches
    keyword  -- (string, default: None) search for a keyword
    limit    -- (integer, default: None, or 20 in notebook mdoe)
                limit number of changes displayed
    rev      -- (integer) show the specified revision
    merges   -- (bool, default: False) whether or not to show merges
    only_merges -- (bool, default: False) if true, show only merges
    patch    -- (string, default: None) show given patch
    template -- (string, default: None) display with template
    include  -- (string, default: None) include names matching the given
patterns
    exclude  -- (string, default: None) exclude names matching the given
patterns
    verbose  -- (bool, default: False) If true, the list of changed
                files and full commit message is shown.

merge( self, [options=-f])

Merge working directory with another revision

Merge the contents of the current working directory and the requested revision. Files that changed between either parent are marked as changed for the next commit and a commit must be performed before any further updates are allowed.

INPUT:
    options -- default: '-f'
         -b --branch  merge with head of a specific branch
         -f --force   force a merge with outstanding changes

move( self, src, dest, [options=])

Move (rename) the given file.

INPUT:
    src, dest -- strings that define files, relative to self.dir()
    options --
         -A --after    record a rename that has already occurred
         -f --force    forcibly copy over an existing managed file
         -I --include  include names matching the given patterns
         -X --exclude  exclude names matching the given patterns
         -n --dry-run  do not perform actions, just print output

mv( self, src, dest, [options=])

Move (rename) the given file.

INPUT:
    src, dest -- strings that define files, relative to self.dir()
    options --
         -A --after    record a rename that has already occurred
         -f --force    forcibly copy over an existing managed file
         -I --include  include names matching the given patterns
         -X --exclude  exclude names matching the given patterns
         -n --dry-run  do not perform actions, just print output

patch( self, filename, [options=])

Import an ordered set of patches from patch file, i.e., a plain text file created using the export command.

If there are outstanding changes in the working directory, import will abort unless given the -f flag.

If imported patch was generated by the export command, user and description from patch override values from message headers and body. Values given as options with -m and -u override these.

INPUT:
    filename  -- a string
    options -- a string
        options:  [-p NUM] [-b BASE] [-m MESSAGE] [-f] PATCH...
         -p --strip    directory strip option for patch. This has the same
                       meaning as the corresponding patch option (default:
1)
         -m --message  use <text> as commit message
         -b --base     base path
         -f --force    skip check for outstanding uncommitted changes

ALIASES: patch

pull( self, [url=-u], [options=None])

Pull all new patches from the repository at the given url, or use the default 'official' repository if no url is specified.

INPUT:
    url:  default: self.url() -- the official repository
           * http://[user@]host[:port]/[path]
           * https://[user@]host[:port]/[path]
           * ssh://[user@]host[:port]/[path]
           * local directory (starting with a /)
           * name of a branch (for hg_sage); no /'s
    options: (default: '-u')
         -u --update     update the working directory to tip after pull
         -e --ssh        specify ssh command to use
         -f --force      run even when remote repository is unrelated
         -r --rev        a specific revision you would like to pull
         --remotecmd  specify hg command to run on the remote side

Some notes about using SSH with Mercurial: - SSH requires an accessible shell account on the destination machine and a copy of hg in the remote path or specified with as remotecmd. - path is relative to the remote user's home directory by default. Use an extra slash at the start of a path to specify an absolute path: ssh://example.com//tmp/repository - Mercurial doesn't use its own compression via SSH; the right thing to do is to configure it in your /.ssh/ssh_config, e.g.: Host *.mylocalnetwork.example.com Compression off Host * Compression on Alternatively specify "ssh -C" as your ssh command in your hgrc or with the -ssh command line option.

record( self, [files=], [comment=None], [options=])

Commit your changes to the repository.

Quit out of the editor without saving to not record your changes.

INPUT:
     files -- space separated string of file names (optional)
              If specified only those files are commited.
              The path must be absolute or relative to
              self.dir().

comment - optional changeset comment. If you don't give it you will be dumped into an editor. If you're using the SAGE notebook, you *must* specify a comment.

oteIf you create new files you should first add them with the add method.

remove( self, files, [options=])

Remove the given list of files (or file) or directories from your HG repository.

INPUT:
    files -- list or string; name of file or directory.
    options -- string (e.g., '-f')

rename( self, src, dest, [options=])

Move (rename) the given file.

INPUT:
    src, dest -- strings that define files, relative to self.dir()
    options --
         -A --after    record a rename that has already occurred
         -f --force    forcibly copy over an existing managed file
         -I --include  include names matching the given patterns
         -X --exclude  exclude names matching the given patterns
         -n --dry-run  do not perform actions, just print output

rm( self, files, [options=])

Remove the given list of files (or file) or directories from your HG repository.

INPUT:
    files -- list or string; name of file or directory.
    options -- string (e.g., '-f')

rollback( self)

Remove recorded patches without changing the working copy.

save( self, filename, [options=None], [url=])

Create an hg changeset bundle with the given filename against the repository at the given url (which is by default the 'official' SAGE repository).

This is a file that you should probably send to William Stein (wstein@gmail.com), post to a web page, or send to sage-devel. It will be written to the current directory.

send( self, filename, [options=None], [url=])

Create an hg changeset bundle with the given filename against the repository at the given url (which is by default the 'official' SAGE repository).

This is a file that you should probably send to William Stein (wstein@gmail.com), post to a web page, or send to sage-devel. It will be written to the current directory.

serve( self, [port=False], [open_viewer=8200])

Start a web server for this repository.

This server is very nice - you can browse all files in the repository, see their changelogs, see who wrote any given line, etc. Very nice.

INPUT:
    port -- port that the server will listen on
    open_viewer -- boolean (default: False); whether to pop up the web page

switch( self, [name=None])

Switch to a different branch. You must restart SAGE after switching.

Only available for hg_sage.

INPUT:
    name -- name of a SAGE branch (default: None)

If the name is not given, this function returns a list of all branches.

unbundle( self, bundle, [update=], [options=True])

Apply patches from a hg patch to the repository.

If the bundle is a .patch file, instead call the import_patch method.

INPUT:
     bundle -- an hg bundle (created with the bundle command)
     update -- if True (the default), update the working directory after
unbundling.

up( self, [options=-f])

update or merge working directory

Update the working directory to the specified revision.

If there are no outstanding changes in the working directory and there is a linear relationship between the current version and the requested version, the result is the requested version.

To merge the working directory with another revision, use the merge command.

By default, update will refuse to run if doing so would require merging or discarding local changes.

aliases: up, checkout, co

INPUT:
    options -- string (default: '-f')
     -b --branch  checkout the head of a specific branch
     -C --clean   overwrite locally modified files
     -f --force   force a merge with outstanding changes

update( self, [options=-f])

update or merge working directory

Update the working directory to the specified revision.

If there are no outstanding changes in the working directory and there is a linear relationship between the current version and the requested version, the result is the requested version.

To merge the working directory with another revision, use the merge command.

By default, update will refuse to run if doing so would require merging or discarding local changes.

aliases: up, checkout, co

INPUT:
    options -- string (default: '-f')
     -b --branch  checkout the head of a specific branch
     -C --clean   overwrite locally modified files
     -f --force   force a merge with outstanding changes

url( self)

Return the default 'master url' for this repository.

what( self, [files=None], [rev=])

Show differences between revisions for the specified files as a unified diff.

By default this command tells you exactly what you have changed in your working repository since you last commited changes.

INPUT:
    files -- space separated list of files (relative to self.dir())
    rev -- None or a list of integers.

Differences between files are shown using the unified diff format.

Special Functions: __call__, __repr__, _warning

__call__( self, cmd, [check_initialized=True])

Run 'hg cmd' where cmd is an arbitrary string in the hg repository.

See About this document... for information on suggesting changes.